Getting Started with GraphQL

The Instana GraphQL API provides a type-safe interface for querying observability data.

With a single query, you can request exactly the data you need, reducing over-fetching and under-fetching.

Key benefits

  • Single request: Fetch related data, such as applications, services, infrastructure, and events in one query
  • Type safety: Strongly typed schema with built-in documentation
  • Flexible queries: Request only the fields you need
  • Efficient data retrieval: Reduces over-fetching and under-fetching of data
  • Time-based filtering: Query metrics, events, and SLOs with time-based filtering

GraphQL vs REST API

The Instana GraphQL API and REST API serve different use cases. Use the Comparison Between GraphQL API and REST API table to understand the key differences and choose the approach that fits your requirements.

Table 1. Comparison between GraphQL API and REST API
Feature GraphQL API REST API
Data fetching Request specific fields in a single query Endpoints return predefined data structures
Multiple resources Retrieve multiple resources in one query Requires requests to separate endpoints
Over-fetching Reduces over-fetching by returning only requested fields Returns the full predefined response for each endpoint
Under-fetching Retrieve related data in one query Related data may require separate requests
Versioning Schema evolves without versioning API changes typically require versioned endpoints
Real-time Supports subscriptions for real-time data Requires WebSockets or polling
Type system Strongly typed schema with introspection Typing depends on implementation and documentation

The GraphQL API endpoint

All requests go to a single URL:

POST https://<your-instana-host>/api/graphql

Replace <your-instana-host> with your Instana tenant hostname (for example, my-company.instana.io).

Every request is an HTTP POST with a JSON body that contains the query you want to run.

Authentication

Every request must include an API token in the Authorization header:

Authorization: apiToken <your-token>

You create and manage API tokens in the Instana settings in Team Settings → API Tokens. A token must have at least the Default scope to use the GraphQL API.

Make your first request

The following example retrieves the names of your first five applications:

query {
  allApplications(first: 5) {
    edges {
      node {
        id
        name
      }
    }
  }
}

What each part means:

  • allApplications: The field that returns your configured applications.
  • first: 5: Limits the results to the first five items.
  • edges { node { ... } }: The standard wrapper for paginated results (explained below).
  • id name: The fields to return: the unique identifier and the display name.

Example response:

{
  "data": {
    "allApplications": {
      "edges": [
        { "node": { "id": "a1b2c3", "name": "Payment Service" } },
        { "node": { "id": "d4e5f6", "name": "Order Management" } }
      ]
    }
  }
}

Rate limits

The GraphQL API enforces a limit of 5,000 calls per hour per tenant unit. Unlike REST APIs, where the rate limit applies per API token, this limit applies at the tenant unit level. Review the current rate limits before you build integrations to ensure your application stays within the allowed thresholds.