> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get response > Retrieves the current state of an agent response by task ID. Returns the response output, model information, token usage, and execution status. When the agent is still processing, the output array will be empty and status will be `in_progress`. Once completed, the response includes the full output, usage statistics, and finish reason. ## OpenAPI ````yaml get /v2/agents/{agent_key}/responses/{task_id} openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/agents/{agent_key}/responses/{task_id}: get: tags: - Agents summary: Get response description: >- Retrieves the current state of an agent response by task ID. Returns the response output, model information, token usage, and execution status. When the agent is still processing, the output array will be empty and status will be `in_progress`. Once completed, the response includes the full output, usage statistics, and finish reason. operationId: GetAgentResponse parameters: - schema: type: string description: The unique key identifier of the agent required: true description: The unique key identifier of the agent name: agent_key in: path - schema: type: string description: The agent execution task ID returned from create response required: true description: The agent execution task ID returned from create response name: task_id in: path responses: '200': description: >- Response retrieved successfully. Returns the current state of the agent execution including output messages, model used, token usage, and status. content: application/json: schema: $ref: '#/components/schemas/GetAgentResponse' '404': description: >- Response not found. The specified task ID does not exist for this agent or workspace. content: application/json: schema: $ref: '#/components/schemas/HonoApiError' components: schemas: GetAgentResponse: allOf: - $ref: '#/components/schemas/CreateAgentResponse' - type: object properties: status: type: string enum: - in_progress - completed - failed description: Current status of the agent response error: type: string description: Error message when status is failed required: - status title: Get Agent Response description: >- Response type from the get-response endpoint. Includes a status field indicating the current state of the agent execution. HonoApiError: type: object properties: code: type: string description: HTTP status code message: type: string description: Error message required: - message CreateAgentResponse: type: object properties: _id: type: string description: The unique response ID task_id: type: string description: The agent execution task ID output: type: array items: $ref: '#/components/schemas/AgentResponseMessage' description: Array of messages from the agent execution created_at: type: string description: ISO timestamp of response creation model: type: string description: Model used in provider/model format usage: type: - object - 'null' properties: completion_tokens: type: number description: Number of tokens in the generated completion. prompt_tokens: type: number description: Number of tokens in the prompt. total_tokens: type: number description: >- Total number of tokens used in the request (prompt + completion). prompt_tokens_details: type: - object - 'null' properties: cached_tokens: type: - integer - 'null' cache_creation_tokens: type: - integer - 'null' audio_tokens: type: - integer - 'null' description: The number of audio input tokens consumed by the request. completion_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: - number - 'null' accepted_prediction_tokens: type: - number - 'null' rejected_prediction_tokens: type: - number - 'null' audio_tokens: type: - integer - 'null' description: The number of audio output tokens produced by the response. description: Token usage from the agent execution finish_reason: type: string enum: - stop - length - tool_calls - content_filter - function_call - max_iterations - max_time description: The reason why the agent stopped generating pending_tool_calls: type: array items: type: object properties: id: type: string type: type: string enum: - function function: type: object properties: name: type: string arguments: type: string required: - id - type - function description: >- Tool calls awaiting user response (when finish_reason is function_call) telemetry: $ref: '#/components/schemas/Telemetry' required: - _id - task_id - output - created_at - model title: Create Agent Response description: Response type from the create-response endpoint. AgentResponseMessage: type: object properties: messageId: type: string role: type: string enum: - user - agent - tool - system parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' metadata: type: object additionalProperties: {} required: - messageId - role - parts title: Agent Response Message description: Response message from an agent execution. Telemetry: type: object properties: trace_id: type: string description: The root trace ID for the agent execution span_id: type: string description: The span ID of the agent execution within the trace required: - trace_id - span_id title: Telemetry description: Telemetry information for correlating the response with traces TextPart: type: object properties: kind: type: string enum: - text text: type: string required: - kind - text title: Text Part description: >- A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses. ErrorPart: type: object properties: kind: type: string enum: - error error: type: string code: type: number required: - kind - error title: Error Part description: >- An error content part containing error information. Used when an error occurs during agent execution. DataPart: type: object properties: kind: type: string enum: - data data: type: object additionalProperties: {} metadata: type: object additionalProperties: {} required: - kind - data title: Data Part description: >- A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools. FilePart: type: object properties: kind: type: string enum: - file file: anyOf: - type: object properties: bytes: type: string minLength: 1 description: base64 encoded content of the file mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - bytes title: Binary format description: >- Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format. - type: object properties: uri: type: string description: URL for the File content mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - uri title: File in URI format description: >- File in URI format. Check in the model's documentation for the supported mime types for the URI format metadata: type: object additionalProperties: {} required: - kind - file title: File Part description: >- A file content part that can contain either base64-encoded bytes or a URI reference. Used for images, documents, and other binary content in agent communications. ToolCallPart: type: object properties: kind: type: string enum: - tool_call tool_name: type: string tool_call_id: type: string minLength: 1 arguments: type: object additionalProperties: {} thought_signature: type: string metadata: type: object additionalProperties: {} required: - kind - tool_name - tool_call_id - arguments title: Tool Call Part description: >- A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution. ToolResultPart: type: object properties: kind: type: string enum: - tool_result tool_call_id: type: string minLength: 1 result: {} metadata: type: object additionalProperties: {} required: - kind - tool_call_id title: Tool Result Part description: >- The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````