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.

Before you begin

Agent Observability is enabled on your Grafana Cloud stack.
You have the Agent Observability API URL, instance ID, and Grafana Cloud access policy token. Refer to Use Agent Observability on Grafana Cloud for setup steps.
Your producer can assign stable generation IDs so retries are idempotent.

Endpoints

Transport	Endpoint
HTTP	`POST /api/v1/generations:export`
gRPC	`agento11y.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.

Transport	Endpoint
HTTP	`POST /api/v1/workflow-steps:export`
gRPC	`agento11y.v1.WorkflowStepIngestService.ExportWorkflowSteps`

Authentication

Use the Grafana Cloud instance ID and Grafana Cloud access policy token you collected from Agent Observability. HTTP requests without valid credentials receive 401 Unauthorized. gRPC requests without valid credentials receive Unauthenticated.

Request body

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

Field	Required	Description
`id`	Yes	Unique, stable generation identifier assigned by your producer.
`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.

Generation and conversation IDs are opaque strings, not necessarily UUIDs. You can use IDs that contain reserved URL characters, for example, session/customer-support/42. Keep the original value in the export payload and reuse each generation ID when retrying its export.

Message parts

Messages can use the system, user, assistant, or tool role. Put model instructions in the top-level system_prompt field when your SDK or framework exposes one. If your producer represents instructions as chat history instead, send them as system role input messages. Evaluation targets and prompt-template variables read the top-level system_prompt field first, then fall back to text from system role input messages when that field is empty.

Message parts can contain text, thinking, tool_call, tool_result, or