Get process

Endpoint

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

This endpoint retrieves the full details for a single Tallyfy process instance (run) identified by its unique ID.

Request

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

Headers

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

Query parameters (optional)

• with (string): A comma-separated list to include related data (e.g., checklist, tasks, tags, assets, next_task, tasks.step, tasks.threads, form_fields, ko_form_fields).
• form_fields_values (boolean, e.g., true): Include the values submitted to form fields.

Understanding with=next_task

When you include next_task in the with parameter, the API returns information about the next task that needs attention in the process.

What does next_task return?

• The first visible incomplete task ordered by position number
• Visible means not hidden/auto-skipped by automation rules
• Incomplete means not yet completed (includes tasks currently in-progress)
• Ordered by position means task 1, task 2, task 3, etc.
• Returns null if all tasks in the process are completed

When to use it:

• Determining which task to display to the user next
• Automating assignments or notifications for upcoming tasks
• Building custom dashboards that show current process status
• Integration logic that needs to know what’s pending

Example response snippet:

{
  "data": {
    "id": "run123",
    "name": "Customer Onboarding",
    "next_task": {
      "id": "task456",
      "title": "Review Application",
      "position": 3,
      "status": "not-started",
      "deadline": "2025-11-25T17:00:00Z"
    }
  }
}

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'; // Example: get related data and field values
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: headers
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to get process ${runId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully retrieved process ${runId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error getting 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_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'
}

# Optional: Add query parameters
params = {
    'with': 'checklist,tasks,tags,form_fields',
    'form_fields_values': 'true' # Include values entered into form fields
}

response = None
try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    process_data = response.json()
    print(f'Successfully retrieved process {run_id}:')
    print(json.dumps(process_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred getting process {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 getting process {run_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response for process {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.util.Map;
import java.util.HashMap; // Use HashMap for mutable map
import java.util.stream.Collectors;

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 baseUrl = String.format("https://go.tallyfy.com/api/organizations/%s/runs/%s", orgId, runId);

        // Optional: Add query parameters
        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("with", "checklist,tasks");
        queryParamsMap.put("form_fields_values", "true");

        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.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("Successfully retrieved process " + runId + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON using Jackson/Gson
            } else {
                System.err.println("Failed to get 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_TO_GET"
    baseUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/runs/%s", orgId, runId)

    // Optional: Add query parameters
    queryParams := url.Values{}
    queryParams.Add("with", "checklist,tasks,tags,form_fields")
    queryParams.Add("form_fields_values", "true")

    apiUrl := baseUrl
    if len(queryParams) > 0 {
         apiUrl += "?" + queryParams.Encode()
    }

  client := &http.Client{Timeout: 10 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
    if err != nil {
        fmt.Printf("Error creating get process 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 get process 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 get process response body for run %s: %v\n", runId, err)
        return
    }

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

  fmt.Printf("Successfully retrieved 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 struct 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> GetTallyfyProcess(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_query(U("with"), U("checklist,tasks,tags,form_fields")); // Example query parameters
    builder.append_query(U("form_fields_values"), U("true"));
    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 retrieved process " << runIdW << L":\n" << body.serialize() << std::endl;
                    // Access data: body[U("data")][U("name")].as_string();
                } else {
                    std::wcerr << L"Failed to get process " << runIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during get process: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during get process response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        GetTallyfyProcess(U("PROCESS_RUN_ID_TO_GET")).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 TallyfyProcessGetter
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task GetProcessAsync(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"] = "checklist,tasks,tags,form_fields"; // Example
        query["form_fields_values"] = "true";
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/runs/{runId}?{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 retrieved process {runId}:");
                // Pretty print JSON
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                    // Access data: doc.RootElement.GetProperty("data").GetProperty("name").GetString();
                } catch (JsonException) {
                    Console.WriteLine(responseBody); // Print raw if not valid JSON
                }
            }
            else
            {
                Console.WriteLine($"Failed to get process {runId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception getting process {runId}: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

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

Response

A successful request returns a 200 OK status code and a JSON object containing a data field with the process run’s details.

{
  "data": {
    "id": "PROCESS_RUN_ID_TO_GET",
    "increment_id": 5015,
    "checklist_id": "template_id_abc",
    "checklist_title": "Client Onboarding V3",
    "name": "Onboarding - Globex Corp",
    "summary": "New client onboarding process run.",
    "status": "active",
    "progress": { ... },
    "started_by": 1002,
    "owner_id": 1002,
    "created_at": "2025-05-20T11:00:00Z",
    "last_updated": "2025-05-21T09:30:00Z",
    "prerun": { // Kick-off form field values if filled
        "kickoff_field_id_1": "Globex Corporation",
        "kickoff_field_id_2": "2025-06-01T00:00:00Z"
    },
    // Included if requested with 'with=checklist'
    "checklist": { ... template details ... },
    // Included if requested with 'with=tasks'
    "tasks": [ { ... task details ... } ],
    // Included if requested with 'with=tags'
    "tags": [ { ... tag details ... } ]
    // ... other run properties ...
  }
}

If the run ID is not found or you lack permission, a 404 Not Found or 403 Forbidden error will be returned.

---

Related articles

Tasks > Get task

This API endpoint retrieves complete details for a specific Tallyfy task by its unique ID and supports optional query parameters to include related data like process run information and form fields while returning a JSON response containing task properties such as title status owners and deadline.

Tasks > List process tasks

This endpoint retrieves all tasks belonging to a specific process run by providing the organization ID and run ID with optional query parameters for filtering by status owners deadlines and sorting while returning paginated results containing task details like title position status and related step information.

Processes > List processes

This documentation explains how to retrieve and filter process instances within a Tallyfy organization using a GET API endpoint that supports various query parameters for searching by status owners templates tags and other criteria with code examples in multiple programming languages including 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