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

# List thread events



## OpenAPI

````yaml /openapi/platform.v1.json get /v1/threads/{threadId}/events
openapi: 3.0.3
info:
  description: Public platform API for catalog and proxied data-plane routes.
  title: Matrices Platform API
  version: v1
servers:
  - url: https://api.matrices.com
security: []
tags:
  - description: Authenticated bearer credential context.
    name: auth
    x-group: Auth
  - description: Write-only provider credentials with safe connection metadata.
    name: connections
    x-group: Connections
  - description: Materialized workspace principals and active agent counts.
    name: identities
    x-group: Identities
  - description: Remote MCP server registrations.
    name: toolsets
    x-group: Toolsets
  - description: Named allow-only agent tool permissions.
    name: roles
    x-group: Roles
  - description: Client-executed tool calls.
    name: tools
    x-group: Tools
  - description: Reusable agent behavior profiles.
    name: profiles
    x-group: Profiles
  - description: Workspace-owned agent identities.
    name: agents
    x-group: Agents
  - description: Immutable private image inputs.
    name: images
    x-group: Images
  - description: Public model catalog.
    name: models
    x-group: Models
  - description: Running agent threads.
    name: threads
    x-group: Threads
  - description: Agent schedules.
    name: schedules
    x-group: Schedules
  - description: Workspace append-only feeds.
    name: feeds
    x-group: Feeds
  - description: Agent subscriptions over workspace feeds.
    name: subscriptions
    x-group: Subscriptions
  - description: Agent-private and workspace-shared durable memory notes.
    name: memory
    x-group: Memory
  - description: Thread messages.
    name: messages
    x-group: Messages
  - description: Thread event log data.
    name: events
    x-group: Events
  - description: Runtime hook audit and wait resolution.
    name: hooks
    x-group: Hooks
paths:
  /v1/threads/{threadId}/events:
    get:
      tags:
        - events
      summary: List thread events
      operationId: ListThreadEvents
      parameters:
        - $ref: '#/components/parameters/ThreadID'
        - $ref: '#/components/parameters/EventTurnID'
        - $ref: '#/components/parameters/EventAfterSeq'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Order'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPage'
          description: Thread event page.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/RuntimeUnavailable'
      security:
        - APIKeyBearer: []
components:
  parameters:
    ThreadID:
      in: path
      name: threadId
      required: true
      schema:
        type: string
    EventTurnID:
      description: Restrict events to one durable turn.
      in: query
      name: turnId
      required: false
      schema:
        minLength: 1
        type: string
    EventAfterSeq:
      description: >-
        Return only events with `seq` strictly greater than this value. `0` is
        equivalent to omitting the parameter. Requires ascending order and is
        mutually exclusive with `cursor`; combining it with either `cursor` or
        `order=desc` is rejected with 400.
      in: query
      name: afterSeq
      required: false
      schema:
        format: int64
        minimum: 0
        type: integer
    Limit:
      in: query
      name: limit
      required: false
      schema:
        maximum: 200
        minimum: 1
        type: integer
    Cursor:
      in: query
      name: cursor
      required: false
      schema:
        type: string
    Order:
      in: query
      name: order
      required: false
      schema:
        enum:
          - asc
          - desc
        type: string
  schemas:
    EventPage:
      properties:
        events:
          items:
            $ref: '#/components/schemas/ThreadEvent'
          type: array
        nextCursor:
          type: string
      required:
        - events
      type: object
    ThreadEvent:
      oneOf:
        - properties:
            failureCode:
              enum:
                - model_image_format_unsupported
              type: string
          required:
            - failureCode
            - failureDetails
        - not:
            required:
              - failureDetails
          properties:
            failureCode:
              not:
                enum:
                  - model_image_format_unsupported
              type: string
      properties:
        compaction:
          $ref: '#/components/schemas/CompactionEvent'
        content:
          $ref: '#/components/schemas/MessageContent'
        eventId:
          type: string
        failureCode:
          type: string
        failureDetails:
          $ref: '#/components/schemas/ModelImageFormatUnsupportedDetails'
        failureText:
          type: string
        hook:
          $ref: '#/components/schemas/HookDecisionEvent'
        inReplyToSeq:
          format: int64
          type: integer
        modelId:
          description: >-
            Runtime-selected model that produced an assistant, tool-intent, or
            compaction event.
          type: string
        occurredAt:
          format: date-time
          type: string
        principal:
          $ref: '#/components/schemas/Principal'
        providerToolCallId:
          type: string
        reveal:
          $ref: '#/components/schemas/ToolReveal'
        seq:
          format: int64
          type: integer
        submitMode:
          $ref: '#/components/schemas/SubmitMode'
        threadId:
          type: string
        timing:
          $ref: '#/components/schemas/Timing'
        toolCallId:
          type: string
        toolInput:
          $ref: '#/components/schemas/JSONValue'
        toolName:
          type: string
        toolOutput:
          $ref: '#/components/schemas/JSONValue'
        toolsetId:
          type: string
        turnId:
          type: string
        type:
          $ref: '#/components/schemas/ThreadEventType'
        usage:
          $ref: '#/components/schemas/ModelUsage'
        waitId:
          type: string
        waitResult:
          $ref: '#/components/schemas/JSONValue'
      required:
        - seq
        - eventId
        - threadId
        - turnId
        - type
        - occurredAt
      type: object
    ErrorResponse:
      properties:
        attemptsRemaining:
          type: integer
        code:
          type: string
        error:
          type: string
        message:
          type: string
        retryAfterSeconds:
          type: integer
      required:
        - error
        - message
      type: object
    CompactionEvent:
      properties:
        attempt:
          description: Round within one sample, for example build:0 or overflow.
          type: string
        preview:
          description: Bounded plain-text preview set only on a successful compacted event.
          type: string
        throughSeq:
          description: >-
            Boundary targeted by this round; every event at or below it is
            summarized.
          format: int64
          type: integer
      required:
        - throughSeq
        - attempt
      type: object
    MessageContent:
      description: >-
        Ordered message content, bounded to 512 KiB of encoded JSON. At most 20
        image blocks are permitted and image IDs must be unique within the
        message.
      items:
        $ref: '#/components/schemas/MessageContentBlock'
      maxItems: 40
      minItems: 1
      type: array
    ModelImageFormatUnsupportedDetails:
      additionalProperties: false
      description: >-
        Sorted unique image formats rejected by the exact model target. The
        encoded object is bounded to 4 KiB.
      properties:
        formats:
          items:
            $ref: '#/components/schemas/ImageFormat'
          maxItems: 4
          minItems: 1
          type: array
          uniqueItems: true
        targetId:
          minLength: 1
          pattern: \S
          type: string
      required:
        - targetId
        - formats
      type: object
    HookDecisionEvent:
      properties:
        decision:
          $ref: '#/components/schemas/HookDecision'
        deliveryId:
          type: string
        hookId:
          type: string
        index:
          type: integer
        latencyMs:
          format: int64
          type: integer
        point:
          $ref: '#/components/schemas/HookPoint'
        processor:
          $ref: '#/components/schemas/HookProcessorType'
        reason:
          type: string
        rewrote:
          type: boolean
      required:
        - hookId
        - index
        - point
        - processor
        - decision
        - latencyMs
      type: object
    Principal:
      properties:
        id:
          type: string
        identity:
          $ref: '#/components/schemas/Identity'
        origin:
          $ref: '#/components/schemas/Origin'
        type:
          enum:
            - user
            - api_key
            - agent
            - schedule
            - trigger
            - subscription
          type: string
      required:
        - type
        - id
      type: object
    ToolReveal:
      properties:
        families:
          items:
            enum:
              - agents
              - connections
              - thread
              - memory
              - artifacts
              - sites
              - web
              - schedules
              - feeds
              - subscriptions
              - sandbox
            type: string
          maxItems: 16
          type: array
        tools:
          items:
            $ref: '#/components/schemas/RevealedTool'
          maxItems: 10
          type: array
      type: object
    SubmitMode:
      enum:
        - queue
        - steer
        - interrupt
      type: string
    Timing:
      properties:
        durationMs:
          format: int64
          minimum: 0
          type: integer
        firstTextMs:
          format: int64
          minimum: 0
          type: integer
      required:
        - durationMs
      type: object
    JSONValue:
      description: Arbitrary JSON value.
    ThreadEventType:
      enum:
        - user_message
        - assistant_message
        - tool_intent
        - tool_result
        - wait_created
        - wait_resolved
        - hook_decision
        - turn_completed
        - turn_cancelled
        - turn_failed
        - compacting
        - compacted
      type: string
    ModelUsage:
      properties:
        cacheReadTokens:
          type: integer
        cacheWriteTokens:
          type: integer
        estimatedCost:
          format: double
          type: number
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        reasoningTokens:
          type: integer
        totalTokens:
          type: integer
      required:
        - inputTokens
        - outputTokens
        - totalTokens
      type: object
    MessageContentBlock:
      discriminator:
        mapping:
          image: '#/components/schemas/MessageImageContentBlock'
          text: '#/components/schemas/MessageTextContentBlock'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/MessageTextContentBlock'
        - $ref: '#/components/schemas/MessageImageContentBlock'
    ImageFormat:
      description: Caller-declared encoded image format.
      enum:
        - jpeg
        - png
        - gif
        - webp
      type: string
    HookDecision:
      enum:
        - allow
        - deny
        - ask
        - defer
      type: string
    HookPoint:
      enum:
        - before_turn_start
        - before_tool_call
        - after_tool_result
        - after_model_response
      type: string
    HookProcessorType:
      enum:
        - url
        - agent
        - client
      type: string
    Identity:
      description: >-
        Provenance identity. Surrounding whitespace is trimmed on input; values
        may contain at most 512 UTF-8 bytes and no Unicode control characters.
      type: string
    Origin:
      additionalProperties: false
      description: >-
        Caller-asserted external event metadata. Only trigger principals may
        assert it; every other principal is rejected.
      properties:
        channelId:
          description: Provider channel identifier, limited to 512 UTF-8 bytes.
          type: string
        messageId:
          description: Provider message identifier, limited to 512 UTF-8 bytes.
          type: string
        provider:
          $ref: '#/components/schemas/OriginProvider'
        senderId:
          description: Provider sender identifier, limited to 512 UTF-8 bytes.
          type: string
        tenantId:
          description: Provider tenant identifier, limited to 512 UTF-8 bytes.
          type: string
        threadId:
          description: Provider thread identifier, limited to 512 UTF-8 bytes.
          type: string
      required:
        - provider
        - tenantId
        - senderId
      type: object
    RevealedTool:
      properties:
        def:
          $ref: '#/components/schemas/RevealedModelTool'
        name:
          type: string
        namespace:
          type: string
        toolsetId:
          type: string
      required:
        - toolsetId
        - namespace
        - name
      type: object
    MessageImageContentBlock:
      additionalProperties: false
      properties:
        imageId:
          $ref: '#/components/schemas/ImageID'
        type:
          enum:
            - image
          type: string
      required:
        - type
        - imageId
      type: object
    MessageTextContentBlock:
      additionalProperties: false
      properties:
        text:
          description: >-
            Non-blank UTF-8 text. User messages permit at most 8 KiB total text;
            assistant messages permit 64 KiB.
          minLength: 1
          pattern: \S
          type: string
        type:
          enum:
            - text
          type: string
      required:
        - type
        - text
      type: object
    OriginProvider:
      description: >-
        Caller-asserted external event provider. This value carries no
        authority.
      enum:
        - slack
      type: string
    RevealedModelTool:
      properties:
        description:
          type: string
        name:
          type: string
        schema:
          $ref: '#/components/schemas/JSONValue'
      required:
        - name
        - schema
      type: object
    ImageID:
      description: Opaque identifier for one immutable private image.
      maxLength: 68
      minLength: 68
      pattern: ^img_[0-9a-f]{64}$
      type: string
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Invalid request.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Resource not found.
    RuntimeUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Runtime environment is unavailable or cannot be selected.
  securitySchemes:
    APIKeyBearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.