AgentRunsListResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gtm/main/json-schema/gtm-agent-runs-list-response-schema.json",
  "title": "AgentRunsListResponse",
  "description": "Response containing a page of agent runs.",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gtm-agent-api-v1-api-openapi.yml#/components/schemas/AgentRunsListResponse",
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentRun"
      },
      "description": "The primary data of the document"
    },
    "meta": {
      "allOf": [
        {
          "$ref": "#/$defs/CursorPagingMeta"
        }
      ],
      "description": "Non-standard meta information about the document"
    },
    "links": {
      "allOf": [
        {
          "$ref": "#/$defs/CursorPagingLinks"
        }
      ],
      "description": "Links related to the primary data"
    }
  },
  "$defs": {
    "AgentArtifactPart": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "Inline text content (text part)."
        },
        "file": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentFileContent"
            }
          ],
          "description": "File content by link or bytes (file part)."
        },
        "data": {
          "description": "Structured content with no downloadable form, e.g. a created CRM record or a data agent's structured result (data part)."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata for this part."
        }
      },
      "description": "One part of an artifact. Exactly one of `text`, `file`, or `data` is set,\nwhich determines the part's kind; `metadata` may accompany any. The\nmultipart protocol (chunk concatenation, rendering) keys off which one is\nset."
    },
    "AgentExecutionMode": {
      "type": "string",
      "enum": [
        "SYNC",
        "STREAMING",
        "ASYNC"
      ],
      "description": "Execution modes an agent supports.",
      "x-enumDescriptions": {
        "SYNC": "The connection is held until the run completes or the synchronous window elapses; an in-progress run is returned on expiry.",
        "STREAMING": "Server-sent events streamed as the run progresses.",
        "ASYNC": "Submit and receive the in-progress run at once; retrieve the outcome via Get Agent Run. Available for every agent that supports synchronous execution."
      }
    },
    "AgentFileContent": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "format": "uri",
          "description": "Link to downloadable content (e.g. a generated document)."
        },
        "bytes": {
          "type": "string",
          "description": "Base64-encoded binary content."
        },
        "name": {
          "type": "string",
          "description": "Display filename."
        },
        "mimeType": {
          "type": "string",
          "description": "MIME type of the file content."
        }
      },
      "description": "File content: exactly one of `uri` (a link, e.g. the platform's\ntoken-gated document route) or `bytes` (base64). `name` is always present\non emitted files (the server falls back to the object type rather than\nemit a nameless file)."
    },
    "AgentMessage": {
      "type": "object",
      "required": [
        "messageId",
        "role",
        "parts"
      ],
      "properties": {
        "messageId": {
          "type": "string",
          "description": "Unique message identifier."
        },
        "contextId": {
          "type": "string",
          "description": "Conversation this message belongs to."
        },
        "taskId": {
          "type": "string",
          "description": "Run this message belongs to (the runId)."
        },
        "role": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentMessageRole"
            }
          ],
          "description": "Who the message is from."
        },
        "parts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentArtifactPart"
          },
          "description": "The message's content parts."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata."
        }
      },
      "description": "A message: the shape carried by `status.message`, `history`, and the stream `message` frame (that frame is reserved for future use and not currently emitted)."
    },
    "AgentMessageRole": {
      "type": "string",
      "enum": [
        "ROLE_UNSPECIFIED",
        "ROLE_USER",
        "ROLE_AGENT"
      ],
      "description": "Who a message is from.",
      "x-enumDescriptions": {
        "ROLE_UNSPECIFIED": "Unspecified.",
        "ROLE_USER": "From the client to the agent.",
        "ROLE_AGENT": "From the agent to the client."
      }
    },
    "AgentRun": {
      "type": "object",
      "required": [
        "id",
        "type",
        "attributes"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique identifier for the resource"
        },
        "type": {
          "type": "string",
          "description": "The type of the resource",
          "default": "AgentRun",
          "pattern": "AgentRun"
        },
        "attributes": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        },
        "meta": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunMeta"
            }
          ],
          "description": "Non-standard meta information about the resource"
        }
      },
      "description": "An agent run. The resource id is the runId, surfaced as taskId on every stream event."
    },
    "AgentRunArtifact": {
      "type": "object",
      "required": [
        "artifactId",
        "parts"
      ],
      "properties": {
        "artifactId": {
          "type": "string",
          "description": "Unique identifier of the artifact within the run."
        },
        "name": {
          "type": "string",
          "description": "Display name of the artifact."
        },
        "description": {
          "type": "string",
          "description": "What the artifact contains."
        },
        "parts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentArtifactPart"
          },
          "description": "The artifact's content parts. May carry more than one part, e.g. a text rendition and a structured `data` part."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata, e.g. the tool that created the artifact."
        }
      },
      "description": "An output artifact of a run. Available when the terminal\nstate is COMPLETED; a completed run carries at least one, and the response\nartifact is the complete record of the result. A chat agent returns a\nsingle text part; a data agent returns a multi-part artifact carrying both\nrenditions, e.g. `parts: [ { text }, { data } ]`, where the `data` part\nholds the structured payload. Over the stream the parts arrive across\nappend-only chunks (the final `lastChunk` event delivers the data part\nbeside the text tail), so a streaming client assembles the same artifact a\nGet Agent Run returns. The first artifact of a run is its response; see\nAgentRunAttributes.artifacts."
    },
    "AgentRunAttributes": {
      "type": "object",
      "required": [
        "agentId",
        "status",
        "executionMode",
        "input",
        "initiatedBy"
      ],
      "properties": {
        "agentId": {
          "type": "string",
          "description": "The agent that was executed."
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunStatus"
            }
          ],
          "description": "Current task status."
        },
        "executionMode": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentExecutionMode"
            }
          ],
          "description": "Execution mode used for the run."
        },
        "input": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunMessage"
            }
          ],
          "description": "The caller's input message, echoed back verbatim as it was sent -- the same `{ parts: [...] }` the run was started with. The run has no separate output field: the result is the run's `artifacts` (parts in, parts out)."
        },
        "contextId": {
          "type": "string",
          "description": "The conversation this run belongs to, as a UUID, identical across the run's POST response, Get Agent Run, stream, and resume. For platform agents it is the conversation thread and can be passed back on a later run to continue it. For Teams agents it is always present -- a fresh server-minted per-run UUID -- but is an identity handle only: passing it back resumes nothing (Teams runs are single-shot)."
        },
        "artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentRunArtifact"
          },
          "description": "The run's artifacts; present when the terminal state is COMPLETED, and at\nleast one is always present then. The FIRST artifact is the run's\nresponse: its text part is the reply prose, and a data part beside it\ncarries the structured result when the agent produced one. Further\nartifacts are supporting deliverables, e.g. generated documents (file\nparts) or referenced objects."
        },
        "error": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunError"
            }
          ],
          "description": "Machine-readable failure details; present when the run FAILED."
        },
        "durationMs": {
          "type": "integer",
          "format": "int64",
          "description": "Total execution duration in milliseconds. Present once the run reaches a terminal state."
        },
        "initiatedBy": {
          "allOf": [
            {
              "$ref": "#/$defs/RunInitiator"
            }
          ],
          "description": "The identity that initiated the run."
        },
        "history": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentMessage"
          },
          "description": "Task history: prior messages exchanged within the run's context."
        },
        "extensions": {
          "type": "object",
          "additionalProperties": {},
          "description": "Extension data contributed to the run."
        }
      },
      "description": "Attributes describing an agent run."
    },
    "AgentRunError": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code, e.g. `AGENT_EXECUTION_FAILED`."
        },
        "message": {
          "type": "string",
          "description": "Human-readable, sanitized explanation. Never carries internal system detail."
        },
        "retryable": {
          "type": "boolean",
          "description": "Whether retrying the identical request may succeed. Defaults to false."
        }
      },
      "description": "Machine-readable failure details. Present when the run FAILED; may be present for CANCELED when a safe cancellation reason exists."
    },
    "AgentRunMessage": {
      "type": "object",
      "required": [
        "parts"
      ],
      "properties": {
        "parts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentArtifactPart"
          },
          "description": "The message's content parts. Each is exactly one of `text`, `file`, or `data`; at most one `data` part is allowed."
        }
      },
      "description": "The caller's message to the agent -- the run's entire input, as an ordered\nlist of content parts (the same part shape artifacts use). There is no\n`role` (the sender is always the caller) and no message id (the run itself\nis the identity), so `parts` is the whole of it.\n\nParts by kind: `text` parts carry prose and are joined into the agent's\nprompt; a `data` part carries the structured argument object the agent's\n`inputSchema` data entry types; `file` parts are declared in the shape but not yet\naccepted. AT MOST ONE `data` part may be present -- parts have no names and\ntheir order carries no meaning, so a second anonymous payload would be\nstructure no schema can address; nest multiple structured payloads inside\nthe one data object instead."
    },
    "AgentRunMeta": {
      "type": "object",
      "required": [
        "createdAt",
        "updatedAt"
      ],
      "properties": {
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the run was created."
        },
        "startedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When execution actually began."
        },
        "completedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the run reached a terminal state."
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the run last changed."
        },
        "totalCredits": {
          "type": "integer",
          "format": "int32",
          "description": "Total AI credits consumed. Present once the run reaches a terminal state."
        }
      },
      "description": "Timestamps and metering for an agent run."
    },
    "AgentRunStatus": {
      "type": "object",
      "required": [
        "state"
      ],
      "properties": {
        "state": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentTaskState"
            }
          ],
          "description": "The task state."
        },
        "message": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentMessage"
            }
          ],
          "description": "A message elaborating this status, e.g. an agent's explanation of a failure or a prompt for further input."
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "When this state was entered."
        }
      },
      "description": "Current status of a run."
    },
    "AgentTaskState": {
      "type": "string",
      "enum": [
        "TASK_STATE_UNSPECIFIED",
        "TASK_STATE_SUBMITTED",
        "TASK_STATE_WORKING",
        "TASK_STATE_INPUT_REQUIRED",
        "TASK_STATE_AUTH_REQUIRED",
        "TASK_STATE_COMPLETED",
        "TASK_STATE_FAILED",
        "TASK_STATE_CANCELED",
        "TASK_STATE_REJECTED"
      ],
      "description": "Task lifecycle states for a run.\nTerminal: COMPLETED, FAILED, CANCELED, REJECTED. Interrupted:\nINPUT_REQUIRED, AUTH_REQUIRED. Everything else is non-terminal.\nConsumers must tolerate unknown values, treating UNSPECIFIED as the\nfallback for states this version does not define.\n\nThe service currently emits SUBMITTED, WORKING, COMPLETED, and FAILED\n(plus the UNSPECIFIED fallback). CANCELED and REJECTED are reserved for\ncancellation support; INPUT_REQUIRED and AUTH_REQUIRED are reserved for\ninteractive runs. Consumers should handle all nine states.",
      "x-enumDescriptions": {
        "TASK_STATE_UNSPECIFIED": "The task state is unknown or has not been set. Non-terminal.",
        "TASK_STATE_SUBMITTED": "The task was accepted and is waiting to begin. Non-terminal.",
        "TASK_STATE_WORKING": "The agent is actively processing the task. Non-terminal.",
        "TASK_STATE_INPUT_REQUIRED": "The agent needs additional user or client input. Interrupted.",
        "TASK_STATE_AUTH_REQUIRED": "Additional authentication is required. Interrupted.",
        "TASK_STATE_COMPLETED": "The task completed successfully. Terminal.",
        "TASK_STATE_FAILED": "The task ended because of an execution error. Terminal.",
        "TASK_STATE_CANCELED": "The task was canceled before completion. Terminal.",
        "TASK_STATE_REJECTED": "The agent declined or could not accept the task. Terminal."
      }
    },
    "CursorPageInfo": {
      "type": "object",
      "required": [
        "pageSize",
        "totalCount"
      ],
      "properties": {
        "pageSize": {
          "type": "integer",
          "format": "uint32",
          "description": "The page size as specified by the request."
        },
        "totalCount": {
          "type": "integer",
          "format": "uint32",
          "description": "The total count of results matching the current filters."
        }
      },
      "description": "Page details for a cursor-paged collection."
    },
    "CursorPagingLinks": {
      "type": "object",
      "properties": {
        "self": {
          "type": "string",
          "format": "uri",
          "description": "The link that generated the current response document"
        },
        "prev": {
          "type": "string",
          "format": "uri",
          "description": "A link to the previous page of data"
        },
        "next": {
          "type": "string",
          "format": "uri",
          "description": "A link to the next page of data"
        }
      },
      "description": "Links for a cursor-paged collection. `next` is omitted on the last page and `prev` on the first."
    },
    "CursorPagingMeta": {
      "type": "object",
      "required": [
        "page"
      ],
      "properties": {
        "page": {
          "allOf": [
            {
              "$ref": "#/$defs/CursorPageInfo"
            }
          ],
          "description": "Page details."
        }
      },
      "description": "Metadata for a cursor-paged collection."
    },
    "RunInitiator": {
      "type": "object",
      "required": [
        "type",
        "id"
      ],
      "properties": {
        "type": {
          "allOf": [
            {
              "$ref": "#/$defs/RunInitiatorType"
            }
          ],
          "description": "The kind of initiator."
        },
        "id": {
          "type": "string",
          "description": "Identifier of the initiator (user id, workflow id, or API client id)."
        }
      },
      "description": "The identity that initiated the run."
    },
    "RunInitiatorType": {
      "type": "string",
      "enum": [
        "USER",
        "WORKFLOW",
        "API"
      ],
      "description": "The kind of identity that initiated a run.",
      "x-enumDescriptions": {
        "USER": "An end user.",
        "WORKFLOW": "An automated workflow.",
        "API": "An API client credential."
      }
    }
  }
}