--- title: "Generation ingest API | Grafana Cloud documentation" description: "HTTP and gRPC contract for exporting generation and workflow step data to Agent Observability." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Generation ingest API The generation ingest API receives structured generation and workflow step data from Agent Observability SDKs. It supports both HTTP and gRPC transports. > Note > > Agent 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` | ## Workflow step endpoints Use workflow step endpoints to export non-LLM execution nodes in an agentic workflow. Workflow steps are linked to generations and appear in the conversation graph and detail view. Expand table | Transport | Endpoint | |-----------|----------------------------------------------------------| | HTTP | `POST /api/v1/workflow-steps:export` | | gRPC | `sigil.v1.WorkflowStepIngestService.ExportWorkflowSteps` | ## 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 | SDK-declared version label. Set this for agent catalog versions and per-version Performance charts. | | `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. | Message parts can contain `text`, `thinking`, `tool_call`, `tool_result`, or `media`. A `media` part stores image/video content metadata plus a `url` value, which may be a data URL, a same-origin URL, or an opaque reference URI depending on the producer and content-capture mode. ## 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_write_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. ## Workflow step request body Each workflow step request contains an array of workflow step objects. Key fields: Expand table | Field | Required | Description | |-------------------------|----------|-----------------------------------------------| | `id` | Yes | Unique workflow step identifier. | | `conversation_id` | Yes | Conversation that contains the workflow step. | | `step_name` | No | Human-readable workflow node name. | | `agent_name` | No | Agent or component that executed the step. | | `agent_version` | No | SDK-declared version label. | | `parent_step_ids` | No | Upstream workflow step IDs for graph edges. | | `linked_generation_ids` | No | LLM generation IDs executed inside this step. | | `input_state` | No | Structured input state for the step. | | `output_state` | No | Structured output state for the step. | | `started_at` | No | Step start timestamp. | | `ended_at` | No | Step completion timestamp. | | `tags` | No | String tags for filtering and grouping. | | `metadata` | No | Key-value metadata pairs. | | `error` | No | Error details if the workflow step failed. | Workflow steps don’t replace generations. Send generations for LLM calls and workflow steps for the surrounding orchestration. ## 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` = `["", ""]` ## 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 and `agent_version` is set, Sigil derives the catalog key from the declared `agent_version`. If both are omitted, Sigil computes a fallback key from the system prompt. The resolved effective version is projection-only and doesn’t modify the stored generation payload. Set `agent_version` when you want catalog, Quality, and Performance views to compare declared releases. The agent catalog can compute an effective version without it, but Performance charts join Prometheus metrics by the SDK-emitted `gen_ai.agent.version` label.