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

Javascript

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);
});

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/tasks'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient'
}

# Define query parameters
params = {
    'status': 'overdue', # Example: Get overdue tasks
    # 'unassigned': True, # Example: Get only unassigned tasks
    'per_page': 15,
    'sort': '-deadline', # Example: Sort by deadline descending
    'with': 'run,step' # Example: Include run and step details
}

response = None
try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    tasks_data = response.json()
    print('Successfully listed organization tasks:')
    print(json.dumps(tasks_data, indent=4))
    # Access pagination: tasks_data.get('meta', {}).get('pagination')

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred listing org tasks: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed listing org tasks: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response when listing org tasks")
    if response is not None:
        print(f"Response Text: {response.text}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Map;
import java.util.HashMap; // Use HashMap for mutable map
import java.util.stream.Collectors;

public class ListOrgTasks {

    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/tasks";

        // Define query parameters
        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("status", "active");
        queryParamsMap.put("per_page", "10");
        queryParamsMap.put("unassigned", "true"); // Example: Get unassigned active tasks
        queryParamsMap.put("with", "run"); // Example: Include run details
        // queryParamsMap.put("sort", "deadline");

        String queryParamsString = queryParamsMap.entrySet().stream()
            .map(entry -> URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&", "?", ""));

        String apiUrl = baseUrl + (queryParamsMap.isEmpty() ? "" : queryParamsString);

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .GET()
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.println("Successfully listed organization tasks:");
                System.out.println(response.body());
                // TODO: Consider parsing JSON response using Jackson/Gson
                // Access pagination: Use jsonNode.path("meta").path("pagination")
            } else {
                System.err.println("Failed to list organization tasks. Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
  if accessToken == "" { accessToken = "YOUR_PERSONAL_ACCESS_TOKEN" }
  orgId := os.Getenv("TALLYFY_ORG_ID")
  if orgId == "" { orgId = "YOUR_ORGANIZATION_ID" }
  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/tasks", orgId)

    // Define query parameters
    queryParams := url.Values{}
    queryParams.Add("status", "active")
    queryParams.Add("per_page", "5")
    queryParams.Add("unassigned", "true") // Example: Get unassigned tasks
    queryParams.Add("with", "run,step") // Example: Include run and step info
    // queryParams.Add("sort", "-deadline")

    apiUrl := baseURL
    if len(queryParams) > 0 {
        apiUrl += "?" + queryParams.Encode()
    }

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
    if err != nil {
        fmt.Printf("Error creating list org tasks request: %v\n", err)
        return
    }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")

  resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error executing list org tasks request: %v\n", err)
        return
    }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("Error reading list org tasks response body: %v\n", err)
        return
    }

  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Failed to list organization tasks. Status: %d\nBody: %s\n", resp.StatusCode, string(body))
    return
  }

  fmt.Println("Successfully listed organization tasks:")
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal JSON into structs, including meta/pagination if needed
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

pplx::task<void> ListTallyfyOrgTasks()
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");

    uri_builder builder(U("https://go.tallyfy.com/api/organizations/"));
    builder.append_path(orgId);
    builder.append_path(U("tasks"));
    builder.append_query(U("status"), U("active")); // Example query parameter
    builder.append_query(U("unassigned"), U("true"));
    builder.append_query(U("per_page"), 10);
    builder.append_query(U("with"), U("run"));
    utility::string_t apiUrl = builder.to_string();

    http_client client(apiUrl);
    http_request request(methods::GET);

    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));

    return client.request(request).then([](http_response response)
    {
        return response.extract_json().then([response](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully listed organization tasks:\n" << body.serialize() << std::endl;
                    // Access data: body[U("data")].as_array()
                    // Access pagination: body[U("meta")][U("pagination")]
                } else {
                    std::wcerr << L"Failed to list org tasks. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during list org tasks: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during list org tasks response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        ListTallyfyOrgTasks().wait();
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Text.Json;
using System.Web; // For HttpUtility

public class TallyfyOrgTaskLister
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task ListOrgTasksAsync()
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";

        // Build URL with query parameters
        var query = HttpUtility.ParseQueryString(string.Empty);
        query["status"] = "active"; // Example
        query["unassigned"] = "true";
        query["per_page"] = "20";
        query["with"] = "run,step"; // Example: Include run and step info
        // query["sort"] = "-deadline";
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/tasks?{queryString}";

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Get, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");

            HttpResponseMessage response = await client.SendAsync(request);
            string responseBody = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Successfully listed organization tasks:");
                // Pretty print JSON
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                    // Access pagination: doc.RootElement.GetProperty("meta").GetProperty("pagination")...
                } catch (JsonException) {
                    Console.WriteLine(responseBody); // Print raw if not valid JSON
                }
            }
            else
            {
                Console.WriteLine($"Failed to list organization tasks. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception listing org tasks: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await ListOrgTasksAsync();
    // }
}

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": { ... }
  }
}

---

Related articles

Tasks > List process tasks

The GET endpoint allows retrieval of task lists associated with a specific process run through authorization headers and optional query parameters for filtering sorting and pagination functionality.

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.

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.

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.