GraphQL API

GraphQL is a query language for APIs. A client sends one query that names the records it wants and the fields of each record, and the server returns a JSON object with the same shape as the query. The client chooses the fields, so a response carries nothing the client did not ask for, and a different question needs a different query, not a different endpoint.

GraphQL API reads the metrics, events, billing, accounting, and consumption data of your Azion account, with one endpoint per data family under https://api.azion.com/v4. Any client that sends an HTTP POST with a JSON body and a personal token can call it. Use the GraphQL API to chart request trends, rank the IP addresses, URIs, or user agents behind your traffic, investigate blocked requests, or read your bills and product usage.

Query structure

A query names one dataset, the arguments that filter, group, and sort it, and the fields to return. This query adds up the requests of your workloads per time bucket in a seven-day window, newest first:

The metrics endpoint returns HTTP 200 and five rows. The response below is cut after the third row:

• workloadMetrics is the dataset, the table the rows come from. It is served by the metrics endpoint, https://api.azion.com/v4/metrics/graphql.
• filter carries the time window in tsRange. Metrics, events, and consumption datasets refuse a query without one.
• aggregate: { sum: requests } and groupBy: [ts] add up requests per time bucket, and the result field is named sum, after the function.
• limit caps the rows at five. Without it, a query returns 10 rows.

If you have written a GraphQL query before, the syntax is the same. A refused query is the one difference: it returns a JSON object with a detail key, not a GraphQL errors array.

Endpoints and datasets

The GraphQL API is not one endpoint. It is five APIs, each with its own endpoint and schema, and a query goes to the endpoint that serves its dataset:

1. Your client sends the query in a POST request, with the header Authorization: Token [TOKEN VALUE] and the value of a personal token.
2. The request goes to the endpoint of the data family the query reads. A query on the events dataset workloadEvents sent to the metrics endpoint returns 400.
3. The endpoint selects the rows of the dataset that the query names, filtered, grouped, and sorted by its arguments.
4. The response holds one array per dataset under the data key, with one object per row and only the fields the query selected.

Each endpoint serves one family of data:

For the datasets, time resolution, and retention behind each endpoint, refer to How the GraphQL API works.

Scope and limits

• Read only: the GraphQL API answers queries. It has no mutations, and no query changes your account.
• Authentication: every request carries Authorization: Token [TOKEN VALUE]. A Bearer header is refused like a missing one, with 401 and Authentication credentials were not provided. To create a token, refer to Personal tokens.
• Clients: the GraphiQL Playground is an in-browser editor served at each endpoint URL to a signed-in Azion Console session. curl or any HTTP client sends the query as a JSON body, and Run GraphQL queries in Postman covers Postman. The aziontech/azion-queries repository holds query examples to adapt.
• Datasets and fields: Datasets and query arguments lists the datasets of each endpoint and the arguments they share. The fields of each dataset are on Real-Time Metrics fields, Real-Time Events fields, Billing fields, Accounting fields, and Consumption fields. Queries shows a raw, an aggregated, a financial, and a usage query, each with its response.
• Limits: a query returns up to 10,000 rows and selects up to 37 fields on a metrics dataset, or 36 on workloadEvents. Events datasets keep records for about 7 days. Past a row or field bound, the query returns 400, and GraphQL API limits lists every bound.
• Errors: every error is a status code with a JSON body that holds one detail key. Error responses lists each message and its cause, and Troubleshoot the GraphQL API gives the cause and the fix for each symptom.
• Terms: the Glossary defines the terms these pages use, such as dataset, raw data, and adaptive resolver.

Next steps