Skip to content

List processes

Endpoint

GET /organizations/{org_id}/runs

This endpoint retrieves a list of process instances (runs) within the specified organization. It supports various filters 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 the 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": "2024-05-18T10:00:00.000Z",
      "last_updated": "2024-05-20T15:30:00.000Z",
      "due_date": "2024-06-18T10: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

The GET endpoint retrieves all tasks linked to a specific process run with customizable filtering options headers and query parameters while supporting multiple programming languages for implementation.

Processes > Get process

An API endpoint that retrieves detailed information about a specific process run through a GET request with optional parameters to include related data like checklists tasks and tags in the response.

Tasks > List organization tasks

A comprehensive API endpoint documentation explaining how to retrieve and filter organization-wide tasks using GET requests with various query parameters and code examples in multiple programming languages.

Templates > List templates

An API endpoint documentation for retrieving process templates from organizations with code examples in JavaScript Python Java and Go along with details about request headers query parameters and response format.
Get in touch
About Tallyfy