Get process

Endpoint

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

Retrieves full details for a single process (run) by its unique ID.

Request

Replace {org_id} with your Organization ID and {run_id} with the run’s ID.

Headers

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

Query parameters (optional)

with (string): Comma-separated list of related data to include. Options: checklist, tasks, tags, assets, next_task, permissions, tasks_meta, ko_form_fields, form_fields, stages, folders, member_watchers, guest_watchers. The controller also supports tasks.threads and tasks.form_fields for nested eager loading.
form_fields_values (boolean, e.g., true): Include values submitted to form fields across all tasks.

Understanding `with=next_task`

Including next_task returns the next task needing attention in the process.

What it returns:

The first incomplete task, sorted by deadline (earliest deadline first)
Incomplete means not yet completed — in-progress tasks are included
Auto-skipped tasks are excluded (they’re filtered from the tasks relationship)
Returns as a collection wrapper: "next_task": {"data": [...]}
Returns an empty collection if all tasks are completed

Fields returned per task: id, increment_id, title, alias, owners (with users, guests, groups arrays), and deadline.

When to use it:

Showing which task a user should work on next
Automating notifications for upcoming deadlines
Building dashboards that display current process state

Code samples

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

const queryParams = '?with=checklist,tasks,tags,form_fields&form_fields_values=true';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/runs/${runId}${queryParams}`;

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) throw new Error(`Error ${response.status}: ${JSON.stringify(data)}`);
        return data;
    });
})
.then(data => console.log('Process:', JSON.stringify(data, null, 2)))
.catch(error => console.error('Failed:', 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')
run_id = 'PROCESS_RUN_ID_TO_GET'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}'

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

params = {
    'with': 'checklist,tasks,tags,form_fields',
    'form_fields_values': 'true'
}

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

print(json.dumps(response.json(), indent=4))

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.util.Map;

public class GetProcess {
    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_TO_GET";

        String queryString = "?with=" + URLEncoder.encode("checklist,tasks", StandardCharsets.UTF_8)
            + "&form_fields_values=true";
        String apiUrl = String.format(
            "https://go.tallyfy.com/api/organizations/%s/runs/%s%s", orgId, runId, queryString);

        HttpClient client = HttpClient.newHttpClient();
        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("Process: " + response.body());
            } else {
                System.err.println("Error " + response.statusCode() + ": " + 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" }
  runId := "PROCESS_RUN_ID_TO_GET"

  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/runs/%s", orgId, runId)
  params := url.Values{}
  params.Add("with", "checklist,tasks,tags,form_fields")
  params.Add("form_fields_values", "true")
  apiURL := baseURL + "?" + params.Encode()

  client := &http.Client{Timeout: 10 * time.Second}
  req, _ := http.NewRequest("GET", apiURL, nil)
  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("Request error: %v\n", err); return }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Error %d: %s\n", resp.StatusCode, string(body))
    return
  }

  var out bytes.Buffer
  json.Indent(&out, body, "", "  ")
  fmt.Println(out.String())
}

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

int main() {
    auto accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    auto orgId = U("YOUR_ORGANIZATION_ID");
    auto runId = U("PROCESS_RUN_ID_TO_GET");

    uri_builder builder(U("https://go.tallyfy.com/api/organizations/"));
    builder.append_path(orgId).append_path(U("runs")).append_path(runId);
    builder.append_query(U("with"), U("checklist,tasks,tags,form_fields"));
    builder.append_query(U("form_fields_values"), U("true"));

    http_client client(builder.to_string());
    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"));

    client.request(request).then([](http_response response) {
        return response.extract_json().then([response](pplx::task<value> task) {
            auto body = task.get();
            if (response.status_code() == status_codes::OK)
                std::wcout << body.serialize() << std::endl;
            else
                std::wcerr << L"Error " << response.status_code()
                           << L": " << body.serialize() << std::endl;
        });
    }).wait();
    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 GetProcess
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task Main(string[] args)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";
        var runId = "PROCESS_RUN_ID_TO_GET";

        var query = HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "checklist,tasks,tags,form_fields";
        query["form_fields_values"] = "true";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/runs/{runId}?{query}";

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

        var response = await client.SendAsync(request);
        var body = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            using var doc = JsonDocument.Parse(body);
            Console.WriteLine(JsonSerializer.Serialize(doc.RootElement,
                new JsonSerializerOptions { WriteIndented = true }));
        }
        else
        {
            Console.WriteLine($"Error {response.StatusCode}: {body}");
        }
    }
}

Response

Returns 200 OK with the process run wrapped in a data object.

{
  "data": {
    "id": "run_id_abc",
    "increment_id": 5015,
    "checklist_id": "template_timeline_id",
    "checklist_title": "Client Onboarding V3",
    "name": "Onboarding - Globex Corp",
    "summary": "New client onboarding run.",
    "status": "active",
    "progress": { },
    "whole_progress": { },
    "started_by": 1002,
    "owner_id": 1002,
    "prerun": { },
    "prerun_status": "complete",
    "starred": false,
    "created_at": "2025-05-20T11:00:00Z",
    "started_at": "2025-05-20T11:00:00Z",
    "last_updated": "2025-05-21T09:30:00Z",
    "archived_at": null,
    "completed_at": null,
    "type": "procedure",
    "is_public": false,
    "users": [],
    "groups": [],
    "checklist": { },
    "tasks": { "data": [] },
    "tags": { "data": [] }
  }
}

Key fields: archived_at maps from the internal deleted_at column. started_by maps from the internal user_id. Included relationships like tasks, tags, and checklist only appear when you request them via with.

If the run isn’t found or you don’t have access, you’ll get a 404 or 403 error.

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.

Tasks > List process tasks

Tallyfy’s API lets you retrieve all tasks for a specific process run via a GET request with optional filters for status and deadlines and owners and sorting and pagination along with the ability to include related data like form fields and step details in the response.

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.

Templates > Get template

Tallyfy’s API lets you fetch full details of any process template by its unique ID using a GET request and optionally include related data like steps and tags through query parameters.

Was this helpful?

Get in touch

About Tallyfy