Reading data

Read your signals, aggregated numbers and raw events back out of Datius, for example to feed your own reports, a BI tool or a spreadsheet. Every request uses a workspace API key with the signals:read scope (see Authentication), and the key must belong to the workspace in the URL. The <workspace-id> in each URL is shown at the top of API Keys & Tokens and in Settings > Workspace > General, or ask the key itself (below).

Need full SQL over your history? On plans with your own storage, your telemetry can live in your own storage bucket as Parquet files, which you can query directly with DuckDB, Spark or your BI tool.

Check a key

Returns the key making the request: its name, scopes and expiry, and the workspace and organization it belongs to. Any valid key can call it, whatever its scopes, so a script holding only a key can find the workspace ID it needs.

Shell

curl https://datius.io/api/v1/api-key \
  -H "X-API-Key: <your-key>"

List signals

Returns every signal in the workspace with its key, data type and tag schema. Add ?isActive=true to skip disabled signals.

Shell

curl https://datius.io/api/v1/workspaces/<workspace-id>/signals \
  -H "X-API-Key: <your-read-key>"

One signal by id: GET /api/v1/signals/<signal-id>.

Business context

What the workspace's owners wrote about the business for AI assistants (set in Settings), such as what the stores are and what a good day looks like. Returns { "businessContext": ... }, null when none is set. Give it to your own assistant as background, not instructions.

Shell

curl https://datius.io/api/v1/workspaces/<workspace-id>/business-context \
  -H "X-API-Key: <your-read-key>"

List derived signals

Returns the workspace's derived signals: each one's key, data type, formula (and its formula in words) and the tags it can be grouped by. Query one through the reports query below with its key; the formula sets the aggregation. On a plan without derived signals this returns 403.

Shell

curl https://datius.io/api/v1/workspaces/<workspace-id>/derived-signals \
  -H "X-API-Key: <your-read-key>"

Aggregated numbers (reports)

The same query the Reports page runs: one signal over a date range, aggregated into buckets, optionally grouped by a tag. The response has a summary, the series of buckets and, when grouped, a breakdown by tag value.

Shell

curl -X POST https://datius.io/api/v1/workspaces/<workspace-id>/reports/query \
  -H "X-API-Key: <your-read-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "signalKey": "order_revenue",
    "startDate": "2026-09-01T00:00:00.000Z",
    "endDate": "2026-10-01T00:00:00.000Z",
    "granularity": "1d",
    "aggregation": "sum",
    "groupByDimension": "store"
  }'

granularity: 1h, 1d, 1w or 1m.
aggregation: count, sum, avg, min, max, p95 or p99.
Optional tagFilters narrow the events first, the same way the filter bar does in the app.

Change analysis

Explains why a signal moved: it compares a window with a baseline and ranks, per tag, the values that account for the change. Counters and currency are compared as totals; numbers, percentages and durations as averages, split into a value's own change and the change in how much of it there is. Included on some plans.

Shell

curl -X POST https://datius.io/api/v1/workspaces/<workspace-id>/insights/explain \
  -H "X-API-Key: <your-read-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "signalKey": "refunds",
    "from": "2026-10-09T09:00:00.000Z",
    "to": "2026-10-09T12:00:00.000Z"
  }'

baseline (optional): auto (the default) uses the same hours averaged over the previous 4 weeks, falling back to last week, then yesterday. You can also pick four_week_average, last_week, yesterday or previous_period. Or set baseline to custom and give a compareWith window (from, to) to compare with, e.g. the first day of a range against its last. Each window can be up to 31 days.
The result has a plain-language headline, the total change, and per tag the ranked values with their share of the change. Tags marked as identifiers (order or device IDs) are never used as a breakdown.
status is NOT_ENOUGH_DATA, with a reason, when there's too little history to compare fairly.

Raw events

Individual events over a time range, newest first, up to 500 per request. Page with offset, and narrow with signalKey, tagFilters or search.

Shell

curl -X POST https://datius.io/api/v1/workspaces/<workspace-id>/telemetry/query \
  -H "X-API-Key: <your-read-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "historical",
    "signalKey": "order_revenue",
    "startTime": "2026-09-30T12:00:00.000Z",
    "endTime": "2026-09-30T13:00:00.000Z",
    "limit": 100,
    "offset": 0
  }'

Tag values

The values one tag has had over the last 7 days, up to 100, for finding the exact value to filter or group by. Narrow them with q, a case-insensitive search.

Shell

curl "https://datius.io/api/v1/workspaces/<workspace-id>/tags/store_id/values?q=00" \
  -H "X-API-Key: <your-read-key>"

Errors

401: the key is missing, wrong or expired.
403: the key lacks signals:read, isn't scoped to a workspace, or belongs to a different workspace than the one in the URL, or the plan doesn't include the feature.
400: the request body didn't validate. The response lists each problem field.

Every request and response shape is in the API Reference.