Query GraphQL schema metadata

List the datasets a GraphQL API endpoint serves, the fields of each dataset, and their types with an introspection query.

Last updated

View as Markdown Agent setup

You can ask the GraphQL API which datasets an endpoint serves, which fields each dataset returns, and the type of each field. The answer comes from an introspection query, which reads the schema instead of your data. Use it to check a dataset or field name before you write a query.

Prerequisites

List datasets and their fields

Each endpoint describes only its own datasets. The steps below query https://api.azion.com/v4/metrics/graphql, which serves the metrics datasets. To list the datasets of another endpoint, such as https://api.azion.com/v4/events/graphql, send the same queries there.

To read the schema of the metrics endpoint:

Send the introspection query

Send this query in a POST request to https://api.azion.com/v4/metrics/graphql, with the header Authorization: Token [TOKEN VALUE]. To send a query, refer to GraphQL API quickstart or Run GraphQL queries in Postman.

GraphQL
01query introspectionQuery {
02 __type(name: "Query") {
03 name
04 description
05 fields {
06 name
07 description
08 type {
09 ofType {
10 fields {
11 name
12 type {
13 name
14 }
15 }
16 }
17 }
18 }
19 }
20}
Check the datasets in the response

The API answers with HTTP 200 and one entry per dataset in fields. The response below is cut after the third dataset, and after the third field of each dataset:

JSON
01{
02 "data": {
03 "__type": {
04 "name": "Query",
05 "description": null,
06 "fields": [
07 {
08 "name": "realTimeEventsQueriesMetrics",
09 "description": "Real-Time Events Metrics dataset query by Minute, Hour and Day with aggregate options.",
10 "type": {
11 "ofType": {
12 "fields": [
13 {
14 "name": "ts",
15 "type": {
16 "name": "CustomDateTime"
17 }
18 },
19 {
20 "name": "sourceLocPop",
21 "type": {
22 "name": "String"
23 }
24 },
25 {
26 "name": "configurationId",
27 "type": {
28 "name": "Int"
29 }
30 },
31 …
32 ]
33 }
34 }
35 },
36 {
37 "name": "aiMetrics",
38 "description": "Query AI Metrics with aggregate options.",
39 "type": {
40 "ofType": {
41 "fields": [
42 {
43 "name": "ts",
44 "type": {
45 "name": "CustomDateTime"
46 }
47 },
48 {
49 "name": "sourceLocPop",
50 "type": {
51 "name": "String"
52 }
53 },
54 {
55 "name": "configurationId",
56 "type": {
57 "name": "Int"
58 }
59 },
60 …
61 ]
62 }
63 }
64 },
65 {
66 "name": "objectStorageMetrics",
67 "description": "Object Storage Metrics dataset query by Day with aggregate options.",
68 "type": {
69 "ofType": {
70 "fields": [
71 {
72 "name": "ts",
73 "type": {
74 "name": "CustomDateTime"
75 }
76 },
77 {
78 "name": "location",
79 "type": {
80 "name": "String"
81 }
82 },
83 {
84 "name": "bucketId",
85 "type": {
86 "name": "String"
87 }
88 },
89 …
90 ]
91 }
92 }
93 },
94 …
95 ]
96 }
97 }
98}
List the deprecated datasets

The first query leaves out deprecated datasets, such as httpMetrics, which workloadMetrics replaces. To list every dataset with its deprecation status, send this query to the same endpoint:

GraphQL
01query {
02 __type(name: "Query") {
03 fields(includeDeprecated: true) { name isDeprecated deprecationReason }
04 }
05}

The API answers with HTTP 200. The response below is cut after the third dataset:

JSON
01{
02 "data": {
03 "__type": {
04 "fields": [
05 {
06 "name": "realTimeEventsQueriesMetrics",
07 "isDeprecated": false,
08 "deprecationReason": null
09 },
10 {
11 "name": "aiMetrics",
12 "isDeprecated": false,
13 "deprecationReason": null
14 },
15 {
16 "name": "edgeAIMetrics",
17 "isDeprecated": true,
18 "deprecationReason": "Use aiMetrics instead."
19 },
20 …
21 ]
22 }
23 }
24}

You have the name, description, and field list of each dataset the endpoint serves, and the replacement of each deprecated one.

Read the response

Each key of the two responses describes one part of the schema:

KeyWhat it holds
nameQuery, the root type that holds every dataset of the endpoint.
descriptionThe description of the root type. It is null.
fields[].nameThe name of a dataset, the name you put in a query.
fields[].descriptionWhat the dataset holds. Most descriptions also name the time buckets the dataset groups data into, such as minute, hour, and day.
fields[].type.ofType.fieldsThe fields the dataset returns, each with its name and the name of its type.
type.name of a fieldThe type of the field’s value, such as CustomDateTime for ts, String, or Int.
isDeprecated and deprecationReasonWhether a dataset is deprecated and, when it is, the dataset to use instead.

Next steps

Datasets and query argumentsSee every dataset by endpoint and the arguments each query accepts.Real-Time Metrics fieldsRead what each field of the metrics datasets returns.Real-Time Events fieldsRead what each field of the event datasets returns.QueriesWrite raw, aggregated, financial, and usage queries with the names you found.