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-10-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": "2024-05-20T11:00:00Z",
    "last_updated": "2024-05-21T09:30:00Z",
    "prerun": { // Kick-off form field values if filled
        "kickoff_field_id_1": "Globex Corporation",
        "kickoff_field_id_2": "2024-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

A GET endpoint retrieves detailed task information including status owners deadlines and form fields through unique organization and task IDs with support for optional related data inclusion in multiple programming languages.

Tasks > List process tasks

The GET endpoint allows retrieval of task lists associated with a specific process run through authorization headers and optional query parameters for filtering sorting and pagination functionality.

Processes > List processes

The GET endpoint retrieves process instances within organizations supporting extensive filtering options through query parameters and providing paginated results with detailed run information.

Templates > Get template

An API endpoint that retrieves detailed information about a specific process template using a GET request with optional parameters to include related data such as steps tags and folder hierarchies.

Was this helpful?

YesNo