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

> ## Agent Instructions
> Follow the content contract in AGENTS.md.
> Treat text as the canonical explanation; video and screenshots enhance it.
> Do not publish unverified product behavior or duplicate an existing canonical article.

# List run events (poll with the cursor parameter, or stream them as SSE)

> Poll with ?after= for JSON pages, or send Accept: text/event-stream to receive the same events as Server-Sent Events: each `id:` is the event id, and the stream closes after the terminal event. Resume a stream with the Last-Event-ID header or ?after=.



## OpenAPI

````yaml /developers/openapi/stefanbrain-v1.json get /api/developers/v1/runs/{runId}/events
openapi: 3.1.0
info:
  title: StefanBrain Developer API
  version: 1.0.0
  description: >-
    REST access to StefanBrain agent runs, tools, and jobs. Authenticate with an
    API key from Settings → Developers. REST usage bills your prepaid API wallet
    at the published per-token rates (see
    https://docs.stefanbrain.com/developers/pricing); the MCP endpoint
    (/api/developers/v1/mcp, not described here) is member pricing from your
    plan pool. Human documentation: https://docs.stefanbrain.com/developers
servers:
  - url: https://stefanbrain.com
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: tools
    description: Directly invocable StefanBrain tools.
  - name: jobs
    description: Long-running tool jobs (poll for results).
  - name: runs
    description: Agentic chat runs with event streams.
  - name: files
    description: Workspace files agent runs produced in a chat.
  - name: media
    description: 'Stored Meta ad media facts: video transcripts on demand.'
  - name: feedback
    description: >-
      Tell StefanBrain where the API got in your way, and read the team's
      replies.
paths:
  /api/developers/v1/runs/{runId}/events:
    get:
      tags:
        - runs
      summary: List run events (poll with the cursor parameter, or stream them as SSE)
      description: >-
        Poll with ?after= for JSON pages, or send Accept: text/event-stream to
        receive the same events as Server-Sent Events: each `id:` is the event
        id, and the stream closes after the terminal event. Resume a stream with
        the Last-Event-ID header or ?after=.
      operationId: listRunEvents
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
        - name: after
          in: query
          required: false
          description: >-
            Return events after this event id (the previous page's next_after).
            Last-Event-ID wins when both are sent.
          schema:
            type: integer
            minimum: 0
        - name: Last-Event-ID
          in: header
          required: false
          description: 'SSE resume: return events after this event id.'
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: Ordered run events since the cursor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunEventList'
            text/event-stream:
              schema:
                type: string
                description: >-
                  SSE frames (sent when the request carries Accept:
                  text/event-stream): `id: <event id>` and `data: <event JSON>`.
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Suspended key, missing plan access, or key scoped away from this
            surface (code api_key_scope_forbidden).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Rate limited (codes request_per_minute, request_per_minute_user,
            request_per_day, user_throttled, user_suspended; Retry-After header
            when the limit has a reset time, plus limits, observed counts, and
            reset_at in the body), the runtime has no capacity to start a turn
            right now (code runtime_capacity_busy, Retry-After: 5), wallet
            exhausted (code api_wallet_exhausted), key budget exhausted (code
            api_key_budget_exhausted), or the plan's monthly usage pool spent
            for OAuth-token traffic (code monthly_usage_limit_reached).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RunEventList:
      type: object
      properties:
        object:
          type: string
        run_id:
          type: string
        events:
          type: array
          items:
            type: object
            additionalProperties: true
        next_after:
          type:
            - integer
            - 'null'
          description: Cursor for the next poll; pass as ?after=.
        is_done:
          type: boolean
      additionalProperties: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - api_error
                - service_unavailable_error
            code:
              type: string
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization: Bearer stefan_sk_... (API key — bills the API wallet) or
        stefan_oat_... (OAuth member token — bills your plan pool).
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````

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