> ## Documentation Index > Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # Query data > Execute a query to retrieve data from a specified data source ## OpenAPI ````json GET /query/data/{context_type} { "openapi": "3.0.3", "info": { "title": "Data API Reference", "version": "2.0.0", "description": "API Documentation for the Supermetrics Data API including data source search capabilities. For more information, visit https://supermetrics.com.", "termsOfService": "https://supermetrics.com/terms-of-service", "contact": { "name": "Supermetrics Suppot", "email": "support@supermetrics.com", "url": "https://supermetrics.com/support" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "x-api-id": "sm-data-api", "x-audience": "public" }, "servers": [ { "url": "https://api.supermetrics.com/v2", "description": "Global production public Supermetrics Data API base path.", "x-internal": false }, { "url": "https://api.supermetrics.com", "description": "Global production public Supermetrics API base path for datasource search.", "x-internal": false } ], "tags": [ { "name": "Get data", "description": "Query data and retrieve results, fields, segments, and accounts" }, { "name": "Data Source Search", "description": "Search and discover data sources with filtering capabilities" }, { "name": "Destination Search", "description": "Search and discover destinations for your team" }, { "name": "API Usage", "description": "Retrieve API usage rollups — timeseries, top breakdowns, errors, and summary" }, { "name": "Raw Usage Data Export", "description": "Endpoints for creating and retrieving a team's raw usage reposts." }, { "name": "Campaign Management", "description": "Create, update, and manage advertising campaigns, audiences, conversions, keywords, and related assets" } ], "externalDocs": { "description": "Find out more about Supermetrics Data API", "url": "https://docs.supermetrics.com/apidocs/data-api" }, "paths": { "/query/data/{context_type}": { "servers": [ { "url": "https://api.supermetrics.com", "description": "production server", "x-internal": false } ], "get": { "summary": "Query data", "description": "Execute a query to retrieve data from a specified data source", "operationId": "getData", "parameters": [ { "name": "context_type", "in": "path", "required": true, "description": "Output format to use for query results", "schema": { "type": "string", "enum": [ "json", "keyjson", "ndjson", "parquet", "powerbi", "qlik", "tableau", "csv", "tsv", "pbijson", "postman" ], "x-enum": [ "json", "keyjson", "ndjson", "parquet", "powerbi", "qlik", "tableau", "csv", "tsv" ], "example": "json" } }, { "name": "schedule_id", "in": "query", "required": false, "description": "Custom query schedule ID", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "sync_timeout", "in": "query", "required": false, "description": "Number of seconds to wait for the query to finish", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 3600, "default": 1800, "example": 0 } }, { "name": "api_links", "in": "query", "required": false, "description": "Types of resource links to return. Not in use.", "schema": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 1000 } }, { "name": "ds_id", "in": "query", "required": true, "description": "Data source ID", "schema": { "type": "string", "maxLength": 100, "example": "GA" } }, { "name": "ds_accounts", "in": "query", "required": false, "description": "List of data source account IDs to query", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "ds_segments", "in": "query", "required": false, "description": "List of data source segment IDs to query", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "ds_user", "in": "query", "required": false, "description": "Shorthand parameter to provide one value for ds_users", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "ds_users", "in": "query", "required": false, "description": "List of data source usernames we should target", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "date_range_type", "in": "query", "required": false, "description": "Type of date range the query should use", "schema": { "type": "string", "maxLength": 50, "example": "yesterday" } }, { "name": "start_date", "in": "query", "required": false, "description": "Fixed or relative query start date", "schema": { "type": "string", "maxLength": 50, "example": "yesterday" } }, { "name": "end_date", "in": "query", "required": false, "description": "Fixed or relative query end date", "schema": { "type": "string", "maxLength": 50, "example": "yesterday" } }, { "name": "compare_type", "in": "query", "required": false, "description": "Date range comparison type", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "compare_show", "in": "query", "required": false, "description": "Display type for comparison values", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "compare_start_date", "in": "query", "required": false, "description": "Fixed or relative start date for comparison date range", "schema": { "type": "string", "maxLength": 50, "example": "yesterday" } }, { "name": "compare_end_date", "in": "query", "required": false, "description": "Fixed or relative end date for comparison date range", "schema": { "type": "string", "maxLength": 50, "example": "yesterday" } }, { "name": "fields", "in": "query", "required": false, "description": "List of metric and dimension field IDs or field objects for the query", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "filter", "in": "query", "required": false, "description": "Query filter string", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "settings", "in": "query", "required": false, "description": "Additional settings for query in key-value pairs", "schema": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 1000 } }, { "name": "order_rows", "in": "query", "required": false, "description": "List of fields and their sorting directions for the results", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "order_columns", "in": "query", "required": false, "description": "Order policy for fields that are split by column", "schema": { "type": "string", "maxLength": 100, "example": "example" } }, { "name": "offset_start", "in": "query", "required": false, "description": "Starting row index for a paginated response. Defaults to 0.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000000, "default": 0, "example": 0 } }, { "name": "offset_end", "in": "query", "required": false, "description": "Ending row index for a paginated response. Defaults to none for all the data.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "max_columns", "in": "query", "required": false, "description": "Maximum number of columns the query should return when fields are split by column", "schema": { "type": "integer", "format": "int32", "default": 20, "minimum": 0, "maximum": 2147483647, "example": 0 } }, { "name": "max_rows", "in": "query", "required": false, "description": "Maximum number of rows the query should return. Defaults to 1000.", "schema": { "type": "integer", "format": "int32", "default": 1000, "minimum": 0, "maximum": 2147483647, "example": 0 } }, { "name": "cache_minutes", "in": "query", "required": false, "description": "Maximum allowed age of query results cache in minutes. Defaults to none for no explicit policy.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 2147483647, "example": 0 } } ], "responses": { "200": { "description": "Query executed successfully, or — when `sync_timeout` elapses before the query\nfinishes — the schedule handle needed to poll `/query/status`.\n\nBranch on `meta.status_code`, never on the HTTP status. An unfinished query\nalso answers 2xx, with `data: []` and `meta.status_code: RUNNING`; teams\ncarrying the `getQueryTimeoutHttpAs202` feature receive 202 rather than 200 in\nthat case. Only `meta.status_code: SUCCESS` means the rows are present.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DataResponse" }, { "$ref": "#/components/schemas/QueryStatusResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [ "ds_queries_write", "ds_queries_run", "any_api_key" ] } ], "tags": [ "Get data" ] } } }, "components": { "schemas": { "DataResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "request_id": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$", "description": "API request ID" }, "schedule_id": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$", "description": "Custom or generated schedule ID for the query" }, "status_code": { "type": "string", "maxLength": 20, "description": "Status code for the query" }, "query": { "type": "object", "properties": { "start_date": { "type": "string", "maxLength": 10, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Query start date in YYYY-MM-DD format" }, "end_date": { "type": "string", "maxLength": 10, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Query end date in YYYY-MM-DD format" }, "ds_accounts": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Data source account IDs used in the query" }, "ds_segments": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Data source segment IDs used in the query" }, "fields": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$", "description": "Field ID from the request" }, "field_id": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$", "description": "Field ID the API uses" }, "field_name": { "type": "string", "maxLength": 255, "description": "Field name" }, "field_type": { "type": "string", "maxLength": 10, "description": "Field type" }, "field_split": { "type": "string", "maxLength": 50, "description": "Field split by type" }, "data_type": { "type": "string", "maxLength": 50, "description": "Field data type" }, "data_column": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000, "description": "Field value position in each data row" }, "visible": { "type": "boolean", "description": "Whether data for this field is visible" } } } }, "compare_type": { "type": "string", "maxLength": 50, "description": "Date range comparison type used" }, "compare_show": { "type": "string", "maxLength": 50, "description": "Display type for comparison values" }, "compare_start_date": { "type": "string", "maxLength": 10, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date for comparison date range" }, "compare_end_date": { "type": "string", "maxLength": 10, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date for comparison date range" }, "settings": { "type": "object", "description": "Settings used in query" }, "cache_minutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10080, "description": "Requested maximum age of cache in minutes" } } }, "result": { "type": "object", "properties": { "total_columns": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000, "description": "Total amount of columns" }, "total_rows": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000, "description": "Total amount of rows in data" }, "run_seconds": { "type": "number", "format": "float", "minimum": 0, "maximum": 7200, "description": "Number of seconds it took for the query to run" }, "data_sampled": { "type": "boolean", "description": "If data source has provided sampled data" }, "cache_used": { "type": "boolean", "description": "If cached data was used" }, "cache_time": { "type": "string", "format": "date-time", "maxLength": 30, "description": "ISO 8601 datetime for the most recent cached data" } } }, "paginate": { "type": "object", "properties": { "prev": { "type": "string", "format": "uri", "maxLength": 500, "description": "URL to previous offset" }, "next": { "type": "string", "format": "uri", "maxLength": 500, "description": "URL to next offset" } } } } }, "data": { "type": "array", "maxItems": 1000000, "items": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 10000 } }, "description": "Query result rows" } } }, "QueryStatusResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "request_id": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$", "description": "API request ID" }, "schedule_id": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$", "description": "Query schedule ID" }, "status_code": { "type": "string", "maxLength": 20, "description": "Status code for the query", "enum": [ "SCHEDULED", "QUEUED", "RUNNING", "SUCCESS", "FAILURE", "STOPPED", "PROCESS_EXITED" ], "x-enum": [ "SCHEDULED", "QUEUED", "RUNNING", "SUCCESS", "FAILURE", "STOPPED" ] }, "progress": { "type": "object", "properties": { "queries_ready": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "description": "Number of sub-queries completed for this query" }, "queries_total": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "description": "Number of sub-queries scheduled for this query (can increase as query progresses)" } } }, "workflow": { "type": "object", "properties": { "tasks_scheduled": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000, "description": "Number of query tasks scheduled to your license queue" }, "tasks_running": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1000, "description": "Number of query tasks running in your license queue" } } } } }, "data": { "type": "array", "maxItems": 10000, "description": "Query results. Empty array when query is not in SUCCESS state.", "items": { "type": "object" } } } }, "ErrorResponse": { "type": "object", "description": "Standard envelope returned by all error (4xx/5xx) responses.", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "meta", "error" ], "additionalProperties": false }, "Meta": { "type": "object", "description": "Metadata included in every API response.", "properties": { "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ], "additionalProperties": false }, "Error": { "type": "object", "description": "Machine- and human-readable detail for a failed request.", "properties": { "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "maxLength": 100, "description": "Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on `message`. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.", "example": "BAD_REQUEST" }, "message": { "type": "string", "maxLength": 255, "pattern": "^.+$", "description": "Short, human-readable summary of the error.", "example": "The request was invalid." }, "description": { "type": "string", "maxLength": 2048, "description": "Optional longer explanation specific to this occurrence.", "example": "The field 'display_name' must not be empty." } }, "required": [ "code", "message" ], "additionalProperties": false }, "RequestId": { "type": "string", "description": "Unique identifier for the request, for tracking and debugging.", "pattern": "^[A-Za-z0-9_-]+$", "minLength": 8, "maxLength": 64, "example": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN", "x-faker": { "random.alphaNumeric": 30 } } }, "responses": { "BadRequest": { "description": "Bad request - invalid parameters", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "meta": { "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN" }, "error": { "code": "BAD_REQUEST", "message": "The request was invalid." } } } } }, "Unauthorized": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "meta": { "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN" }, "error": { "code": "UNAUTHORIZED", "message": "Authentication is required." } } } } }, "PermissionDenied": { "description": "Permission denied", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "meta": { "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN" }, "error": { "code": "PERMISSION_ERROR", "message": "You do not have permission to perform this action." } } } } }, "UnprocessableEntity": { "description": "Unprocessable Entity - validation failed for the request parameters", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "meta": { "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN" }, "error": { "code": "UNPROCESSABLE_ENTITY", "message": "Validation failed for the request parameters." } } } } }, "TooManyRequests": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "meta": { "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN" }, "error": { "code": "TOO_MANY_REQUESTS", "message": "Rate limit exceeded. Retry later." } } } } }, "InternalServerError": { "description": "Internal server error", "headers": { "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "meta": { "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN" }, "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred." } } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API key authentication. Create API keys in the Supermetrics Hub and send\nthem in the Authorization header:\n`Authorization: Bearer `\n" } }, "headers": { "X-RateLimit-Limit": { "description": "Request limit per hour", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 10000, "example": 5000 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "example": 4999 } }, "Access-Control-Allow-Origin": { "description": "CORS header", "schema": { "type": "string", "maxLength": 255, "enum": [ "*" ], "example": "*" } }, "WWW-Authenticate": { "description": "Bearer token required", "schema": { "type": "string", "maxLength": 255, "pattern": "^Bearer.*" } }, "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 86400, "example": 3600 } } } } } ````