Forming Calls

Learn how to authenticate with the GraphQL API in order to create and run queries and mutations.

Authentication

Once your account is provisioned, an account admin can grant individuals developer access via your account settings page. Users with developer permissions will then have the ability to issue an API key for themselves and gain access to our API Explorer. The API key that is granted to a user issues queries and mutations under that user's roles and permissions.

The Arize GraphQL API is available to enterprise-grade customers. To upgrade your account contact [e-mail]

The GraphQL endpoint

While a typical REST endpoint has multiple endpoints, the GraphQL API has a single endpoint: https://app.arize.com/graphql

Communicating with GraphQL

Because GraphQL operations consist of complex, nested structures, we recommend using the Explorer to make GraphQL calls. You can also use cURL or any other HTTP-speaking library.

In REST, HTTP determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is POST.

To query GraphQL using cURL, make a POST request with a JSON payload. The payload must contain a string called query:

curl -H "x-api-key: graphql_api_key" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{ "query": "query { viewer { user { name } }}" }' \
  https://app.arize.com/graphql

Note: The string value "query" must escape newline characters or the schema will not parse it correctly. For the POST body, use outer double quotes and escaped inner double quotes.

As you can see, GraphQL is simply an HTTP POST and does not require any particular library. However, we highly recommend you use a client library as it can vastly improve your developer experience. In our tutorials we will make use of the following clients in our script examples:

Python: gql

JavaScript: graphql-request

About query and mutation operations

The two types of allowed operations in Arize's GraphQL API are queries and mutations. Comparing GraphQL to REST, queries operate like GET requests, while mutations operate like POST/PATCH/DELETE. The mutation name determines which modification is executed.

For information about rate limiting, please consult our resource limitations guide.

Queries and mutations share similar forms, with some important differences.

About queries

GraphQL queries return only the data you specify. To form a query, you must specify fields within fields (also known as nested subfields) until you return only scalars.

Queries are structured like this:

query {
    Objects or scalars to return
}

Here is a simple example of how to pull your information

Query

query {
  viewer {
    user {
      name
      email
    }
  }
  account {
    name
  }
}

Response

{
  "data": {
    "viewer": {
      "user": {
        "name": "Arize Support",
        "email": "[e-mail]"
      }
    },
    "account": {
      "name": "Arize AI"
    }
  }
}

Having trouble? Reach out to us via email [e-mail] or Slack us in the #arize-support channel for more support.