Skip to content
Tallyfy

List processes

Endpoint

GET /organizations/{org_id}/runs

This endpoint retrieves a list of Tallyfy process instances (runs) within your organization. It supports extensive filtering through query parameters.

Request

Replace {org_id} with your actual Organization ID.

Headers

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

Query parameters (optional)

This endpoint offers several parameters to filter Tallyfy process results. Refer to the GET /organizations/{org}/runs definition in Swagger for the full list. Common parameters include:

  • q (string): Search term for process name.
  • status (string): Filter by status (e.g., active, problem, delayed, complete, archived).
  • owners (string): Comma-separated list of User IDs to filter by process owner.
  • checklist_id (string): Filter processes launched from a specific template ID.
  • folder (string): Filter processes within a specific folder ID.
  • tag (string): Filter processes by a specific Tag ID.
  • starred (boolean): Filter by starred status.
  • type (string): Filter by type (e.g., procedure, form).
  • groups (string): Comma-separated list of Group IDs involved in tasks within the process.
  • task_status (string): Filter processes based on the status of tasks within them (e.g., in-progress, completed).
  • with (string): Comma-separated list to include related data (e.g., checklist, tasks, tags, assets).
  • page (integer): For pagination, the page number to retrieve (default: 1).
  • per_page (integer): For pagination, the number of results per page (default: 10).
  • sort (string): Field to sort by (e.g., name, created_at, -created_at for descending).

Code samples

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


// Construct query parameters
const params = new URLSearchParams({
    status: 'active', // Example: Get only active processes
    // q: 'Onboarding', // Example: Search for name containing "Onboarding"
    // checklist_id: 'template_id_example',
    per_page: '5' // Example: Limit to 5 results per page
});
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: headers
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error("Failed to list processes:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Successfully listed processes:');
    console.log(JSON.stringify(data, null, 2));
    // Access pagination info via data.meta.pagination if needed
})
.catch(error => {
    console.error('Error listing processes:', error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing a data array. Each element in the array represents a process run matching the filter criteria.

{
  "data": [
    {
      "id": "run_id_abc",
      "increment_id": 5012,
      "checklist_id": "template_id_123",
      "checklist_title": "Customer Onboarding",
      "name": "Onboarding - ACME Corp",
      "summary": "Process instance for ACME.",
      "status": "active",
      "progress": {
        "complete": 5,
        "total": 10,
        "percent": 50
      },
      "started_by": 1001,
      "created_at": "2025-01-15T10:00:00.000Z",
      "last_updated": "2025-01-17T15:30:00.000Z",
      "due_date": "2025-02-15T10:00:00.000Z",
      "owner_id": 1001,
      // ... other run properties ...
    },
    {
      "id": "run_id_def",
      // ... details for another process run ...
    }
  ],
  "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 provides details for navigating through multiple pages of results if applicable.

Tasks > List process tasks

This endpoint retrieves all tasks belonging to a specific process run by providing the organization ID and run ID with optional query parameters for filtering by status owners deadlines and sorting while returning paginated results containing task details like title position status and related step information.

Tasks > List organization tasks

The GET endpoint retrieves all tasks across an organization’s processes and one-off tasks with extensive filtering options including status assignees deadlines tags folders and pagination while supporting multiple programming languages through code samples that demonstrate query parameter construction and response handling.

Templates > List templates

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

Processes > Get process

This API endpoint retrieves complete details about a specific Tallyfy process run using its unique ID and supports optional query parameters to include related data like tasks and form field values along with a special next_task parameter that returns the first visible incomplete task in the process.
Get in touch
About Tallyfy