Quickstart

The REST and MCP examples below use the latest tracked contract.

REST cURL

curl -sS "https://api.admetrics.io/api/20260709/queries/run" \
  -H "Authorization: Bearer $AQL_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_source": "user_provided_query",
    "result_format": "arrow",
    "analytics_query": {
      "shape": { "format": "arrow", "offset": 0, "limit": 100 },
      "select": {
        "metrics": [{ "id": "consumption.spend", "params": {} }],
        "dimensions": [{ "id": "date", "params": {} }, { "id": "campaign_name", "params": {} }]
      },
      "filters": [
        { "id": "client_id", "filter": { "$in": [2617401] } },
        { "id": "date", "filter": { "$gte": "2026-06-01", "$lte": "2026-06-07" } }
      ]
    }
  }'

Use the authenticated Query Builder to assemble the structured query from catalog selections and inspect execution.result.table_preview before moving the request into backend code.

Runnable Examples

We provide dependency-free examples for REST and MCP clients:

• examples/rest/run-aql-query.sh
• examples/rest/run-aql-query.mjs
• examples/mcp/client-config.json

All examples use AQL_BEARER_TOKEN and avoid committing literal bearer tokens.

Catalog

Use the Catalog to access the full library of dimensions and metrics ready to be used in AQL.

Compile Only

Use POST /api/20260709/questions/compile when a workflow needs a generated structured analytics query without execution.

Structured Analytics Query Run

Use POST /api/20260709/queries/run when the caller already has a non-empty structured analytics query from the compiler, the Query Builder, or a trusted backend payload.

Production Checklist

• Use OAuth where supported.
• Store bearer tokens in environment variables or secret managers.
• Never commit tokens, cookies, client secrets, or generated local state.
• Handle 401, validation errors, async timeouts, and retryable status races.
• Log request IDs and high-level status, not bearer tokens or raw secrets.