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 allows retrieval of task lists associated with a specific process run through authorization headers and optional query parameters for filtering sorting and pagination functionality.

Processes > Get process

A GET endpoint retrieves detailed information about a specific process run using organization and run IDs with optional parameters to include related data such as checklists tasks tags and form field values.

Tasks > List organization tasks

The GET endpoint retrieves and filters tasks across processes within an organization offering extensive customization through query parameters and returns detailed task information with pagination support.

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