Metadata

metadata is validated JSON trace data. The API limits total size, key count, depth, list length, key format, and value types. Stable errors include metadata_too_large, metadata_too_many_keys, metadata_too_deep, metadata_invalid_key, metadata_invalid_value, and metadata_list_too_large.

metadata accepts an optional JSON object recorded with the invocation for technical traceability.

await client.responses.create({
  message: "Summarize the opportunity",
  metadata: { source: "crm", recordId: "lead_456", environment: "production" },
});

Use short, stable, non-sensitive fields. Metadata is not added to the prompt and does not change agent instructions. If the agent needs a value to answer, include it in message or in a configured Knowledge source.