REST API Reference

This reference is grounded in the analytics service's source-owned OpenAPI 3.1.1 documents. The portal vendors the aggregate document and serves it at /openapi.json; it covers the latest 20260709 contract, the deprecated /v1 compatibility contract, and shared MCP/OAuth paths.

Authentication

REST callers can authenticate with:

Authorization: Bearer <token>

Authorization is preferred. The portal's own live tools call server-side BFF routes so bearer tokens do not live in browser localStorage.

REST Query Flow

Endpoints

Question endpoints are documented for agent and MCP-style workflows. Backend REST integrations should prefer direct structured-query execution through POST /api/20260709/queries/run.

Client Listing

Use GET /api/20260709/clients when an integration only needs accessible client IDs and names. It is lighter than fetching the full catalog and is the preferred backing endpoint for searchable client pickers.

The response includes client_count, returned_count, next_offset, and clients. Each client contains id, client_id, optional display/external names, optional stack metadata, parent client ID, and child client IDs.

Data Freshness

Use GET /api/20260709/clients/{client_id}/freshness before interpreting results that cover today or yesterday, or whenever ingestion lag could affect an answer.

curl -sS "https://api.admetrics.io/api/20260709/clients/2938354/freshness" \
-H "Authorization: Bearer ${AQL_BEARER_TOKEN}"

{
  "client_id": "2938354",
  "observed_at": "2026-08-03T10:00:00Z",
  "dbt": { "last_success_at": "2026-08-03T08:00:00Z" },
  "vendor_pull": {
    "last_success_at": "2026-08-03T09:00:00Z",
    "vendors": ["google"]
  }
}

All timestamps are UTC completion times. Both checkpoints include only regular successful runs; backfills are excluded. A token-authorized client with no successful history returns null for the relevant timestamp. Missing or invalid credentials return 401, and a valid token without access to the requested client returns 403.

Common Natural-Language Request Fields

Structured Analytics Query Run Fields

Metadata-Aware Filters

The Query Builder can add any token-visible metric or dimension as an additional filter. Client and date scope stay in their dedicated controls, filter-only fields do not need to be selected as outputs, and additional rows are combined with AND.

Builder selections and filter editor values are restored when you navigate away and return in the same browser tab. This session-scoped workspace stores query configuration only; authentication credentials and query results are not persisted there.

Contains filters escape the typed value and emit a case-insensitive regex. Explicit regex operators preserve the raw pattern for expert use. Indexed dimensions offer client-scoped value suggestions through /api/20260709/catalog/search, but typed values remain valid:

{
  "dimension": "campaign_name",
  "value_query": "brand",
  "client_ids": [2617401],
  "value_limit": 12
}

A query can repeat a field; AQL merges the constraints. A range and a case-insensitive contains filter serialize as:

"filters": [
  { "id": "client_id", "filter": { "$in": [2617401] } },
  { "id": "date", "filter": { "$gte": "2026-06-01", "$lte": "2026-06-30" } },
  { "id": "attributed_events.visits", "filter": { "$gte": 1000, "$lte": 5000 } },
  { "id": "campaign_name", "filter": { "$regex": "(?i).*brand.*" } }
]

Return Formats

Return Format Examples

These examples show the shape a run response might expose under execution.result. Exact wrappers and metadata can vary by endpoint, timeout behavior, and format.

records or json

{
  "format": "records",
  "content_type": "application/json",
  "data": [
    {
      "date": "2026-06-01",
      "campaign_name": "Brand Search",
      "spend": 1284.5,
      "revenue": 8120.2,
      "roas": 6.32
    }
  ]
}

rows

{
  "format": "rows",
  "columns": ["date", "campaign_name", "spend", "revenue", "roas"],
  "data": [
    ["2026-06-01", "Brand Search", 1284.5, 8120.2, 6.32]
  ]
}

columnar

{
  "format": "columnar",
  "data": {
    "date": ["2026-06-01"],
    "campaign_name": ["Brand Search"],
    "spend": [1284.5],
    "revenue": [8120.2],
    "roas": [6.32]
  }
}

csv or txt

date,campaign_name,spend,revenue,roas
2026-06-01,Brand Search,1284.50,8120.20,6.32

arrow, xlsx, or dataframe

{
  "format": "arrow",
  "content_type": "application/vnd.apache.arrow.stream",
  "byte_length": 1024,
  "base64": "<encoded binary payload>",
  "table_preview": {
    "columns": ["date", "campaign_name", "spend", "revenue", "roas"],
    "rows": [
      {
        "date": "2026-06-01",
        "campaign_name": "Brand Search",
        "spend": 1284.5,
        "revenue": 8120.2,
        "roas": 6.32
      }
    ],
    "row_count": 1,
    "truncated": false
  }
}

Binary-oriented formats usually include content metadata and may include table_preview so portal users can inspect rows without decoding the full payload in the browser.

Troubleshooting Failed Requests

Most failures mean the request needs a more precise analytics contract. Treat these as recoverable integration states rather than generic server errors.