---
title: "GraphQL API"
description: "The Call AI GraphQL endpoint, the query mechanics it supports, and how it reports errors."
contentType: "overview"
url: "https://developer.mindtickle.com/docs/call-ai/graphql-api/"
---

The Call AI GraphQL API returns conversation intelligence data, such as call recordings, transcripts, and insights, from a single endpoint. You choose the fields you need in the query, so one request returns exactly the data you ask for.

Send all requests to `https://api-gateway.callai.mindtickle.com/public/graphapi` with `Content-Type: application/json` and `Authorization: Bearer ACCESS_TOKEN`. See [Authentication](/docs/call-ai/authentication/) for the token.

## GraphQL overview

GraphQL is a query language for APIs that lets you request exactly the data you need. The selection set defines which fields the server returns, so you can limit a request to the information your integration needs.

For example, the following query fetches a list of recordings with the `recordingsV2` operation:

```graphql
{
  recordingsV2(
    first: 1
    after: "0"
    filters: { categoryId: "1" }
    sort: { sortType: "start_date", sortOrder: desc }
  ) {
    edges {
      node {
        id
        mediaUrls {
          streamingSource
        }
      }
    }
  }
}
```

## Interacting with the API

You can interact directly with the Call AI API with standard HTTP clients or command-line tools such as cURL.

:::note
Keep the batch size low, ideally fewer than 10 meetings per batch, and make your script wait at least 60 seconds between successive batches to avoid rate limit errors.
:::

If you encounter errors related to exhausted credits, see [Error handling](/docs/call-ai/graphql-api/#error-handling) and reduce the batch size before retrying.

The following cURL command authenticates and fetches a list of recordings. Replace `ACCESS_TOKEN` with your OAuth access token.

```bash
curl --location 'https://api-gateway.callai.mindtickle.com/public/graphapi' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer ACCESS_TOKEN' \
 --data '{"query":"query {\n    recordingsV2(\n        first: 1,\n        after: \"0\",\n        filters: {\n            categoryId: \"1\"\n        }\n        sort: {\n            sortType: \"start_date\",\n            sortOrder: asc\n        }\n    )\n    {\n        edges {\n            node {\n                id\n                mediaUrls {\n                    streamingSource\n                }\n            }\n        }\n    }\n}\n","variables":{}}'
```

## Endpoints

- [Query call data](/docs/call-ai/graphql-api/query-call-data/): fetch recordings with the `recordingsV2` query, including participants, transcripts, themes, stats, and scores.
- [Download call recordings](/docs/call-ai/graphql-api/download-call-recordings/): retrieve pre-signed URLs for the audio and video files of a recording.

## Error handling

In GraphQL, a request may return an HTTP `200 OK` status even if it fails. Check the response body for an `errors` array as well as checking the HTTP status. GraphQL responses can contain both partial `data` and `errors`; do not assume HTTP 200 means every requested field succeeded.

The following structure uses type placeholders. Replace `"number"` and `"string"` with the corresponding values when interpreting an error response.

```json
{
  "errors": [
    {
      "message": "string",
      "locations": [
        {
          "line": "number",
          "column": "number"
        }
      ],
      "path": ["string"],
      "extensions": {
        "code": "string",
        "originalError": {
          "code": "string",
          "message": "string",
          "details": {}
        },
        "creditsInfo": {
          "maximumAvailable": "number",
          "currentlyAvailable": "number",
          "willResetAt": "string"
        },
        "requestedQueryCost": "number"
      }
    }
  ],
  "data": null
}
```

Recommended actions:

- For each object in `errors`, if `extensions.code` is `INSUFFICIENT_CREDITS`, you have exceeded the rate limit. Reduce your pagination size or request hit rate. Check the `creditsInfo` object in the error response to view your current availability.
- For each object in `errors`, if `extensions.code` is `INTERNAL_SERVER_ERROR` and its `message` contains the string `/authenticate - Request failed with status code 404`, your access token has expired. Refresh the access token. See [Refresh an access token](/docs/call-ai/authentication/refresh-an-access-token/).

## Related

- [Authentication](/docs/call-ai/authentication/): generate the access token these requests need.