Skip to content
Tallyfy

List processes

Endpoint

GET /organizations/{org_id}/runs

This endpoint returns a paginated list of process instances (runs) in your organization, with filters for status, ownership, templates, and more.

Request

Replace {org_id} with your Organization ID.

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient

Query parameters (optional)

  • q (string): Search processes by name.
  • status (string): Filter by status - active, complete, problem, improvement, archived, delayed, or starred.
  • owners (string): Comma-separated User IDs to filter by process owner or task assignee.
  • checklist_id (string): Filter by the template ID used to launch the process. Alias: blueprint_id.
  • folder (string): Filter by folder ID.
  • tag (string): Filter by a specific Tag ID.
  • tag_ids (string): Filter by comma-separated Tag IDs.
  • untagged (boolean): When set, returns only processes with no tags.
  • starred (boolean): Filter by starred status.
  • type (string): Filter by type - procedure or form.
  • groups (string): Comma-separated Group IDs involved in tasks within the process.
  • with (string): Comma-separated related data to include. Options: checklist, tasks, tags, assets, next_task, permissions, tasks_meta, ko_form_fields, form_fields, stages, folders.
  • page (integer): Page number to retrieve (default: 1).
  • per_page (integer): Results per page (default: 10).
  • sort (string): Field to sort by (e.g., name, created_at). Prefix with - for descending order (e.g., -created_at). Alias: sort_by.
  • without_pagination (boolean): When true, returns all results without pagination.

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';


const params = new URLSearchParams({
    status: 'active',
    per_page: '5'
});
const queryStr = params.toString();
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/runs${queryStr ? '?' + queryStr : ''}`;


const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');


fetch(apiUrl, { method: 'GET', headers })
.then(response => {
    return response.json().then(data => {
        if (!response.ok) {
            console.error("Failed to list processes:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data;
    });
})
.then(data => {
    console.log('Successfully listed processes:');
    console.log(JSON.stringify(data, null, 2));
    // Pagination info: data.meta.pagination
})
.catch(error => {
    console.error('Error listing processes:', error.message);
});

Response

A successful request returns a 200 OK status and a JSON object with a data array. Each element represents a process run matching your filters.

{
  "data": [
    {
      "id": "run_id_abc",
      "increment_id": 5012,
      "checklist_id": "template_id_123",
      "checklist_title": "Customer Onboarding",
      "name": "Onboarding - ACME Corp",
      "summary": "",
      "status": "active",
      "progress": {
        "complete": 5,
        "total": 10,
        "percent": 50
      },
      "whole_progress": { ... },
      "started_by": 1001,
      "owner_id": 1001,
      "prerun": { ... },
      "prerun_status": "complete",
      "starred": false,
      "created_at": "2025-01-15T10:00:00.000Z",
      "started_at": "2025-01-15T10:00:00.000Z",
      "last_updated": "2025-01-17T15:30:00.000Z",
      "archived_at": null,
      "completed_at": null,
      "due_date": "2025-02-15T10:00:00.000Z",
      "due_date_passed": false,
      "due_soon": false,
      "late_tasks": 0,
      "collaborators": [],
      "type": "procedure",
      "is_public": false,
      "users": [],
      "groups": [],
      "parent_id": null,
      "can_add_oot": true
    }
  ],
  "meta": {
    "pagination": {
      "total": 55,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 6,
      "links": {
        "next": "https://go.tallyfy.com/api/organizations/{org_id}/runs?status=active&per_page=10&page=2"
      }
    }
  }
}

The meta.pagination object helps you page through results. Use the links.next URL to fetch the next page directly.

Tasks > List process tasks

Tallyfy’s API lets you retrieve all tasks for a specific process run via a GET request with optional filters for status and deadlines and owners and sorting and pagination along with the ability to include related data like form fields and step details in the response.

Templates > List templates

Tallyfy’s API lets you retrieve a paginated and filterable list of process templates (called “checklists” in the API) for your organization using a GET request with optional query parameters for searching by title and filtering by status or tags or owner along with code examples in JavaScript and Python and Java and Go and C++ and C#.

Code Samples > Managing processes (Runs)

The Tallyfy API manages processes (called “runs”) through org-scoped endpoints that cover launching from templates or as empty containers and listing and filtering and fetching details and updating and archiving and restoring and permanently deleting processes along with retrieving activity feeds for audit trails.

Processes > Get process

Tallyfy’s GET endpoint lets you retrieve full details of a specific process run by its ID and optionally include related data like tasks and form fields and tags through query parameters while also supporting a special “next_task” option that returns the earliest-deadline incomplete task for building dashboards or automating notifications.
Get in touch
About Tallyfy