List processes

Endpoint

GET /organizations/{org_id}/runs

This endpoint returns a paginated list of process instances (runs) in your organization. It’s filterable by status, ownership, templates, and more.

Request

Replace {org_id} with your Organization ID.

Headers

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

Query parameters (optional)

q (string): Search processes by name.
status (string): Filter by status - active, complete, problem, issue, improvement, archived, delayed, or starred. A process gets the issue status while someone has an open process-level issue on it, and its tasks can’t change until the issue is resolved. The problem filter also returns issue processes, so dashboards built on it keep showing everything that needs attention. Each process in the response carries a has_open_issue boolean.
owners (string): Comma-separated User IDs to filter by process owner or task assignee.
checklist_id (string): Filter by the template ID used to launch the process. Alias: blueprint_id.
folder (string): Filter by folder ID.
tag (string): Filter by a specific Tag ID.
tag_ids (string): Filter by comma-separated Tag IDs.
untagged (boolean): When set, returns only processes with no tags.
starred (boolean): Filter by starred status.
type (string): Filter by type - procedure or form.
groups (string): Comma-separated Group IDs involved in tasks within the process.
with (string): Comma-separated related data to include. Options: checklist, tasks, tags, assets, next_task, permissions, tasks_meta, ko_form_fields, form_fields, stages, folders.
page (integer): Page number to retrieve (default: 1).
per_page (integer): Results per page (default: 10).
sort (string): Field to sort by (e.g., name, created_at). Prefix with - for descending order (e.g., -created_at). Alias: sort_by.
without_pagination (boolean): When true, returns all results without pagination.

Code samples

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

const params = new URLSearchParams({
    status: 'active',
    per_page: '5'
});
const queryStr = params.toString();
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/runs${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 })
.then(response => {
    return response.json().then(data => {
        if (!response.ok) {
            console.error("Failed to list processes:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data;
    });
})
.then(data => {
    console.log('Successfully listed processes:');
    console.log(JSON.stringify(data, null, 2));
    // Pagination info: data.meta.pagination
})
.catch(error => {
    console.error('Error listing processes:', error.message);
});

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}/runs'

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

params = {
    'status': 'active',
    'per_page': 10,
    'page': 1,
    # 'q': 'ACME Corp',
    # 'with': 'tags,checklist'
}

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

    processes_data = response.json()
    print('Successfully listed processes:')
    print(json.dumps(processes_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error: {http_err}")
    if response is not None:
        print(f"Response: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed: {req_err}")
except Exception as err:
    print(f"Unexpected error: {err}")

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 ListProcesses {

    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 + "/runs";

        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("status", "active");
        queryParamsMap.put("per_page", "5");

        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 processes:");
                System.out.println(response.body());
            } else {
                System.err.println("Failed to list processes. Status: " + response.statusCode());
                System.err.println("Response: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        }
    }
}

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"
  }
  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/runs", orgId)

  queryParams := url.Values{}
  queryParams.Add("status", "active")
  queryParams.Add("per_page", "10")
  queryParams.Add("with", "tags")

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

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

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

  fmt.Println("Successfully listed processes:")
  var prettyJSON bytes.Buffer
  if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
    fmt.Println(prettyJSON.String())
  } else {
    fmt.Println(string(body))
  }
}

#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> ListTallyfyProcesses()
{
    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_query(U("status"), U("active")); // Example query parameter
    builder.append_query(U("per_page"), 5);
    builder.append_query(U("with"), U("tags"));
    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 processes:\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 processes. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during list processes: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during list processes response handling: " << e.what() << std::endl;
            }
        });
    });
}

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

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

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

    public static async Task ListProcessesAsync()
    {
        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["status"] = "active";
        query["per_page"] = "10";
        query["with"] = "tags";
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/runs?{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 processes:");
                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 to list processes. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
        }
    }
}

Response

You’ll get a 200 OK status and a JSON object with a data array. Each element represents a process run matching your filters.

{
  "data": [
    {
      "id": "run_id_abc",
      "increment_id": 5012,
      "checklist_id": "template_id_123",
      "checklist_title": "Customer Onboarding",
      "name": "Onboarding - ACME Corp",
      "summary": "",
      "status": "active",
      "progress": {
        "complete": 5,
        "total": 10,
        "percent": 50
      },
      "whole_progress": { ... },
      "started_by": 1001,
      "owner_id": 1001,
      "prerun": { ... },
      "prerun_status": "complete",
      "starred": false,
      "created_at": "2025-01-15T10:00:00.000Z",
      "started_at": "2025-01-15T10:00:00.000Z",
      "last_updated": "2025-01-17T15:30:00.000Z",
      "archived_at": null,
      "completed_at": null,
      "due_date": "2025-02-15T10:00:00.000Z",
      "due_date_passed": false,
      "due_soon": false,
      "late_tasks": 0,
      "collaborators": [],
      "type": "procedure",
      "is_public": false,
      "users": [],
      "groups": [],
      "parent_id": null,
      "can_add_oot": true
    }
  ],
  "meta": {
    "pagination": {
      "total": 55,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 6,
      "links": {
        "next": "https://go.tallyfy.com/api/organizations/{org_id}/runs?status=active&per_page=10&page=2"
      }
    }
  }
}

The meta.pagination object helps you page through results. You’ll find the next page URL in links.next.

Tasks > List process tasks

Retrieve all tasks for a specific process run through Tallyfy’s API. Filter by status, deadline…

Templates > List templates

Retrieve a paginated list of process templates from your Tallyfy organization using the API…

Processes > Get process

Retrieve full details of a specific process run by ID, with optional related data like tasks…

Code Samples > Managing processes (runs)

Use the Tallyfy API to manage processes (runs) through org-scoped endpoints. Launch, list…

Was this helpful?

Get in touch

About Tallyfy