What you will learn in this article:
How token-based authentication and bearer headers secure your API requests.
The core REST query execution flow, from client and catalog discovery to payload execution.
Key API endpoints for retrieving metadata, checking pipeline data freshness, and executing direct analytics queries.
For full technical specifications and interactive query builder tools, visit our full reference documentation at https://developers.admetrics.io/docs/api-reference.
Who this article is for
This article is designed for:
Data Engineers and Software Developers building custom ETL pipelines, internal dashboards, or automated reporting workflows.
Marketing Operations & Analytics Teams seeking direct programmatic access to attribution metrics, active client IDs, and raw analytics outputs.
Product Managers & Technical Leads overseeing transitions from legacy Admetrics integrations to our standardized REST infrastructure.
It addresses common business challenges such as manual reporting overhead, data latency in custom BI tools, legacy integration deprecation, and the need for programmatically verified data freshness across multi-client accounts.
Important notice: API migration window
Customers using the legacy API have a 30-day deadline to migrate to the new REST interface and token-based authentication.
Please note the following details regarding this migration:
Support Window: While legacy API endpoint functionality will remain active to ensure uninterrupted operations for the internal dashboard, technical support for the legacy API will officially end upon the expiration of the 30-day notice period.
Enhanced Logging: Extensive logging has been implemented for the new REST API. This provides significantly higher visibility into request processing, payload validation, and execution errors, making troubleshooting faster and more straightforward.
Action Required: Audit your current API integrations, replace deprecated authentication mechanisms with Bearer tokens, and update your endpoint paths to the current API version.
What are the benefits
Integrating with the current Admetrics REST API provides several key business and technical advantages:
Unified Developer Portal: The new Developer Portal unifies API access. Customers can now independently manage their API access, explore the catalog via the search tool, and construct payloads using the interactive Query Builder.
Simplified Token Generation: You can now generate API tokens directly and securely within the Developer Portal, entirely replacing the legacy method of manually extracting tokens from the Chrome console.
Streamlined Debugging: Extensive backend logging for every API request accelerates error diagnosis and integration setup, providing high visibility into request processing and payload validation.
Automated Data Pipelines: Programmatically extract attribution and performance metrics directly into your data warehouse or BI platforms.
Real-Time Data Freshness Checks: Inspect transformation and vendor ingestion timestamps before executing heavy queries to guarantee data integrity.
How to use it
To generate an API token for authenticating your requests:
Step 1: Sign in using your standard admetrics credentials:
Go to the Developer Portal at https://developers.admetrics.io/tokens and log in with your account.
Step 2: You will be asked to authorize the admetrics developer portal and request access in order to read ADM API data as well as MCP-facing tools.
Step 3: Navigate to API Access and click on "Create token".
Step 4: Your generated token will appear on the right and is ready to use.
Authentication
All REST API requests require Bearer token authentication supplied in the HTTP request header:
HTTP
Authorization: Bearer <your_api_token>
Note: Tokens can be generated and managed inside the Developer Portal. Always store your tokens securely in environment variables or key management systems - never embed tokens directly in client-side code.
Core Query Execution Flow
To execute a structured analytics query via the REST API, follow these steps:
Discover Authorized Clients: Call
GET /api/20260709/clientsto list active client IDs accessible to your token.Inspect Data Freshness: Verify that recent data has synced by calling
GET /api/20260709/clients/{client_id}/freshness.Build Your Query Payload: Assemble your JSON payload defining your target metrics, dimensions, date range, and filters under the
analytics_queryobject.Execute the Query: Send a
POSTrequest tohttps://api.admetrics.io/api/20260709/queries/runwith your query payload and setquery_sourcetouser_provided_query.Inspect & Parse Results: Parse the response body for execution status, schema metadata, and tabular result sets.
Key Endpoints Reference
HTTP Method | Endpoint Path | Primary Purpose |
|
| Service liveness check for system monitoring. |
|
| Download aggregate, machine-readable OpenAPI contracts across all versions. |
|
| Retrieve normalized catalog of available metrics, dimensions, and clients. |
|
| Fetch paginated list of active clients authorized for the bearer token. |
|
| Inspect the latest successful DBT attribution update and vendor pull timestamps. |
|
| Search metrics, dimensions, clients, and indexed dimension values dynamically. |
|
| Primary REST execution endpoint. Validate and run a structured analytics query directly. |
|
| Compile, validate, and execute natural-language queries for agent workflows. |
Additional resources and related articles
Admetrics Developer Portal & API Reference: For full technical specifications, interactive query builder tools, and raw OpenAPI schemas, visit our full reference documentation at https://developers.admetrics.io/docs/api-reference.
Interactive REST Query Builder: Build and validate JSON query payloads visually in your browser at https://developers.admetrics.io/rest-builder.
Data Catalog Explorer: Browse indexed metrics, dimensions, and dimension values at https://developers.admetrics.io/catalog.
API Access & Token Management: Learn how to create and rotate bearer tokens at https://developers.admetrics.io/tokens.
Frequently asked questions
Q: What happens to my integration when the 30-day legacy API migration window ends?
A: After 30 days, technical support for legacy endpoints will cease entirely. While underlying legacy endpoints may remain active to serve internal dashboard dependencies, deprecated endpoints will no longer receive bug fixes, optimizations, or technical assistance. All API consumers must transition to token-based authentication and the /api/20260709/ path within 30 days.
Q: How does the new logging feature help with troubleshooting?
A: The current REST API captures extensive request metadata, token validation steps, payload structure errors, and execution traces on the server side. If a query fails or returns unexpected results, our technical support team can inspect these logs using your token's request trace IDs to pinpoint issues immediately.
Q: What is the difference between /queries/run and /questions/run?
A: /queries/run is the primary endpoint for backend REST integrations. It requires a pre-structured JSON query object (analytics_query) and runs with minimal validation overhead. /questions/run is designed for conversational interfaces and agent workflows, taking natural-language strings, compiling them into structured queries, and executing them asynchronously.
Q: What result formats can I request?
A: You can specify output formatting in your request body via result_format. Supported values include records, rows, columnar, csv, txt, xlsx, dataframe, arrow, json and text.
How to share feedback
We continually improve our REST API documentation and developer tooling. If you encounter issues, notice gaps in our documentation, or have suggestions:
Click the "Was this article helpful?" rating buttons at the bottom of this page.
Send developer feedback directly to [email protected].
For technical support during your migration, submit a request via the Admetrics Help Portal or reach out to your designated technical support representative.