> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.writesonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query agent runs

> See the history of agent runs for a task or an agent, or follow the step-by-step progress of a single run.

**Example:** "Show the agent run history for the task 'Fix login bug'"

**Usage:** choose what you want with `scope` — the runs of a task (needs the task id), the runs of an agent (needs the agent id), or the live progress of one run (needs the task id and the run id). The run lists come back in pages of up to 100 (50 by default); pass the cursor from the previous page to get the next one.

**Response:** a list of runs, each showing its status, what triggered it, when it started and finished, and how many tokens it used. A progress request returns the run's steps in order.



## OpenAPI

````yaml https://mcp.agent.writesonic.com/openapi.json post /api/v1/business/agent-runs/query
openapi: 3.1.0
info:
  title: hq-backend — Business API
  description: Public business tool endpoints (API-key auth).
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/business/agent-runs/query:
    post:
      tags:
        - business
      summary: Query agent runs
      description: >-
        See the history of agent runs for a task or an agent, or follow the
        step-by-step progress of a single run.


        **Example:** "Show the agent run history for the task 'Fix login bug'"


        **Usage:** choose what you want with `scope` — the runs of a task (needs
        the task id), the runs of an agent (needs the agent id), or the live
        progress of one run (needs the task id and the run id). The run lists
        come back in pages of up to 100 (50 by default); pass the cursor from
        the previous page to get the next one.


        **Response:** a list of runs, each showing its status, what triggered
        it, when it started and finished, and how many tokens it used. A
        progress request returns the run's steps in order.
      operationId: get_agent_runs_api_v1_business_agent_runs_query_post
      parameters:
        - name: x-project-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
            description: Project ID for tenant scoping
            title: X-Project-Id
          description: Project ID for tenant scoping
        - name: X-Workspace-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            description: Overrides the key's workspace
            title: X-Workspace-Id
          description: Overrides the key's workspace
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: User API key
            title: X-Api-Key
          description: User API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunsArgs'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AgentRunListResponse'
                  - $ref: '#/components/schemas/AgentProgressJSONResponse'
                title: Response Get Agent Runs Api V1 Business Agent Runs Query Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentRunsArgs:
      properties:
        scope:
          $ref: '#/components/schemas/AgentRunScope'
          description: 'Which run view: task_runs, agent_runs, or run_progress'
        task_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Task Id
          description: Task id; required for task_runs and run_progress
        agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Agent Id
          description: Agent id; required for agent_runs
        run_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Run Id
          description: Run id; required for run_progress
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
          description: Pagination cursor for the run list scopes
        limit:
          type: integer
          maximum: 100
          minimum: 1
          title: Limit
          description: Page size for the run list scopes
          default: 50
      type: object
      required:
        - scope
      title: AgentRunsArgs
    AgentRunListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AgentRunResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      required:
        - items
      title: AgentRunListResponse
    AgentProgressJSONResponse:
      properties:
        run_id:
          type: string
          title: Run Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        failure_reason:
          anyOf:
            - $ref: '#/components/schemas/AgentFailureReason'
            - type: 'null'
        log_pointer:
          anyOf:
            - type: string
            - type: 'null'
          title: Log Pointer
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Ended At
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        steps:
          items:
            $ref: '#/components/schemas/AgentProgressStep'
          type: array
          title: Steps
      type: object
      required:
        - run_id
        - status
        - steps
      title: AgentProgressJSONResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentRunScope:
      type: string
      enum:
        - task_runs
        - agent_runs
        - run_progress
      title: AgentRunScope
    AgentRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        task_id:
          type: string
          format: uuid
          title: Task Id
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        trigger:
          $ref: '#/components/schemas/AgentRunTrigger'
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        failure_reason:
          anyOf:
            - $ref: '#/components/schemas/AgentFailureReason'
            - type: 'null'
        log_pointer:
          anyOf:
            - type: string
            - type: 'null'
          title: Log Pointer
        last_comment_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Last Comment Id
        cancelled_by_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Cancelled By User Id
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - task_id
        - agent_id
        - status
        - trigger
        - started_at
        - ended_at
        - error_message
        - failure_reason
        - log_pointer
        - last_comment_id
        - cancelled_by_user_id
        - input_tokens
        - output_tokens
        - created_at
        - updated_at
      title: AgentRunResponse
    AgentRunStatus:
      type: string
      enum:
        - pending
        - running
        - awaiting_approval
        - awaiting_workflow
        - awaiting_knowledge_sync
        - succeeded
        - failed
        - cancelled
        - skipped
      title: AgentRunStatus
    AgentFailureReason:
      type: string
      enum:
        - iteration_limit
        - timeout
        - tool_error
        - llm_error
        - unknown
        - dispatch_lost
      title: AgentFailureReason
    AgentProgressStep:
      properties:
        kind:
          type: string
          enum:
            - assistant_message
            - tool_call
            - tool_result
          title: Kind
        ts:
          anyOf:
            - type: string
            - type: 'null'
          title: Ts
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
        tool_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Name
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
        args:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Args
        status:
          anyOf:
            - type: string
              enum:
                - ok
                - error
            - type: 'null'
          title: Status
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
      type: object
      required:
        - kind
      title: AgentProgressStep
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentRunTrigger:
      type: string
      enum:
        - task_assigned
        - human_reply
        - scheduled
        - mention
        - status_transition
        - batch_completed
      title: AgentRunTrigger

````