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, 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';


const params = new URLSearchParams({
    status: 'active', // Get active tasks
    // unassigned: 'true', // Get only unassigned tasks
    // owners: '1001,1002',
    per_page: '20'
});
const queryStr = params.toString();
const apiUrl = `https://api.tallyfy.com/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 => {
    if (!response.ok) {
        // Error handling...
        return response.json().then(errData => { throw new Error(/*...*/); }).catch(() => { throw new Error(/*...*/); });
    }
    return response.json();
})
.then(data => {
    console.log('Successfully listed organization tasks:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error listing organization tasks:', error);
});

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 (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": { ... }
  }
}
Get in touch
About Tallyfy