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

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to development documentation. Use it only with the matching development source. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# List runs

> Return the caller's runs, newest first.

Args:
    sop_id (`str | None`):
        Narrow to one procedure.
    phase (`SOPPhase | None`):
        Narrow to one phase.
    user_id (`str`):
        Injected authenticated user id.
    storage (`StorageBase`):
        Injected storage backend.

Returns:
    `ListSOPRunsResponse`:
        The matching runs.



## OpenAPI

````yaml /en/versions/2.0.9/deploy/openapi.json get /sop/runs
openapi: 3.1.0
info:
  title: AgentScope
  version: 2.0.9
servers: []
security: []
paths:
  /sop/runs:
    get:
      tags:
        - sop
      summary: List runs
      description: |-
        Return the caller's runs, newest first.

        Args:
            sop_id (`str | None`):
                Narrow to one procedure.
            phase (`SOPPhase | None`):
                Narrow to one phase.
            user_id (`str`):
                Injected authenticated user id.
            storage (`StorageBase`):
                Injected storage backend.

        Returns:
            `ListSOPRunsResponse`:
                The matching runs.
      operationId: list_sop_runs_sop_runs_get
      parameters:
        - name: sop_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Only runs of this procedure.
            title: Sop Id
          description: Only runs of this procedure.
        - name: phase
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/SOPPhase'
              - type: 'null'
            description: >-
              Only runs standing here — ``awaiting`` is the one worth asking
              for.
            title: Phase
          description: Only runs standing here — ``awaiting`` is the one worth asking for.
        - name: x-user-id
          in: header
          required: true
          schema:
            type: string
            description: >-
              Caller's user ID. Temporary header-based identity; will be
              replaced by JWT auth.
            title: X-User-Id
          description: >-
            Caller's user ID. Temporary header-based identity; will be replaced
            by JWT auth.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSOPRunsResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SOPPhase:
      type: string
      enum:
        - pending
        - running
        - awaiting
        - completed
        - failed
      title: SOPPhase
      description: |-
        Where a step, or a whole run, stands.

        One enum for both: a run is only ever as far along as its steps let
        it be.
    ListSOPRunsResponse:
      properties:
        runs:
          items:
            $ref: '#/components/schemas/SOPRunRecord'
          type: array
          title: Runs
          description: The runs, newest first.
        total:
          type: integer
          title: Total
          description: How many were returned.
      type: object
      required:
        - runs
        - total
      title: ListSOPRunsResponse
      description: Response body listing runs.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SOPRunRecord:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the credential.
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_at:
          type: string
          format: date-time
          title: Created At
        user_id:
          type: string
          title: User Id
        sop_id:
          type: string
          title: Sop Id
        definition:
          $ref: '#/components/schemas/SOPData'
        sessions:
          additionalProperties:
            type: string
          type: object
          title: Sessions
        state:
          $ref: '#/components/schemas/SOPRunState'
      type: object
      required:
        - user_id
        - sop_id
        - definition
      title: SOPRunRecord
      description: One run of a procedure.
    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
    SOPData:
      properties:
        name:
          type: string
          title: Name
          description: The name of the procedure.
        description:
          type: string
          title: Description
          description: What the procedure is for.
          default: ''
        steps:
          items:
            $ref: '#/components/schemas/SOPStepDataV1'
          type: array
          minItems: 1
          title: Steps
          description: Its milestones, in the order they must happen.
        workspace_grain:
          $ref: '#/components/schemas/SOPWorkspaceGrain'
          description: How many workspaces a run of this gets.
          default: run
        session_settings:
          additionalProperties:
            $ref: '#/components/schemas/SessionSettings'
          type: object
          title: Session Settings
          description: What each conversation is opened with, keyed by session key.
      type: object
      required:
        - name
        - steps
      title: SOPData
      description: 'A procedure: its milestones, in order.'
    SOPRunState:
      properties:
        id:
          type: string
          title: Id
        inputs:
          items:
            $ref: '#/components/schemas/Msg'
          type: array
          title: Inputs
        steps:
          items:
            $ref: '#/components/schemas/SOPStepRunState'
          type: array
          title: Steps
        created_at:
          type: string
          title: Created At
        phase:
          $ref: '#/components/schemas/SOPPhase'
          description: |-
            Where the run stands, worked out from its steps.

            Dumped alongside the stored fields so a reader can sort runs
            by it without replaying every step.

            Returns:
                `SOPPhase`:
                    How far along the run as a whole is.
          readOnly: true
      type: object
      required:
        - phase
      title: SOPRunState
      description: |-
        One execution of a SOP, and the whole of what is worth saving.

        It covers the SOP's own state and nothing below it: an executor that
        keeps state of its own (an :class:`~..agent.Agent` does) is persisted
        by whoever built it, the same way it is built.
    SOPStepDataV1:
      properties:
        version:
          type: string
          const: v1
          title: Version
          default: v1
        subject:
          type: string
          title: Subject
          description: A brief, actionable name.
        description:
          type: string
          title: Description
          description: What this step must achieve — the destination.
        executor:
          $ref: '#/components/schemas/SOPAgentRef'
          description: Who does the work.
        verifier:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/AgentVerifier'
                - $ref: '#/components/schemas/HumanVerifier'
              discriminator:
                propertyName: type
                mapping:
                  agent:
                    $ref: '#/components/schemas/AgentVerifier'
                  human:
                    $ref: '#/components/schemas/HumanVerifier'
            - type: 'null'
          title: Verifier
          description: Who judges it. ``None`` accepts whatever comes back.
        max_attempts:
          type: integer
          exclusiveMinimum: 0
          title: Max Attempts
          description: How many refusals before the run gives up on it.
          default: 3
      type: object
      required:
        - subject
        - description
        - executor
      title: SOPStepDataV1
      description: |-
        One milestone, as :class:`~agentscope.sop.SOPStep` runs it.
        An incompatible change becomes a new model discriminated on
        :attr:`version`.
    SOPWorkspaceGrain:
      type: string
      enum:
        - run
        - per_session_key
      title: SOPWorkspaceGrain
      description: |-
        How many workspaces a run gets. Always minted for the run, never
        shared with another run.
    SessionSettings:
      properties:
        chat_model_config:
          additionalProperties: true
          type: object
          title: Chat Model Config
        fallback_chat_model_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Fallback Chat Model Config
        permission_mode:
          type: string
          title: Permission Mode
          default: default
      type: object
      required:
        - chat_model_config
      title: SessionSettings
      description: Settings for a session a channel or SOP run opens for a user.
    Msg:
      properties:
        name:
          type: string
          title: Name
        content:
          items:
            anyOf:
              - $ref: '#/components/schemas/TextBlock'
              - $ref: '#/components/schemas/ThinkingBlock'
              - $ref: '#/components/schemas/HintBlock'
              - $ref: '#/components/schemas/ToolCallBlock'
              - $ref: '#/components/schemas/ToolResultBlock'
              - $ref: '#/components/schemas/DataBlock'
          type: array
          title: Content
        role:
          type: string
          enum:
            - user
            - assistant
            - system
          title: Role
        id:
          type: string
          title: Id
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          title: Created At
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
        finished_reason:
          anyOf:
            - $ref: '#/components/schemas/ReplyFinishedReason'
            - type: 'null'
        structured_output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Structured Output
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: 'null'
      type: object
      required:
        - name
        - content
        - role
      title: Msg
      description: |-
        The message class in AgentScope, responsible for information storage
        and transmission among different agents.
    SOPStepRunState:
      properties:
        phase:
          $ref: '#/components/schemas/SOPPhase'
          default: pending
        given:
          items:
            $ref: '#/components/schemas/Msg'
          type: array
          title: Given
        submission:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
            - type: 'null'
          title: Submission
        verifications:
          items:
            $ref: '#/components/schemas/VerificationResult'
          type: array
          title: Verifications
      additionalProperties: true
      type: object
      title: SOPStepRunState
      description: |-
        What one step did in one run.

        The engine writes :attr:`given`; the step keeps the other three
        honest. To remember more, subclass this and name the subclass in
        :attr:`~._schema.SOPStepBase.state_type` — extra fields survive a
        round trip through storage.
    SOPAgentRef:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: The agent that does the work.
        session_key:
          type: string
          title: Session Key
          description: >-
            Which conversation it does it in; references sharing a key share one
            session.
      type: object
      required:
        - agent_id
        - session_key
      title: SOPAgentRef
      description: Which agent does something, and in which conversation.
    AgentVerifier:
      properties:
        type:
          type: string
          const: agent
          title: Type
          default: agent
        agent:
          $ref: '#/components/schemas/SOPAgentRef'
          description: Who judges the work.
        criteria:
          type: string
          format: textarea
          title: Criteria
          description: What to hold the work to, beyond the step's own description.
          default: ''
      type: object
      required:
        - agent
      title: AgentVerifier
      description: A verifier that is itself an agent.
    HumanVerifier:
      properties:
        type:
          type: string
          const: human
          title: Type
          default: human
        question:
          type: string
          format: textarea
          title: Question
          description: What the person is asked.
          default: Does this meet what the step had to prove?
      type: object
      title: HumanVerifier
      description: A verifier that asks a person and waits for the answer.
    TextBlock:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        text:
          type: string
          title: Text
        id:
          type: string
          title: Id
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
      type: object
      required:
        - text
      title: TextBlock
      description: The text block.
    ThinkingBlock:
      properties:
        type:
          type: string
          const: thinking
          title: Type
          default: thinking
        thinking:
          type: string
          title: Thinking
        id:
          type: string
          title: Id
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
      additionalProperties: true
      type: object
      required:
        - thinking
      title: ThinkingBlock
      description: |-
        The thinking block.

        Allows extra provider-specific fields (e.g. Anthropic's ``signature``,
        ``redacted_thinking_data``) via ``extra="allow"`` so that model
        implementations can pass arbitrary metadata without subclassing.

        .. note::
            Anthropic's ``redacted_thinking`` blocks are also stored as
            ``ThinkingBlock`` instances with ``thinking=""`` and the
            encrypted payload in the ``redacted_thinking_data`` extra
            field. Callers filtering by ``type=="thinking"`` (e.g.
            ``get_content_blocks``) will receive both visible and
            redacted blocks.
    HintBlock:
      properties:
        type:
          type: string
          const: hint
          title: Type
          default: hint
        hint:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Hint
        id:
          type: string
          title: Id
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
      type: object
      required:
        - hint
      title: HintBlock
      description: |-
        A block used to provide instructions or hints to the LLM during the
        reasoning-acting loop. When passed to the LLM API, the hint block is
        converted into a user message.

        The ``hint`` field can be a plain string (text-only) or a list of
        :class:`TextBlock` / :class:`DataBlock` for multimodal content
        (e.g. a background tool result containing both text and an image).
    ToolCallBlock:
      properties:
        type:
          type: string
          const: tool_call
          title: Type
          default: tool_call
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        input:
          type: string
          title: Input
        state:
          $ref: '#/components/schemas/ToolCallState'
          default: pending
        suggested_rules:
          items:
            $ref: '#/components/schemas/PermissionRule'
          type: array
          title: Suggested Rules
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
      type: object
      required:
        - id
        - name
        - input
      title: ToolCallBlock
      description: The tool call block.
    ToolResultBlock:
      properties:
        type:
          type: string
          const: tool_result
          title: Type
          default: tool_result
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        output:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Output
        state:
          $ref: '#/components/schemas/ToolResultState'
          default: running
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
      type: object
      required:
        - id
        - name
        - output
      title: ToolResultBlock
      description: The tool result block.
    DataBlock:
      properties:
        type:
          type: string
          const: data
          title: Type
          default: data
        id:
          type: string
          title: Id
        source:
          anyOf:
            - $ref: '#/components/schemas/Base64Source'
            - $ref: '#/components/schemas/URLSource'
          title: Source
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
      type: object
      required:
        - source
      title: DataBlock
      description: The data block for binary content (images, audio, video, etc.).
    Usage:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        cache_input_tokens:
          type: integer
          title: Cache Input Tokens
          default: 0
        cache_creation_input_tokens:
          type: integer
          title: Cache Creation Input Tokens
          default: 0
      type: object
      required:
        - input_tokens
        - output_tokens
      title: Usage
      description: The token usage information of a message.
    ReplyFinishedReason:
      type: string
      enum:
        - completed
        - interrupted
        - exceed_max_iters
        - error
      title: ReplyFinishedReason
      description: The reason a reply finished.
    ErrorInfo:
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
          default: unknown
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ErrorInfo
      description: Structured, UI-facing description of a fatal reply error.
    VerificationResult:
      properties:
        passed:
          type: boolean
          title: Passed
        message:
          type: string
          title: Message
          default: ''
        verifier:
          type: string
          title: Verifier
          default: ''
        created_at:
          type: string
          title: Created At
      type: object
      required:
        - passed
      title: VerificationResult
      description: |-
        One settled verdict on one attempt.

        Only settled verdicts exist — a step with nothing to say yet records
        nothing, because a verdict that has not happened is not a verdict.
    ToolCallState:
      type: string
      enum:
        - pending
        - asking
        - allowed
        - submitted
        - finished
      title: ToolCallState
      description: The state of the tool call.
    PermissionRule:
      properties:
        tool_name:
          type: string
          title: Tool Name
        rule_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Rule Content
        behavior:
          $ref: '#/components/schemas/PermissionBehavior'
        source:
          type: string
          title: Source
      type: object
      required:
        - tool_name
        - rule_content
        - behavior
        - source
      title: PermissionRule
      description: >-
        Permission rule for tool usage.


        A permission rule defines whether a specific tool or tool operation

        should be allowed, denied, or require user confirmation. The

        rule_content field has different semantics depending on the tool_name:


        - For "Bash": rule_content is a substring pattern matched against the
          command Example: rule_content="npm install" matches "npm install express"

        - For "Write"/"Read": rule_content is a glob pattern matched against
        file
          paths Example: rule_content="src/**" matches "src/main.py"

        - For other tools: rule_content is a tool-specific filter pattern
    ToolResultState:
      type: string
      enum:
        - success
        - error
        - interrupted
        - denied
        - running
      title: ToolResultState
      description: The tool result state.
    Base64Source:
      properties:
        type:
          type: string
          const: base64
          title: Type
          default: base64
        data:
          type: string
          title: Data
        media_type:
          type: string
          title: Media Type
      type: object
      required:
        - data
        - media_type
      title: Base64Source
      description: The base64 source.
    URLSource:
      properties:
        type:
          type: string
          const: url
          title: Type
          default: url
        url:
          type: string
          minLength: 1
          format: uri
          title: Url
        media_type:
          type: string
          title: Media Type
      type: object
      required:
        - url
        - media_type
      title: URLSource
      description: The URL source.
    ErrorType:
      type: string
      enum:
        - authentication
        - permission
        - rate_limit
        - invalid_request
        - upstream
        - connection
        - internal
        - setup
        - unknown
      title: ErrorType
      description: |-
        Classification of a fatal error that terminated a reply.

        Not model-specific: the status-derived members apply to any upstream
        service reached during a reply (chat model, embedding, TTS, MCP).
    PermissionBehavior:
      type: string
      enum:
        - allow
        - deny
        - ask
        - passthrough
      title: PermissionBehavior
      description: |-
        The behavior of permission.

        Attributes:
            ALLOW: Allow the operation
            DENY: Deny the operation
            ASK: Ask the user for permission
            PASSTHROUGH: Let the permission engine continue with rule matching
                (used by tools to defer decision to the engine)

````