---
title: "GraphQL API | Grafana Alloy documentation"
description: "Learn about the Grafana Alloy GraphQL API"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# GraphQL API

> **EXPERIMENTAL**: This is an [experimental](/docs/release-life-cycle/) feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the `stability.level` [flag](/docs/alloy/next/reference/cli/run/) to `experimental`.

Grafana Alloy exposes a GraphQL API for querying information about a running instance and its components. You can use the GraphQL API to retrieve build metadata, readiness status, and component health.

Before you begin, ensure you have the following:

- A running Alloy instance.
- The `--feature.graphql.enabled` flag set to `true` when starting Alloy.

## Enable the GraphQL API

The GraphQL API is disabled by default. To enable it, start Alloy with the `--feature.graphql.enabled` flag:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
alloy run --feature.graphql.enabled config.alloy
```

After you enable the API, the `/graphql` endpoint becomes available on the Alloy HTTP server. By default, this is `http://localhost:12345/graphql`.

## GraphQL playground

Alloy includes an optional interactive GraphQL playground that you can use to explore the schema and run queries. To enable the playground, use the `--feature.graphql-playground.enabled` flag:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
alloy run --feature.graphql.enabled --feature.graphql-playground.enabled config.alloy
```

After you enable the playground, it’s available at `/graphql/playground` on the Alloy HTTP server. By default, this is `http://localhost:12345/graphql/playground`.

## Schema

The GraphQL API exposes the following queries.

### `alloy`

Information about the running Alloy instance.

#### Arguments

None.

#### Fields

- **`branch`:** The Git branch from which this build was created.
- **`buildDate`:** The timestamp of when this build was created.
- **`buildUser`:** The user account that initiated this build.
- **`isReady`:** Whether the Alloy instance is up and running.
- **`revision`:** The Git commit hash from which this build was created.
- **`version`:** The semantic version of this Alloy build.

### `components`

All components running in Alloy.

#### Arguments

None.

#### Fields

- **`health`:** Health status of the component.
  
  - **`message`:** Message of the health status.
  - **`lastUpdated`:** Last updated time of the health status.
- **`id`:** Fully qualified ID of the component.
- **`name`:** Name of the component.
- **`arguments`:** Arguments of the component.
- **`exports`:** Exports of the component.
- **`debugInfo`:** Debug info of the component.

### `component`

Component by ID.

#### Arguments

- *`id`* (`ID!`): The id of the component to retrieve.

#### Fields

- **`health`:** Health status of the component.
  
  - **`message`:** Message of the health status.
  - **`lastUpdated`:** Last updated time of the health status.
- **`id`:** Fully qualified ID of the component.
- **`name`:** Name of the component.
- **`arguments`:** Arguments of the component.
- **`exports`:** Exports of the component.
- **`debugInfo`:** Debug info of the component.

The query returns `null` if no component matches the given arguments.

## Example queries

To query the API using `curl`, send a `POST` request to the `/graphql` endpoint with a JSON body containing the `query` field:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
curl -X POST http://localhost:12345/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ alloy { version isReady } }"}'
```

The response is a JSON object:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "data": {
    "alloy": {
      "version": "v1.14.0",
      "isReady": true
    }
  }
}
```

## API details

The GraphQL API has the following behavior:

- **Supported transports:** `OPTIONS`, `GET`, and `POST`.
- **Introspection:** Enabled. You can query the schema using standard GraphQL introspection queries.
- **Timeout:** Each operation has a 10-second timeout.
- **Query caching:** Parsed queries are cached for performance.