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

Javascript

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

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_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))

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

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_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())
}

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;

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)

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 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.

---

Related articles

Tasks > Get task

Retrieve full details for a specific task by ID, with optional related data like the process run, form fields, step info, and tags.

Tasks > List process tasks

Retrieve all tasks for a specific process run with optional filters for status, owners, deadlines, and sorting - returning paginated results with task details like title, position, status, and related step information.

Processes > List processes

Retrieve and filter process instances in a Tallyfy organization using a GET API endpoint with query parameters for status, owners, templates, tags, and more - with code examples in JavaScript, Python, Java, Go, C++, and C#.

Templates > Get template

This endpoint retrieves complete details for a specific process template by its unique ID and supports optional query parameters to include related data like steps tags and form fields in the response.

Was this helpful?

YesNo