List tags

Endpoint

GET /organizations/{org_id}/tags

Retrieves all tags in the specified organization.

Request

Replace {org_id} with your Organization ID.

Headers

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

Query parameters (optional)

• q (string) - Search by tag name.
• with (string) - Include related data. Supported value: statistics.
• all (string) - Set to true to include auto-generated process tags, which aren’t returned by default.
• per_page (integer) - Tags per page. Defaults to 10.
• page (integer) - Page number for pagination.
• sort (string) - Sort by a property. Prefix with - for descending order.

Code samples

Javascript

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

const queryParams = '?with=statistics&page=1&per_page=10';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/tags${queryParams}`;

const headers = {
  'Authorization': `Bearer ${accessToken}`,
  'Accept': 'application/json',
  '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('Tags:', JSON.stringify(data, null, 2));
    // Pagination info at data.meta.pagination
  })
  .catch(error => console.error('Failed to list tags:', 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')
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/tags'

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

params = {
    'q': 'Project',       # Search tags containing "Project"
    'with': 'statistics',
    'per_page': 10
}

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

tags_data = response.json()
print(json.dumps(tags_data, indent=4))
# Pagination: tags_data['meta']['pagination']

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 ListTags {
    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 baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/tags";

        Map<String, String> params = Map.of("with", "statistics", "per_page", "10");
        String query = params.entrySet().stream()
            .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "=" +
                      URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .reduce((a, b) -> a + "&" + b).map(s -> "?" + s).orElse("");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + query))
                .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("Tags: " + 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" }
  baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/tags", orgId)

  params := url.Values{}
  params.Add("with", "statistics")
  params.Add("per_page", "10")
  apiUrl := baseURL + "?" + params.Encode()

  client := &http.Client{Timeout: 15 * 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, 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;

pplx::task<void> ListTags() {
    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("tags"));
    builder.append_query(U("with"), U("statistics"));
    builder.append_query(U("per_page"), U("10"));

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

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

int main() {
    try { ListTags().wait(); }
    catch (const std::exception &e) { std::cerr << 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;

public class TallyfyTagLister
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task ListTagsAsync()
    {
        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"] = "statistics";
        query["per_page"] = "10";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/tags?{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

You’ll get a 200 OK response with a JSON object containing a data array of tags and meta pagination info.

Each tag object contains these fields from the TagTransformer: id, title (max 30 chars), color, auto_generated, created_at, and deleted_at.

If you’ve requested with=statistics, each tag also includes a nested statistics object with: active_template, archived_template, active_process, and archived_process counts.

{
  "data": [
    {
      "id": "tag_id_abc",
      "title": "Urgent",
      "color": "#e74c3c",
      "auto_generated": false,
      "created_at": "2025-01-15T10:00:00Z",
      "deleted_at": null,
      "statistics": {
        "data": {
          "active_template": 5,
          "archived_template": 2,
          "active_process": 12,
          "archived_process": 3
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 25,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 3
    }
  }
}

---

Related articles

Tags > Get tag

Retrieve a specific tag by its ID using a GET request to…

Code Samples > Managing tags

Tallyfy’s Tags API allows you to create and manage organization-scoped labels with unique titles…

Groups > List groups

Retrieve a paginated list of all groups in your Tallyfy organization. Filter by name, sort…

Templates > List templates

Retrieve a paginated list of process templates from your Tallyfy organization using the API…

Was this helpful?

YesNo