Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana AI Observabilitybreadcrumb arrow Referencebreadcrumb arrow Explore generation ingest API
Grafana Cloud

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

TransportEndpoint
HTTPPOST /api/v1/generations:export
gRPCsigil.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:

FieldRequiredDescription
idYesUnique generation identifier (UUID).
conversation_idYesGroups generations into a conversation thread.
model.providerYesLLM provider name, for example, openai.
model.nameYesModel name, for example, gpt-4o.
modeNoSYNC or STREAM. Default: SYNC.
agent_nameNoAgent identifier for catalog tracking.
agent_versionNoInformational version string.
effective_versionNoSDK-supplied catalog key. Must match sha256:<64 lowercase hex> when set.
system_promptNoSystem prompt text.
inputNoArray of input messages.
outputNoArray of output messages.
toolsNoArray of tool definitions.
usageNoToken usage breakdown.
timestampsNoStart, first token, and end timestamps.
metadataNoKey-value metadata pairs.
tagsNoString tags for filtering.
trace_idNoOpenTelemetry trace ID.
span_idNoOpenTelemetry span ID.
parent_generation_idsNoList of upstream generation IDs for multi-agent dependency tracking.

Token usage fields

FieldDescription
input_tokensTokens in the request.
output_tokensTokens in the response.
cache_read_input_tokensTokens served from cache.
cache_creation_input_tokensTokens written to cache.
reasoning_tokensTokens used for reasoning/thinking.

Tool definitions

FieldDescription
nameTool name.
descriptionTool description.
typeTool type.
input_schema_jsonJSON schema for tool input.
deferredWhether the tool is lazily loaded.

Response

The response contains per-generation results:

FieldDescription
generation_idThe generation ID.
acceptedWhether the generation was accepted.
errorError 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.