Concepts

What AQL Does

AQL (Admetrics Query Language) translates catalog-aware analytics intent into the query shape understood by the Admetrics warehouse layer. It takes exact metrics, dimensions, clients, date ranges, attribution settings, grouping, sort, limit, and output-format options, validates them, and produces or runs the corresponding warehouse query.

For API builders, this keeps the integration boundary stable: use catalog IDs and structured analytics queries instead of hard-coding warehouse tables, joins, attribution logic, or result serialization in every downstream service.

MCP vs REST API

MCP exposes named tools to agent clients. Use it when ChatGPT, Claude Code, Codex, OpenCode, or another agent should search catalog fields, compile a natural-language analytics question, validate the generated structured query, and optionally run the result.

REST exposes HTTP endpoints for application code. Use it when a backend system already knows the exact metric, dimension, client, and date fields it wants to request. Most REST integrations should send a trusted structured analytics query directly to POST /api/20260709/queries/run; the Query Builder helps assemble that payload from catalog IDs.

Natural-language orchestration belongs in MCP clients and agent tools. The portal Query Builder is for direct JSON query construction and result inspection.

Data Platform Augmentation

Admetrics can live next to an existing warehouse, dashboard layer, notebook environment, or internal developer platform. Use REST to fetch validated analytics into your own jobs and data products, and use MCP to let agents discover, explain, and orchestrate the same metric contracts.

The main advantage is consistency: catalog IDs, attribution parameters, date ranges, and result formats become shared integration contracts instead of being reimplemented separately in every report, service, or agent workflow.

Clients

Client IDs identify the Admetrics customer or account context. Include a client whenever possible so catalog search, validation, and execution stay precise.

Metrics And Dimensions

Metrics are numeric measures such as spend or revenue. Dimensions group or filter results, such as campaign, ad set, channel, or date.

Exact catalog IDs are preferred over guessed labels. Use the Catalog Explorer or search_analytics_catalog before compile/run calls when field names are ambiguous.

Time resolution is represented as dimensions in the structured query. Daily grouping uses date, weekly grouping prefers week and can fall back to isoweek, monthly grouping uses month, and custom grouping does not add a time dimension automatically.

Attribution Parameters

Some metrics support attribution parameters such as model and window. Explicit per-metric params win over global params, and all values must be supported by the live catalog.

Date Ranges

Natural-language calls should describe one continuous date range. Direct comparison wording such as vs, compare, YoY, MoM, change, increase, drop, or spike is rejected by the compiler. Decompose comparisons into one query per period or request a continuous range grouped by time.

Validation Before Execution

Compile produces a structured analytics query and validation output. Execution should only start after validation succeeds.

Async Lifecycle

Run paths enqueue an analytics query, poll status, and fetch a result when available. Long-running queries can time out locally while continuing upstream; callers should handle async status explicitly.

Output Formats

Supported formats are records, rows, columnar, csv, txt, xlsx, dataframe, and arrow. json maps to records; text maps to txt.

The Query Builder defaults to arrow for backend-style integrations. Arrow binary responses may include execution.result.table_preview so portal users can inspect rows without downloading or decoding the full payload in the browser.