List process tasks

Endpoint

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

This endpoint retrieves a list of all tasks specifically associated with a single process instance (run).

Request

Replace {org_id} with your Organization ID and {run_id} with the ID of the specific process run whose tasks you want to list.

Headers

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

Query parameters (optional)

Similar filtering parameters as listing organization tasks are available, but scoped to this process run. Refer to Swagger.

• status (string): Filter by task status within this run (e.g., complete, active, incomplete, inprogress, not-started, hasproblem, overdue, due_soon). Note: auto-skipped may also appear for tasks hidden by rules.
• owners (string): Comma-separated User IDs.
• guests (string): Comma-separated Guest emails.
• groups (string): Comma-separated Group IDs.
• unassigned (boolean): Filter for unassigned tasks in this run.
• deadline_start_range / deadline_end_range (string): Filter by deadline.
• with (string): Include related data (e.g., step, threads, assets, form_fields, summary).
• page, per_page (integer): Pagination.
• sort (string): Sort by position, deadline (or -position, -deadline).
• without_pagination (boolean).

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const runId = 'PROCESS_RUN_ID'; // ID of the specific process run

const params = new URLSearchParams({
    // status: 'incomplete', // Example: Get only incomplete tasks for this run
    with: 'step,form_fields', // Example: Include step and form field details
    per_page: '50' // Example: Get up to 50 tasks per page
});
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 => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to list tasks for process ${runId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully listed tasks for process ${runId}:`);
    console.log(JSON.stringify(data, null, 2));
    // Access pagination: data.meta.pagination
})
.catch(error => {
    console.error(`Error listing tasks for process ${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' # ID of the specific process run
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'
}

# Optional: Add query parameters
params = {
     'status': 'active', # Example: Get only active tasks in this run
    'with': 'step,form_fields', # Example: Include step and form field details
    'sort': 'position' # Example: Order tasks by their position in the process
}

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(f'Successfully listed tasks for process {run_id}:')
    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 process tasks for run {run_id}: {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 process tasks for run {run_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response when listing tasks for run {run_id}")
    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 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"; // ID of the specific process run
        String baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/runs/" + runId + "/tasks";

        // Optional: Add query parameters
        Map<String, String> queryParamsMap = new HashMap<>();
        // queryParamsMap.put("status", "incomplete");
        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("Successfully listed tasks for process " + runId + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON response using Jackson/Gson
            } else {
                System.err.println("Failed to list tasks for process " + runId + ". 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" }
    runId := "PROCESS_RUN_ID" // ID of the specific process run
  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/runs/%s/tasks", orgId, runId)

    // Optional: Add query parameters
    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 list process tasks 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 list process tasks request for run %s: %v\n", runId, err)
        return
    }
  defer resp.Body.Close()

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

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

  fmt.Printf("Successfully listed tasks for process %s:\n", runId)
    // 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 a slice of task structs 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> ListTallyfyProcessTasks(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")); // Example query parameters
    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"Successfully listed tasks for process " << runIdW << L":\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 tasks for process " << runIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during list process tasks: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during list process tasks response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        ListTallyfyProcessTasks(U("PROCESS_RUN_ID")).wait(); // Replace with actual Run ID
    } 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 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";

        // Build URL with query parameters
        var query = HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "step,form_fields"; // Example
        query["sort"] = "position";
        // query["status"] = "active";
        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($"Successfully listed tasks for process {runId}:");
                // 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 tasks for process {runId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception listing process tasks for run {runId}: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

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

Response

A successful request returns a 200 OK status code and a JSON object containing a data array of tasks specific to that process run, and a meta object for pagination.

{
  "data": [
    {
      "id": "task_id_1",
      "increment_id": 1210,
      "title": "Welcome Call",
      "run_id": "PROCESS_RUN_ID",
      "step_id": "step_id_welcome",
      "status": "active",
      "position": 1,
      "owners": { ... },
      "deadline": "2024-05-28T17:00:00Z",
      // ... other task properties ...
      // Included if requested via 'with=step':
      "step": {
          "id": "step_id_welcome",
          "title": "Schedule Welcome Call",
          "alias": "welcome_call",
          // ... other step details ...
      }
    },
    {
      "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,
      // ...
    }
    // ... more tasks from this process run ...
  ],
  "meta": {
    "pagination": { ... }
  }
}

---

Related articles

Tasks > List organization tasks

A comprehensive API endpoint documentation explaining how to retrieve and filter organization-wide tasks using GET requests with various query parameters and code examples in multiple programming languages.

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.

Processes > Get process

An API endpoint that retrieves detailed information about a specific process run through a GET request with optional parameters to include related data like checklists tasks and tags in the response.

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.