Skip to content

List organization tasks

Endpoint

GET /organizations/{org_id}/tasks

This endpoint retrieves a list of all tasks across all processes and one-off tasks within the specified organization. It offers extensive filtering capabilities.

Request

Replace {org_id} with your Organization ID.

Headers

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

Query parameters (optional)

Refer to the GET /organizations/{org}/tasks definition in Swagger for the full list. Key parameters include:

  • q (string): Search by process name or task name.
  • status (string): Filter by task status (e.g., complete, hasproblem, overdue, due_soon, active, incomplete, inprogress, not-started).
  • owners (string): Comma-separated list of User IDs to filter tasks assigned to any of these users.
  • guests (string): Comma-separated list of Guest emails.
  • roles (string): Comma-separated list of Role IDs.
  • groups (string): Comma-separated list of Group IDs.
  • tag (string): Filter by Tag name or ID.
  • folder (string): Filter tasks within a specific folder ID.
  • created (string): Filter by creation date (e.g., YYYY-MM-DD or YYYY-MM-DD:YYYY-MM-DD range).
  • deadline_start_range / deadline_end_range (string): Filter by deadline range (YYYY-MM-DD).
  • unassigned (boolean, e.g., unassigned=true): Retrieve only tasks with no assignees.
  • archived (boolean, e.g., archived=true): Include tasks from archived processes.
  • with (string): Include related data (e.g., run, run.checklist, step, threads, assets, [form_fields](/products/pro/tracking-and-tasks/tasks/what-are-form-fields-in-tallyfy/), tags).
  • page, per_page (integer): For pagination.
  • sort (string): Sort results (e.g., deadline, newest, problems, -deadline).
  • without_pagination (boolean, e.g., without_pagination=true): Retrieve all results without pagination (use with caution on large datasets).

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
// Construct query parameters
const params = new URLSearchParams({
status: 'active', // Example: Get active tasks
// unassigned: 'true', // Example: Get only unassigned tasks
// owners: '1001,1002', // Example: Tasks owned by user 1001 OR 1002
per_page: '20',
with: 'run' // Example: Include run information
});
const queryStr = params.toString();
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/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 organization tasks:", data);
throw new Error(`HTTP error! status: ${response.status}`);
}
return data; // Pass successful data along
});
})
.then(data => {
console.log('Successfully listed organization tasks:');
console.log(JSON.stringify(data, null, 2));
// Access pagination info via data.meta.pagination if needed
})
.catch(error => {
console.error('Error listing organization tasks:', error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing a data array of tasks and a meta object for pagination.

{
"data": [
{
"id": "task_id_abc",
"increment_id": 1205,
"title": "Review Proposal",
"summary": "Review the proposal document attached.",
"run_id": "run_id_xyz", // ID of the process this task belongs to (null for one-off tasks)
"step_id": "step_id_123", // ID of the [template step](/products/pro/tracking-and-tasks/tasks/) (null for one-off tasks)
"status": "active",
"owners": { // Assignees
"users": [
{ "id": 1001, "full_name": "Alice", "profile_pic": "..." }
],
"guests": [],
"groups": []
},
"deadline": "2024-05-25T17:00:00Z",
"created_at": "2024-05-20T10:00:00Z",
// ... other task properties (form fields if requested with 'with=form_fields') ...
},
// ... more tasks ...
],
"meta": {
// Pagination details similar to List Processes/Templates
"pagination": { ... }
}
}

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 > List processes

The GET endpoint retrieves and filters process instances within an organization providing paginated results with detailed run information task status and optional related data through various query parameters.

Tags > List tags

The GET endpoint allows retrieval of organizational tags with optional filtering and sorting capabilities returning tag details such as ID title color and usage statistics through authenticated API requests.

Tasks > Get task

A GET endpoint retrieves comprehensive task details including status owners deadlines and form fields through unique organization and task IDs with optional related data parameters.