# GraphQL API quickstart 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 `workloadMetrics` dataset. - Read the response, and the shape of an error. - Query raw request records with the `workloadEvents` dataset. Three things make a query return data, and each one depends on the one before: 1. The **personal token** authenticates the request in the `Authorization` header. 2. The **endpoint** serves one family of data. `https://api.azion.com/v4/metrics/graphql` serves aggregated metrics, and `https://api.azion.com/v4/events/graphql` serves raw events. 3. 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](/en/documentation/devtools/graphql/overview/). --- 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](/en/documentation/fundamentals/creating-account/). - Traffic on at least one workload in the last seven days. A time window with no traffic returns an empty array. **GraphiQL** - A browser signed in to Azion Console. To sign in, refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). **API** - `curl`, or another HTTP client. To send the queries from Postman, refer to [Run GraphQL queries in Postman](/en/documentation/guides/platform/observability/query-graphql-postman/). --- ## 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: 1. **Open the Personal Tokens page** Access [Azion Console](https://console.azion.com/) > **Account** > **Personal Token**. 2. **Select + Personal Token** 3. **Name the token** In **Name**, enter a name. For example: `graphql-quickstart`. 4. **Set the expiration** In **Expires within**, select *90 days* or *1 year*. A longer expiration suits API use. Store the token as you store a password. 5. **Select Save** 6. **Copy the token** In the **Personal Token has been created** dialog, select **Copy**. The dialog shows the token only once. 7. **Select Confirm** The token appears on the **Personal Tokens** page with its **Expiration Date**. For more information, refer to [Personal tokens](/en/documentation/guides/platform/account-and-billing/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: ```graphql query { workloadMetrics( limit: 5 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } aggregate: { sum: requests } groupBy: [ts] orderBy: [ts_DESC] ) { ts sum } } ``` `workloadMetrics` is a metrics dataset, so the query goes to the metrics endpoint, `https://api.azion.com/v4/metrics/graphql`. **GraphiQL** The endpoint URL also serves GraphiQL, an in-browser editor that writes, validates, and runs GraphQL queries. To run the query in GraphiQL: 1. **Sign in to Azion Console** Access [Azion Console](https://console.azion.com/) and sign in to your account. 2. **Open the metrics endpoint** In the same browser, go to `https://api.azion.com/v4/metrics/graphql`. 3. **Paste the query** Paste the query into the editor. GraphiQL validates each field as you type. 4. **Run the query** Without a signed-in session, the endpoint returns `401` with `Authentication credentials were not provided.` instead of GraphiQL. **API** To run the query with `curl`, send a `POST` request to the metrics endpoint. Replace `[TOKEN VALUE]` with your personal token: ```bash curl -X POST https://api.azion.com/v4/metrics/graphql \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Content-Type: application/json" \ -d '{"query": "query { workloadMetrics(limit: 5, filter: { tsRange: {begin: \"2026-09-26T14:00:00\", end: \"2026-10-03T14:00:00\"} }, aggregate: { sum: requests }, groupBy: [ts], orderBy: [ts_DESC]) { ts sum } }"}' ``` 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: ```json { "data": { "workloadMetrics": [ { "ts": "2026-10-03T13:00:00Z", "sum": 2 }, { "ts": "2026-10-03T12:00:00Z", "sum": 2 }, { "ts": "2026-10-03T03:00:00Z", "sum": 2 }, … ] } } ``` 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: - `ts` is the time bucket in UTC. A seven-day window returns hour buckets. - `sum` is the total of `requests` in that bucket, named after the aggregate function in `aggregate: { sum: requests }`. - The rows follow `orderBy`, here `ts_DESC`, newest first. - `limit` caps the number of rows. It defaults to `10` and accepts up to `10000`. 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: ```graphql query { workloadMetrics(limit: 3, aggregate: { sum: requests }, groupBy: [ts]) { ts sum } } ``` The API returns HTTP `400`: ```json { "detail": "To execute queries it is mandatory to provide the desired time interval." } ``` Every GraphQL API error has this `detail` shape, not a GraphQL `errors` array. For each message and its cause, refer to [Error responses](/en/documentation/devtools/graphql/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: ```graphql query { workloadEvents( limit: 5 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } orderBy: [ts_DESC] ) { ts host status requestUri } } ``` **GraphiQL** To run the query in GraphiQL: 1. **Open the events endpoint** In a browser signed in to Azion Console, go to `https://api.azion.com/v4/events/graphql`. 2. **Paste the query** 3. **Run the query** **API** To run the query with `curl`, send a `POST` request to the events endpoint. Replace `[TOKEN VALUE]` with your personal token: ```bash curl -X POST https://api.azion.com/v4/events/graphql \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Content-Type: application/json" \ -d '{"query": "query { workloadEvents(limit: 5, filter: { tsRange: {begin: \"2026-09-26T14:00:00\", end: \"2026-10-03T14:00:00\"} }, orderBy: [ts_DESC]) { ts host status requestUri } }"}' ``` The endpoint returns HTTP `200` and one object per request. The response below is cut after the third of its five rows: ```json { "data": { "workloadEvents": [ { "ts": "2026-10-03T13:34:44Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, { "ts": "2026-10-03T13:16:33Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, { "ts": "2026-10-03T12:53:40Z", "host": "www.example.com", "status": 200, "requestUri": "/" }, … ] } } ``` 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](/en/documentation/devtools/graphql/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. --- ## Next steps - [How the GraphQL API works](/en/documentation/devtools/graphql/overview.md): The endpoints, the datasets each one serves, and how aggregated and raw data differ. - [Queries](/en/documentation/devtools/graphql/queries.md): Query shapes for raw, aggregated, financial, and usage data, with a response for each. - [GraphiQL Playground](/en/documentation/devtools/graphql/graphql-playground.md): Sample queries to run and adapt in the in-browser editor. - [GraphQL API guides](/en/documentation/devtools/graphql/guides.md): Queries for top URIs, top attacks, top attacking IPs, connected users, and metadata.