Skip to content
Tallyfy

List organization tasks

Endpoint

GET /organizations/{org_id}/tasks

This endpoint retrieves a list of all Tallyfy 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": "YYYY-MM-DDTHH:MM:SSZ",
      "created_at": "YYYY-MM-DDTHH:MM:SSZ",
      // ... 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

This endpoint retrieves all tasks belonging to a specific process run by providing the organization ID and run ID with optional query parameters for filtering by status owners deadlines and sorting while returning paginated results containing task details like title position status and related step information.

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#.

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.

Tags > List tags

This endpoint retrieves all tags within an organization by making a GET request with optional query parameters for searching filtering and pagination while returning tag details like ID title color usage counts and creation timestamps in a JSON response.
Get in touch
About Tallyfy