---
title: "Generation ingest API | Grafana Cloud documentation"
description: "HTTP and gRPC contract for exporting generation data to AI Observability."
---

# Generation ingest API

The generation ingest API receives structured generation data from AI Observability SDKs. It supports both HTTP and gRPC transports.

> Note
> 
> AI Observability is referred to as “Sigil” in API paths, gRPC service names, and configuration. For example, the gRPC service is `sigil.v1.GenerationIngestService` and authentication variables use the `SIGIL_` prefix.

## Endpoints

Expand table

| Transport | Endpoint                                             |
|-----------|------------------------------------------------------|
| HTTP      | `POST /api/v1/generations:export`                    |
| gRPC      | `sigil.v1.GenerationIngestService.ExportGenerations` |

## Authentication

The `X-Scope-OrgID` header identifies the tenant. When authentication is enabled (`SIGIL_AUTH_ENABLED=true`):

- HTTP requests without the header receive `401 Unauthorized`.
- gRPC requests without the header receive `Unauthenticated`.

When authentication is disabled, the server injects the fake tenant ID.

## Request body

Each request contains an array of generation objects. Key fields:

Expand table

| Field                   | Required | Description                                                                |
|-------------------------|----------|----------------------------------------------------------------------------|
| `id`                    | Yes      | Unique generation identifier (UUID).                                       |
| `conversation_id`       | Yes      | Groups generations into a conversation thread.                             |
| `model.provider`        | Yes      | LLM provider name, for example, `openai`.                                  |
| `model.name`            | Yes      | Model name, for example, `gpt-4o`.                                         |
| `mode`                  | No       | `SYNC` or `STREAM`. Default: `SYNC`.                                       |
| `agent_name`            | No       | Agent identifier for catalog tracking.                                     |
| `agent_version`         | No       | Informational version string.                                              |
| `effective_version`     | No       | SDK-supplied catalog key. Must match `sha256:<64 lowercase hex>` when set. |
| `system_prompt`         | No       | System prompt text.                                                        |
| `input`                 | No       | Array of input messages.                                                   |
| `output`                | No       | Array of output messages.                                                  |
| `tools`                 | No       | Array of tool definitions.                                                 |
| `usage`                 | No       | Token usage breakdown.                                                     |
| `timestamps`            | No       | Start, first token, and end timestamps.                                    |
| `metadata`              | No       | Key-value metadata pairs.                                                  |
| `tags`                  | No       | String tags for filtering.                                                 |
| `trace_id`              | No       | OpenTelemetry trace ID.                                                    |
| `span_id`               | No       | OpenTelemetry span ID.                                                     |
| `parent_generation_ids` | No       | List of upstream generation IDs for multi-agent dependency tracking.       |

## Token usage fields

Expand table

| Field                         | Description                         |
|-------------------------------|-------------------------------------|
| `input_tokens`                | Tokens in the request.              |
| `output_tokens`               | Tokens in the response.             |
| `cache_read_input_tokens`     | Tokens served from cache.           |
| `cache_creation_input_tokens` | Tokens written to cache.            |
| `reasoning_tokens`            | Tokens used for reasoning/thinking. |

## Tool definitions

Expand table

| Field               | Description                        |
|---------------------|------------------------------------|
| `name`              | Tool name.                         |
| `description`       | Tool description.                  |
| `type`              | Tool type.                         |
| `input_schema_json` | JSON schema for tool input.        |
| `deferred`          | Whether the tool is lazily loaded. |

## Response

The response contains per-generation results:

Expand table

| Field           | Description                          |
|-----------------|--------------------------------------|
| `generation_id` | The generation ID.                   |
| `accepted`      | Whether the generation was accepted. |
| `error`         | Error message if rejected.           |

Partial success is supported — some generations may be accepted while others are rejected.

## Multi-agent dependency tracking

The `parent_generation_ids` field lets you declare parent-child relationships between generations. Set it to the list of generation IDs whose output the current generation consumes. Sigil uses these links to build a dependency DAG and propagate quality signals — if an upstream generation fails evaluation, all downstream dependents are flagged.

For example, in an orchestrator that spawns agents A, B, and C where C depends on A and B:

- A: `parent_generation_ids` = `[]`
- B: `parent_generation_ids` = `[]`
- C: `parent_generation_ids` = `["<A_GENERATION_ID>", "<B_GENERATION_ID>"]`

## Agent version computation

Sigil resolves an effective agent version as `sha256:<64 lowercase hex>` for agent catalog queries. If `effective_version` is set, Sigil validates and uses that SDK-supplied catalog key. If it is omitted or blank, Sigil computes a fallback key from the canonical combination of `system_prompt` and `tools`. The resolved effective version is projection-only and doesn’t modify the stored generation payload.