Skip to content
Tallyfy

List process tasks

Endpoint

GET /organizations/{org_id}/runs/{run_id}/tasks

This endpoint retrieves a list of all Tallyfy tasks specifically associated with a single process instance (run).

Request

Replace {org_id} with your Organization ID and {run_id} with the ID of the specific process run whose tasks you want to list.

Headers

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

Query parameters (optional)

Similar filtering parameters as listing organization tasks are available, but scoped to this process run. Refer to Swagger.

  • status (string): Filter by task status within this run (e.g., complete, active, incomplete, inprogress, not-started, hasproblem, overdue, due_soon). Note: auto-skipped may also appear for tasks hidden by rules.
  • owners (string): Comma-separated User IDs.
  • guests (string): Comma-separated Guest emails.
  • groups (string): Comma-separated Group IDs.
  • unassigned (boolean): Filter for unassigned tasks in this run.
  • deadline_start_range / deadline_end_range (string): Filter by deadline.
  • with (string): Include related data (e.g., step, threads, assets, form_fields, summary).
  • page, per_page (integer): Pagination.
  • sort (string): Sort by position, deadline (or -position, -deadline).
  • without_pagination (boolean).

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const runId = 'PROCESS_RUN_ID'; // ID of the specific process run


const params = new URLSearchParams({
    // status: 'incomplete', // Example: Get only incomplete tasks for this run
    with: 'step,form_fields', // Example: Include step and form field details
    per_page: '50' // Example: Get up to 50 tasks per page
});
const queryStr = params.toString();
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/runs/${runId}/tasks${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 tasks for process ${runId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully listed tasks for process ${runId}:`);
    console.log(JSON.stringify(data, null, 2));
    // Access pagination: data.meta.pagination
})
.catch(error => {
    console.error(`Error listing tasks for process ${runId}:`, error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing a data array of tasks specific to that process run, and a meta object for pagination.

{
  "data": [
    {
      "id": "task_id_1",
      "increment_id": 1210,
      "title": "Welcome Call",
      "run_id": "PROCESS_RUN_ID",
      "step_id": "step_id_welcome",
      "status": "active",
      "position": 1,
      "owners": { ... },
      "deadline": "2025-05-28T17:00:00Z",
      // ... other task properties ...
      // Included if requested via 'with=step':
      "step": {
          "id": "step_id_welcome",
          "title": "Schedule Welcome Call",
          "alias": "welcome_call",
          // ... other step details ...
      }
    },
    {
      "id": "task_id_2",
      "increment_id": 1211,
      "title": "Setup Account",
      "run_id": "PROCESS_RUN_ID",
      "step_id": "step_id_setup",
      "status": "not-started",
      "position": 2,
      // ...
    }
    // ... more tasks from this process run ...
  ],
  "meta": {
    "pagination": { ... }
  }
}

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.

Processes > List processes

This documentation explains how to retrieve and filter process instances within a Tallyfy organization using a GET API endpoint that supports various query parameters for searching by status owners templates tags and other criteria with code examples in multiple programming languages including JavaScript Python Java Go C++ and C#.

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.

Tasks > Get task

This API endpoint retrieves complete details for a specific Tallyfy task by its unique ID and supports optional query parameters to include related data like process run information and form fields while returning a JSON response containing task properties such as title status owners and deadline.
Get in touch
About Tallyfy