List process tasks

Endpoint

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

Returns all tasks for a specific process run.

Request

Replace {org_id} with your Organization ID and {run_id} with the run ID whose tasks you want.

Headers

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

Query parameters (optional)

• status (string): Filter by task status - complete, active, active_visible, incomplete, inprogress, not-started, hasproblem, overdue, due_soon. Tasks hidden by rules appear with auto-skipped status in responses but can’t be used as a filter value.
• owners (string): Comma-separated User IDs.
• guests (string): Comma-separated Guest emails.
• groups (string): Comma-separated Group IDs.
• unassigned (boolean): Filter for unassigned tasks.
• deadline_start_range / deadline_end_range (string): Filter by deadline range.
• deadline_on (string): Filter tasks with deadline on an exact date (YYYY-MM-DD). Takes precedence over range filters.
• deadline_before / deadline_after (string): Filter tasks with deadline before or after a date (YYYY-MM-DD), exclusive.
• with (string): Include related data - step, threads, comments, assets, form_fields, activities, run, run.checklist, summary. Comma-separate multiple values.
• page, per_page (integer): Pagination controls. Default per_page is 10.
• sort (string): Sort by position, deadline (or -position, -deadline for descending).
• without_pagination (boolean): Set to true to return all results without pagination.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const runId = 'PROCESS_RUN_ID';

const params = new URLSearchParams({
    with: 'step,form_fields',
    per_page: '50'
});
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 => {
        if (!response.ok) {
            console.error(`Failed to list tasks for run ${runId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data;
    });
})
.then(data => {
    console.log(`Tasks for run ${runId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error listing tasks for run ${runId}:`, 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')
run_id = 'PROCESS_RUN_ID'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}/tasks'

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

params = {
    'status': 'active',
    'with': 'step,form_fields',
    'sort': 'position'
}

response = None
try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status()

    tasks_data = response.json()
    print(f'Tasks for run {run_id}:')
    print(json.dumps(tasks_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error listing tasks for run {run_id}: {http_err}")
    if response is not None:
        print(f"Response: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed for run {run_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON for run {run_id}")
    if response is not None:
        print(f"Response: {response.text}")

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;
import java.util.stream.Collectors;

public class ListProcessTasks {

    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 runId = "PROCESS_RUN_ID";
        String baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/runs/" + runId + "/tasks";

        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("with", "step");
        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("Tasks for run " + runId + ":");
                System.out.println(response.body());
            } else {
                System.err.println("Failed (status " + response.statusCode() + "): " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "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" }
  runId := "PROCESS_RUN_ID"
  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/runs/%s/tasks", orgId, runId)

  queryParams := url.Values{}
  queryParams.Add("status", "active")
  queryParams.Add("with", "step")
  queryParams.Add("sort", "position")

  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 request for run %s: %v\n", runId, 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 request for run %s: %v\n", runId, err)
    return
  }
  defer resp.Body.Close()

  body, err := io.ReadAll(resp.Body)
  if err != nil {
    fmt.Printf("Error reading response for run %s: %v\n", runId, err)
    return
  }

  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Failed (status %d): %s\n", resp.StatusCode, string(body))
    return
  }

  fmt.Printf("Tasks for run %s:\n", runId)
  var prettyJSON bytes.Buffer
  if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
    fmt.Println(prettyJSON.String())
  } else {
    fmt.Println(string(body))
  }
}

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> ListProcessTasks(const utility::string_t& runId)
{
    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("runs"));
    builder.append_path(runId);
    builder.append_path(U("tasks"));
    builder.append_query(U("with"), U("step,form_fields"));
    builder.append_query(U("sort"), U("position"));
    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([runId](http_response response)
    {
        utility::string_t runIdW = runId;
        return response.extract_json().then([response, runIdW](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Tasks for run " << runIdW << L":\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed (status " << response.status_code() << L"): " << body.serialize() << std::endl;
                }
            } catch (const std::exception& e) {
                std::wcerr << L"Error: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        ListProcessTasks(U("PROCESS_RUN_ID")).wait();
    } catch (const std::exception &e) {
        std::cerr << "Error: " << 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;

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

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

        var query = HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "step,form_fields";
        query["sort"] = "position";
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/runs/{runId}/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($"Tasks for run {runId}:");
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                } catch (JsonException) {
                    Console.WriteLine(responseBody);
                }
            }
            else
            {
                Console.WriteLine($"Failed (status {response.StatusCode}): {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error for run {runId}: {e.Message}");
        }
    }
}

Response

A 200 OK response returns a JSON object with a data array of tasks and a meta object for pagination.

{
  "data": [
    {
      "id": "task_id_1",
      "increment_id": 1210,
      "title": "Welcome Call",
      "run_id": "PROCESS_RUN_ID",
      "checklist_id": "template_id",
      "step_id": "step_id_welcome",
      "alias": "welcome_call",
      "status": "active",
      "position": 1,
      "owners": {
        "users": [...],
        "guests": [...],
        "groups": [...]
      },
      "deadline": "2025-05-28T17:00:00Z",
      "created_at": "2025-05-20T10:00:00Z",
      "last_updated": "2025-05-25T14:30:00Z",
      "completed_at": null,
      "task_type": "task",
      "is_oneoff_task": false,
      // Included when requesting with=step:
      "step": {
          "id": "step_id_welcome",
          "title": "Schedule Welcome Call"
      }
    },
    {
      "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
    }
  ],
  "meta": {
    "pagination": { ... }
  }
}

---

Related articles

Tasks > List organization tasks

Tallyfy’s API lets you retrieve and filter all tasks across an entire organization—including both process-based and one-off tasks—using a GET endpoint with extensive query parameters for status and deadline filtering and owner/guest/group assignment and sorting and pagination with code examples in six languages.

Processes > Get process

Tallyfy’s GET endpoint lets you retrieve full details of a specific process run by its ID and optionally include related data like tasks and form fields and tags through query parameters while also supporting a special “next_task” option that returns the earliest-deadline incomplete task for building dashboards or automating notifications.

Processes > List processes

Tallyfy’s API lets you retrieve a paginated and filterable list of all running process instances in your organization by calling GET on the runs endpoint with optional parameters for status and ownership and tags and sorting and related data inclusion.

Tasks > Get task

Tallyfy’s API lets you fetch any single task by its ID using a GET request and optionally include related data like form fields and process run details through query parameters.

Was this helpful?

YesNo