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

Retrieve all tasks for a specific process run with optional filters for status, owners, deadlines, and sorting - returning paginated results with task details like title, position, status, and related step information.

Templates > List templates

This API endpoint retrieves process templates (called Checklists in the API) from an organization using a GET request with query parameters for filtering, pagination and search.

Tasks > List organization tasks

Retrieve all tasks across an organization’s processes and one-off tasks with filtering by status, assignees, deadlines, tags, folders and pagination.
Get in touch
About Tallyfy