Skip to content

List process tasks

Endpoint

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

This endpoint retrieves a list of all 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": "2024-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 and filters tasks across processes within an organization offering extensive customization through query parameters and returns detailed task information with pagination support.

Processes > List processes

The GET endpoint retrieves process instances within organizations supporting extensive filtering options through query parameters and providing paginated results with detailed run information.

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 > Get task

A GET endpoint retrieves detailed task information including status owners deadlines and form fields through unique organization and task IDs with support for optional related data inclusion in multiple programming languages.