Get task

Endpoint

GET /organizations/{org_id}/tasks/{task_id}

Retrieves a single task by its ID. This works for both standalone (one-off) tasks and process tasks. For process tasks, you can also use GET /organizations/{org_id}/runs/{run_id}/tasks/{task_id}.

Request

Replace {org_id} with your Organization ID and {task_id} with the task’s unique 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: run, step, form_fields, tags, threads, issues, assets, folders, roles, activities, ko-form-fields, summary, member_watchers, guest_watchers, threads_count. Example: with=run,step,form_fields.

Code samples

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

const queryParams = '?with=run,step,form_fields,tags';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/tasks/${taskId}${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) {
            console.error(`Failed to get task ${taskId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data;
    });
})
.then(data => {
    console.log(`Successfully retrieved task ${taskId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error getting task ${taskId}:`, 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')
task_id = 'TASK_ID_TO_GET'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/tasks/{task_id}'

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

params = {
    'with': 'run,step,form_fields,tags'
}

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

    task_data = response.json()
    print(f'Successfully retrieved task {task_id}:')
    print(json.dumps(task_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error getting task {task_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 for task {task_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON for task {task_id}")
    if response is not None:
        print(f"Response Text: {response.text}")

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;
import java.util.stream.Collectors;

public class GetTask {

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

        Map<String, String> queryParamsMap = new HashMap<>();
        queryParamsMap.put("with", "run,step,form_fields");

        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 task " + taskId + ":");
                System.out.println(response.body());
            } else {
                System.err.println("Failed to get task " + taskId + ". Status: " + response.statusCode());
                System.err.println("Response Body: " + 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" }
  taskId := "TASK_ID_TO_GET"
  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/tasks/%s", orgId, taskId)

  // Optional: Add query parameters
  queryParams := url.Values{}
  queryParams.Add("with", "run,step,form_fields,tags")

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

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

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

  fmt.Printf("Successfully retrieved task %s:\n", taskId)
  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> GetTallyfyTask(const utility::string_t& taskId)
{
    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("tasks"));
    builder.append_path(taskId);
    builder.append_query(U("with"), U("run,step,form_fields,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([taskId](http_response response)
    {
        utility::string_t taskIdW = taskId;
        return response.extract_json().then([response, taskIdW](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully retrieved task " << taskIdW << L":\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to get task " << taskIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const std::exception& e) {
                std::wcerr << L"Exception getting task: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        GetTallyfyTask(U("TASK_ID_TO_GET")).wait();
    } catch (const std::exception &e) {
        std::cerr << "Error: " << 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 TallyfyTaskGetter
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task GetTaskAsync(string taskId)
    {
        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["with"] = "run,step,form_fields,tags";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/tasks/{taskId}?{query}";

        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 task {taskId}:");
                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 get task {taskId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request exception getting task {taskId}: {e.Message}");
        }
    }
}

Response

Returns a 200 OK with a JSON object containing a data field that holds the task’s full details.

{
  "data": {
    "id": "task_id_abc",
    "increment_id": 1205,
    "title": "Review Proposal",
    "run_id": "run_id_xyz",
    "checklist_id": "checklist_id_123",
    "step_id": "step_id_456",
    "alias": "review-proposal",
    "status": "active",
    "status_label": "Active",
    "task_type": "task",
    "is_oneoff_task": false,
    "is_completable": true,
    "is_approved": false,
    "owners": {
      "users": [1234],
      "guests": [],
      "groups": []
    },
    "position": 1,
    "started_at": "2025-01-10T09:00:00Z",
    "deadline": "2025-01-15T17:00:00Z",
    "created_at": "2025-01-10T09:00:00Z",
    "last_updated": "2025-01-12T14:30:00Z",
    "completed_at": null,
    "archived_at": null,
    "starter_id": 1234,
    "completer_id": null,
    "everyone_must_complete": false,
    "can_complete_only_assignees": true,
    "max_assignable": 1,
    "webhook": null,
    "top_secret": false,
    "form_fields": {
      "data": [
        {
          "id": "capture_id_abc",
          "label": "Approval Status",
          "field_type": "dropdown",
          "value": { "id": 1, "text": "Approved" },
          "required": true
        }
      ]
    },
    "run": { "data": { "...": "process run details" } },
    "step": { "data": { "...": "template step details" } }
  }
}

The form_fields, run, and step objects only appear when you request them via the with parameter. If the task isn’t found, you’ll get a 404. If you lack permission, expect a 403.

Processes > Get process

Tallyfy’s GET endpoint lets you retrieve full details of a specific process run by its ID and optionally include related data like tasks and form fields and tags through query parameters while also supporting a special “next_task” option that returns the earliest-deadline incomplete task for building dashboards or automating notifications.

Tags > Get tag

Tallyfy’s API lets you retrieve a specific tag by its ID using a GET request to /organizations/[org_id]/tags/[tag_id] and optionally include usage statistics showing how many active or archived templates and processes use that tag.

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.

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.

Was this helpful?

Get in touch

About Tallyfy