Aggregate Overview

Count documents, failures, app decisions, deliveries, model calls and cost per document in one request. Numbers only, filtered, grouped by field or by day.

POST /v1/aggregate answers several questions about your workspace in one request and returns numbers, never document contents. A typical dashboard asks: how many documents arrived in the last 12 hours, how many of them failed, how they split by document type, and what processing a document cost on average. Each of those is one query in the same request, and the answer comes back keyed by the id you gave each query.

Every request names a time window with from and to. Both are ISO-8601 timestamps that carry an offset, such as 2026-11-05T12:00:00Z; a timestamp without one is refused, because it would be read in an unknown time zone. The window includes from and excludes to, so two back-to-back windows never count the same row twice. A window can be at most 31 days long.

Each query picks a dataset (what you are counting, such as documents or deliveries), a measure (count, sum, avg, median, a percentile like p90, and a few more) and optionally where filters and group_by fields. GET /v1/aggregate/catalog lists every dataset with a sentence on what one row is, every field with its type and the filters it takes, and every limit. Read it first: it is generated from the same definitions the endpoint checks requests against, so it is always current.

Most datasets count things created in the window and report their state now. A document that arrived yesterday and failed this morning counts as failed in yesterday's window. This makes repeated reports for the same window change slightly while work is still in progress, and settle once it is done. as_of in the answer says when the numbers were read; all queries of one request read the same moment.

scope narrows every query of the request to some documents: by id, by tag, by source, by document type, by the batch_id you sent at upload, or to top-level documents or attachments only. Datasets that are not about documents refuse a scope with a 400, so a filter never silently does nothing; the catalog marks them with document_scope: false. Rows tied to a document the owner of the API key may not see are left out. Rows tied to no document at all, such as a model call outside any document, still count unless a scope is set.

curl -s https://api.talonic.com/v1/aggregate \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-11-05T12:00:00Z",
    "to":   "2026-11-06T00:00:00Z",
    "queries": [
      { "id": "received", "dataset": "documents", "measure": "count",
        "where": [{ "field": "duplicate", "op": "eq", "value": false }] },
      { "id": "failed",   "dataset": "documents", "measure": "count",
        "where": [{ "field": "failed", "op": "eq", "value": true }] },
      { "id": "by_type",  "dataset": "documents", "measure": "count",
        "group_by": ["document_type"] },
      { "id": "cost",     "dataset": "document_cost",
        "measure": ["avg", "median", "p90"], "of": "cost_usd" }
    ]
  }'

{
  "window": { "from": "2026-11-05T12:00:00.000Z", "to": "2026-11-06T00:00:00.000Z" },
  "as_of": "2026-11-06T00:00:03.120Z",
  "results": {
    "received": { "dataset": "documents", "kind": "entity", "value": 412 },
    "failed":   { "dataset": "documents", "kind": "entity", "value": 3 },
    "by_type": {
      "dataset": "documents", "kind": "entity",
      "groups": [
        { "key": { "document_type": "Invoice" },       "value": 301 },
        { "key": { "document_type": "Delivery Note" }, "value": 97 },
        { "key": { "document_type": null },            "value": 14 }
      ],
      "groups_total": 3
    },
    "cost": { "dataset": "document_cost", "kind": "entity",
              "values": { "avg": 0.0108, "median": 0.0104, "p90": 0.0124, "n": 412 } }
  }
}

Reading the answer

A query with one measure answers value; a query with a list of measures answers values, one entry per measure, plus n, the number of rows they were computed over. A grouped query answers groups, each with the key it groups by and its value; a null key collects the rows without a value for that field (above: documents not yet classified). Groups come largest first, or in time order when grouped by hour or day.

At most 200 groups come back per query. groups_total says how many existed, so when it is larger than the number of groups returned, narrow the query with a where filter or a shorter window. A computed measure such as avg or sum is null when there were no rows to compute it over; counts are 0.

{
  "from": "2026-10-07T00:00:00Z",
  "to":   "2026-11-06T00:00:00Z",
  "queries": [
    { "id": "failed_daily", "dataset": "documents", "measure": "count",
      "where": [{ "field": "failed", "op": "eq", "value": true }],
      "group_by": ["day", "source_connection_id"] }
  ]
}

Errors

• 400 invalid_aggregate: a name, operator, value or limit is wrong. The message says which, and details lists the names allowed there (allowed_datasets, allowed_fields, allowed_ops, allowed_keys).
• 403 cost_not_visible: the request asks for a cost field or groups by model, and cost visibility is off for your organization.
• 422 aggregate_timeout: one statement ran longer than limits.statement_timeout_ms and the request was stopped; details.dataset names the dataset. Ask for a shorter window, fewer groups or fewer queries.
• 429 with Retry-After: another aggregate request of your workspace is still running. Retry after that many seconds.
• 429 with X-RateLimit-Reset: the daily rate limit of your workspace is used up until that time.