{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Message identifier."
},
"conversation_id": {
"type": "string",
"description": "Conversation identifier that owns the message."
},
"parent_id": {
"type": [
"string",
"null"
],
"description": "Parent message identifier when the message belongs to a branch or reply chain."
},
"seq": {
"type": "number",
"description": "Monotonic sequence number within the conversation."
},
"role": {
"type": "string",
"description": "Message role such as user, assistant, tool, or system."
},
"created_by": {
"type": [
"string",
"null"
],
"description": "User or actor identifier that created the message."
},
"sender_type": {
"type": "string",
"description": "Sender kind: user, webhook, service_account, integration, agent or system."
},
"sender_id": {
"type": [
"string",
"null"
],
"description": "Sender identifier: the participant or agent for an agent message, otherwise the author."
},
"sender_display_name": {
"type": [
"string",
"null"
],
"description": "Human-readable sender name when available."
},
"parts": {
"type": "array",
"items": {
"description": "One part item associated with this record."
},
"description": "Structured message parts, including text, tool invocations, or rich content blocks."
},
"model": {
"type": [
"string",
"null"
],
"description": "Model identifier that generated the message, when applicable."
},
"run_usage": {
"anyOf": [
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"const": "run",
"description": "The scope associated with this record."
},
"model": {
"type": [
"string",
"null"
],
"description": "AI model id or alias. Call list_models for the ids this deployment serves; never invent a version suffix."
},
"input_tokens": {
"type": "integer",
"minimum": 0,
"description": "The input tokens associated with this record."
},
"output_tokens": {
"type": "integer",
"minimum": 0,
"description": "The output tokens associated with this record."
},
"cache_creation_input_tokens": {
"type": "integer",
"minimum": 0,
"description": "The cache creation input tokens associated with this record."
},
"cache_read_input_tokens": {
"type": "integer",
"minimum": 0,
"description": "The cache read input tokens associated with this record."
},
"reasoning_tokens": {
"type": "integer",
"minimum": 0,
"description": "The reasoning tokens associated with this record."
},
"total_tokens": {
"type": "integer",
"minimum": 0,
"description": "The total tokens associated with this record."
},
"model_calls": {
"type": "integer",
"minimum": 0,
"description": "The model calls associated with this record."
},
"cost_credits": {
"type": [
"string",
"null"
],
"description": "The cost credits associated with this record."
}
},
"required": [
"scope",
"model",
"input_tokens",
"output_tokens",
"cache_creation_input_tokens",
"cache_read_input_tokens",
"reasoning_tokens",
"total_tokens",
"model_calls",
"cost_credits"
],
"additionalProperties": false,
"description": "Structured run usage details associated with this record."
},
{
"type": "null",
"description": "The run usage returned by the tool."
}
],
"description": "Token usage and cost of the whole run that produced an assistant message; absent when none is recorded."
},
"token_usage": {
"anyOf": [
{
"description": "The token usage associated with this record."
},
{
"type": "null",
"description": "The token usage returned by the tool."
}
],
"description": "Token accounting metadata associated with the message."
},
"finish_reason": {
"type": [
"string",
"null"
],
"description": "Completion finish reason for model-generated messages."
},
"cost_credits": {
"type": [
"string",
"null"
],
"description": "Credit cost attributed to the message, when tracked."
},
"status": {
"type": "string",
"description": "Lifecycle status of the message."
},
"edited_at": {
"type": [
"string",
"null"
],
"description": "Timestamp when the message was edited, or null when unedited."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "Idempotency key used to deduplicate message creation requests."
},
"metadata": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"description": "Additional structured values associated with this result."
},
"description": "Additional structured metadata for the record."
},
{
"type": "null",
"description": "Additional structured metadata returned by the tool."
}
],
"description": "Additional machine-readable message metadata."
},
"created_at": {
"type": "string",
"description": "Timestamp when the message was created."
},
"updated_at": {
"type": [
"string",
"null"
],
"description": "Timestamp when the message was last updated."
}
},
"required": [
"id",
"conversation_id",
"parent_id",
"seq",
"role",
"created_by",
"sender_type",
"sender_id",
"sender_display_name",
"parts",
"model",
"finish_reason",
"cost_credits",
"status",
"edited_at",
"idempotency_key",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false,
"description": "Conversation message record returned by MCP conversation tools."
},
"description": "Primary result records returned by the tool."
},
"page_info": {
"type": "object",
"properties": {
"self": {
"type": [
"string",
"null"
],
"description": "Cursor representing the current page."
},
"first": {
"type": "null",
"description": "Always null because these MCP pagination flows do not expose a first-page cursor."
},
"next": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results."
},
"prev": {
"type": [
"string",
"null"
],
"description": "Cursor for the previous page, or null when unavailable."
}
},
"required": [
"self",
"first",
"next",
"prev"
],
"additionalProperties": false,
"description": "Cursor-based pagination metadata for conversation tool responses."
}
},
"required": [
"data",
"page_info"
],
"additionalProperties": false,
"description": "Structured result returned by the list_conversation_message_branches tool.",
"$schema": "http://json-schema.org/draft-07/schema#"
}
