Aggregate Catalog

Every dataset, field, measure and limit POST /v1/aggregate accepts, generated from the definitions it checks against: types, filters, grouping, cost fields.

GET /v1/aggregate/catalog describes everything POST /v1/aggregate accepts. It is generated from the same definitions the endpoint uses to check requests, so a field listed here works and a field not listed here does not. It reads no workspace data, is not limited to one request at a time, and is safe to call on every dashboard start to build a query builder or to check names.

Each dataset carries a description that says what one row is and what count counts: for documents a row is a document, for pipeline_documents a row is a document in one pipeline and count counts distinct documents. kind is entity for rows created in the window and read as they are now, and event for rows written in the window that never change (model calls). document_scope says whether the request's scope applies, and defaults lists filters applied unless your query filters the same field, such as leaving out preview runs or replaced decisions.

Each field carries its type (text, uuid, bool, number or text[]), whether it can appear in group_by (groupable), the where operators it takes (ops), and whether it needs cost visibility (cost). Number fields can be measured with sum, avg, median and the percentiles; any field can be measured with count_distinct. True/false fields take eq and neq, not in, and tag lists take contains_any and contains_all.

limits lists the window length, the number of queries per request, the number of values a list filter may carry, how long one statement may run (statement_timeout_ms; a request runs one statement per dataset plus one per grouped query, so a whole request can take longer), and how many requests may run at once (concurrency: one per workspace, or per API process where the deployment does not share that limit). group_by lists the time buckets (hour, day, both UTC), how many grouping fields a query may name and how many groups come back. cost_visible says whether your workspace may read fields marked cost.

{
  "datasets": [
    {
      "name": "documents",
      "description": "Documents created in the window, with their status now. Deleted documents are left out. `count` counts documents.",
      "kind": "entity",
      "document_scope": true,
      "defaults": [],
      "fields": [
        { "name": "failed", "description": "True when processing ended in an error (upload, OCR or extraction).",
          "type": "bool", "groupable": true, "cost": false, "ops": ["eq", "neq", "is_null", "not_null"] },
        { "name": "document_type", "description": "Name of the document type the document is classified as (e.g. \"Invoice\").",
          "type": "text", "groupable": true, "cost": false, "ops": ["eq", "neq", "in", "not_in", "is_null", "not_null"] }
      ]
    }
  ],
  "measures": [ { "name": "count", "description": "What the dataset counts (its description says: rows, documents or distinct documents).", "needs_of": false } ],
  "group_by": { "time": ["hour", "day"], "max": 3, "max_buckets": 200 },
  "scope_keys": ["document_ids", "tags", "system_tags", "source_connection_ids", "document_types", "client_batch_ids", "roots_only", "attachments_only"],
  "limits": { "max_window_days": 31, "max_queries": 20, "max_list_values": 1000, "statement_timeout_ms": 30000,
              "concurrency": { "requests": 1, "per": "workspace" } },
  "cost_visible": true
}

curl -s https://api.talonic.com/v1/aggregate/catalog \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  | jq -r '.datasets[] | "\(.name): \([.fields[] | select(.groupable) | .name] | join(", "))"'