Async queries

By default, a Supermetrics API query is a synchronous request, meaning the HTTP request waits until the query has finished running. This is sometimes referred to as HTTP long polling.

In contrast, fetching data in asynchronous mode returns query status without any waiting. You are then expected to poll for query status with separate requests.

• How to run an async query
• Poll for query status
• Get query results
• Result expiry
• Limitations

How to run an async query

Query parameter sync_timeout controls the amount of seconds your request will wait for the query to finish, before returning a response.

By setting the value to 0, we will not wait at all, and instead immediately respond with the query status. You will then need to poll for query status to get further updates.

GET https://api.supermetrics.com/enterprise/v2/query/data/json?json={
    "api_key": "<api key>",
    "sync_timeout": 0
}

HTTP 202 Accepted
{
    "meta": {
        "request_id": "AbRoVa9aiNVGFhsl8Eu2ebAmuenMHwsY",
        "schedule_id": "4226fd7f86799a5804...102d51c0",
        "status_code": "QUEUED",
        "progress": {
            "queries_ready": 0,
            "queries_total": 1
        },
        "workflow": {
            "tasks_scheduled": 0,
            "tasks_running": 1
        }
    },
    "data": []
}

Response code for above response is 200 OK for customers enrolled before June 22nd 2022. To change this behaviour, please contact support.

Poll for query status

To ask for the query status, use the status endpoint. For this you will need the schedule ID from the requested query. The response will either be the current query status, query error, or the query results in the default JSON format.

Note: You can also set your own schedule ID with the schedule_id parameter.

GET https://api.supermetrics.com/enterprise/v2/query/status?json={
    "api_key": "<api key>",
    "schedule_id": "4226fd7f86799a5804...102d51c0"
}

Get query results

You might have noticed that the previous status provides the query results only in the default JSON format. If you used some other format, you can retrieve those results via the get results endpoint.

GET https://api.supermetrics.com/enterprise/v2/query/results?json={
    "api_key": "<api key>",
    "schedule_id": "4226fd7f86799a5804...102d51c0"
}

Result expiry

The maximum amount of time a query can run is four hours. Query status or results can be retrieved up to one hour after a query has stopped. If requested query status cannot be found, the status endpoint will respond with error code STATUS_NOT_FOUND.

Limitations

If you plan to schedule large batches of queries in asynchronous mode, please be aware that all queries are performed with limited concurrency, and in the order they were received. Therefore, large batches might cause temporary processing delays in other tools that you use Supermetrics API with as well.

See usage limits for more.