GraphQL API

EXPERIMENTAL: This is an experimental 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 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 --server.http.enable-graphql 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 --server.http.enable-graphql flag:

alloy run --server.http.enable-graphql 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 --server.http.enable-graphql-playground flag:

alloy run --server.http.enable-graphql --server.http.enable-graphql-playground 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:

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

The response is a JSON object:

{
  "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.