GraphQL API quickstart
Create a personal token, run your first GraphQL API query in GraphiQL or with curl, read the response, and query raw request events.
This guide instructs you through your first query to the GraphQL API.
- Create a personal token in Azion Console.
- Query the request totals of your workloads with the
workloadMetricsdataset. - Read the response, and the shape of an error.
- Query raw request records with the
workloadEventsdataset.
Three things make a query return data, and each one depends on the one before:
- The personal token authenticates the request in the
Authorizationheader. - The endpoint serves one family of data.
https://api.azion.com/v4/metrics/graphqlserves aggregated metrics, andhttps://api.azion.com/v4/events/graphqlserves raw events. - The dataset named in the query, such as
workloadMetrics, is the table the rows come from. The endpoint must serve that dataset.
The GraphQL API reads data only: it has no mutations. For more information, refer to How the GraphQL API works.
Select the interface you will use. The prerequisites and every stage below follow that choice.
Prerequisites
- An Azion account. To create one, refer to Create an account.
- Traffic on at least one workload in the last seven days. A time window with no traffic returns an empty array.
- A browser signed in to Azion Console. To sign in, refer to Access Azion Console.
Create a personal token
The GraphQL API authenticates each request with a personal token. A personal token suits API use because it can have a long expiration.
To create a personal token in Azion Console:
Access Azion Console > Account > Personal Token.
In Name, enter a name. For example: graphql-quickstart.
In Expires within, select 90 days or 1 year. A longer expiration suits API use. Store the token as you store a password.
In the Personal Token has been created dialog, select Copy. The dialog shows the token only once.
The token appears on the Personal Tokens page with its Expiration Date. For more information, refer to Personal tokens.
Run your first query
This query adds up the requests your workloads received from 2026-09-26T14:00:00 to 2026-10-03T14:00:00. It groups the totals by time, newest first, and returns five rows. Before you run it, replace the two tsRange dates with a window inside the last seven days:
workloadMetrics is a metrics dataset, so the query goes to the metrics endpoint, https://api.azion.com/v4/metrics/graphql.
To run the query with curl, send a POST request to the metrics endpoint. Replace [TOKEN VALUE] with your personal token:
The body is a JSON object whose query key holds the query as a string. The header takes the Token scheme: a Bearer header returns 401 with Authentication credentials were not provided., the same as a missing header.
The endpoint returns HTTP 200 and the rows. The response below is cut after the third of its five rows:
Each row is one hour of the window that received requests, with the request total in sum.
Read the response
A GraphQL API response is a JSON object. Its data key holds one array per dataset in the query, named after the dataset: data.workloadMetrics for the query in Run your first query. The array holds one object per row, and each object carries only the fields the query selected.
The workloadMetrics response reads as follows:
tsis the time bucket in UTC. A seven-day window returns hour buckets.sumis the total ofrequestsin that bucket, named after the aggregate function inaggregate: { sum: requests }.- The rows follow
orderBy, herets_DESC, newest first. limitcaps the number of rows. It defaults to10and accepts up to10000.
A window with no data returns an empty array with HTTP 200, not an error.
A query the API refuses returns an HTTP error status and a detail key in place of data. Metrics and events datasets require a time window, so this query, which has no filter, is refused:
The API returns HTTP 400:
Every GraphQL API error has this detail shape, not a GraphQL errors array. For each message and its cause, refer to Error responses.
Query raw events
Raw events are the records of individual requests, one row per request, with no aggregation. The workloadEvents dataset holds them, and the events endpoint, https://api.azion.com/v4/events/graphql, serves it. The metrics endpoint refuses events datasets with 400 and Cannot query field "workloadEvents" on type "Query".
This query returns the time, host, status code, and URI of the five most recent requests. Events datasets keep records for about seven days, so replace the tsRange dates with a window inside the last week:
To run the query with curl, send a POST request to the events endpoint. Replace [TOKEN VALUE] with your personal token:
The endpoint returns HTTP 200 and one object per request. The response below is cut after the third of its five rows:
Each row is one request, with no groupBy and no aggregate. Billing, accounting, and consumption data have their own endpoints, which take the same POST request and Authorization header: https://api.azion.com/v4/billing/graphql, https://api.azion.com/v4/accounting/graphql, and https://api.azion.com/v4/consumption/graphql. Their datasets and time filters are on Queries.
In GraphiQL, the page URL updates with an encoded parameter after a query runs. Copy that URL to share the query with another user.