# Transcend's GraphQL API (/docs/overview/developer-tools/graphql-api)

## Overview [#overview]

Transcend offers a GraphQL API to interact with its offerings, in an automated fashion.

<Callout type="info">
  **Note on Terminology**: While our documentation refers to "Data Systems", the GraphQL API uses the legacy field name `dataSilos` for backward compatibility. When working with the API, use `dataSilos` in your queries and mutations to reference Data Systems.
</Callout>

## Using the GraphQL API [#using-the-graphql-api]

The GraphQL API is hosted at `https://api.transcend.io/graphql` (or `https://api.us.transcend.io/graphql` if you are a US-based customer). You can visit those pages
using a web browser to find an GraphQL playground to discover all the different queries and operations we support using the GraphQL API.

### Authentication [#authentication]

You will need an API key generated from the Transcend Admin-dashboard, with the appropriate scopes granted to the key, for the routes you wish to use. Include
the API key generated as a Bearer token, with the `Authorization` header in any requests you send to the GraphQL API.

## Best Practices [#best-practices]

We have an established set of best practices when calling our GraphQL API, especially for certain queries and mutations.

### Read Requests [#read-requests]

When using the GraphQL API for a query to read some information from Transcend's systems, we recommend you use the `useMaster: false` parameter in order to route your
requests to our read-replicas. While the GraphQL resolver will certainly attempt to route your query to the right database instance to process your query, we recommend using
this parameter to avoid any ambiguity.

Our read-replicas have a typical replication lag of about 100 milliseconds.

An example query with the `useMaster` parameter is:

```graphql
query ListDataSilos {
  dataSilos(first: 10, useMaster: false) {
    nodes {
      id
      title
      type
    }
  }
}
```

### Query-specific Optimisations [#query-specific-optimisations]

#### `subDataPoints` [#subdatapoints]

When repeatedly calling the `subDataPoints` GraphQL query, we recommend using a cursor-based pagination using the `id` attribute to massively decrease the response times
to your queries. Each subsequent call to the GraphQL query would use the `id` attribute of the last `subDataPoint` in the response (`nodes[nodes.length - 1].id`), as
the cursor for the next page of results.

An example query is:

```graphql
query ListSubDataPointsByDataSilo($datasilo: ID!, $id_cursor: ID!) {
  subDataPoints(
    first: 100
    filterBy: { dataSilos: [$datasilo], cursor: { id: $id_cursor } }
    useMaster: false
  ) {
    nodes {
      id
      name
    }
    totalCount
  }
}
```