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

# Read research status

> Poll a run after the create request has closed. In-progress statuses are queued, running, and synthesizing. Terminal statuses are completed, partial, and failed.



## OpenAPI

````yaml https://seneca-research.fly.dev/v1/openapi.json get /v1/research/{run_id}
openapi: 3.1.0
info:
  title: Seneca Research API
  version: 0.1.0
  description: >-
    Create a research run, poll it, then read the customer report. Original
    model text is a separate read: list /v1/research/{run_id}/responses, read
    one model at /v1/research/{run_id}/responses/text, or download the panel as
    JSONL from /v1/research/{run_id}/responses/export. Send Authorization:
    Bearer seneca_sk_… Narrative quickstart:
    https://seneca.professionalaiagents.com/api.md
servers:
  - url: https://seneca-research.fly.dev
    description: Production
security: []
paths:
  /v1/research/{run_id}:
    get:
      tags:
        - public-api
      summary: Read research status
      description: >-
        Poll a run after the create request has closed. In-progress statuses are
        queued, running, and synthesizing. Terminal statuses are completed,
        partial, and failed.
      operationId: get_research_v1_research__run_id__get
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Run Id
      responses:
        '200':
          description: >-
            Current run, including credits_reserved, credits_charged, and
            progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicRunOut'
        '400':
          description: invalid_request when the run id cannot be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
        '401':
          description: >-
            authentication_required when the bearer token is missing or not a
            bearer token. invalid_api_key when the key is unknown, revoked, or
            expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
        '404':
          description: run_not_found. Another workspace's run is also run_not_found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
        '429':
          description: >-
            rate_limit_exceeded. Reads are limited to 120 requests per minute
            per key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
        '500':
          description: internal_error. The body does not include a traceback or a secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
      security:
        - SenecaApiKey: []
components:
  schemas:
    PublicRunOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        object:
          type: string
          const: research.run
          title: Object
          default: research.run
        status:
          type: string
          title: Status
          description: queued, running, synthesizing, completed, partial, or failed.
        phase:
          anyOf:
            - type: string
            - type: 'null'
          title: Phase
          description: >-
            panel while models are still answering. Null while synthesizing or
            after the run finishes.
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        panel:
          anyOf:
            - type: string
            - type: 'null'
          title: Panel
          description: >-
            Canonical panel id: wide, consensus, or seneca. A stored Quick Pulse
            run still reports quick_pulse.
        prompt:
          type: string
          title: Prompt
        credits_reserved:
          type: integer
          title: Credits Reserved
          description: >-
            Credits reserved when the run was accepted. This is the panel price
            and does not change if the run is later refunded.
        credits_charged:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Charged
          description: >-
            Null while the run is in progress. Equal to credits_reserved when a
            customer report is delivered, including a partial run that has a
            report. 0 after a verified technical failure with no customer
            report; that refund restores the reserve. failure_code does not
            change between a charged failure and a refunded one.
        failure_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Code
          description: research_failed when status is failed. Null otherwise.
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
        progress:
          $ref: '#/components/schemas/PublicProgressOut'
      additionalProperties: false
      type: object
      required:
        - id
        - status
        - prompt
        - credits_reserved
        - created_at
        - progress
      title: PublicRunOut
    PublicErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/PublicErrorObject'
      additionalProperties: false
      type: object
      required:
        - error
      title: PublicErrorResponse
      description: Error envelope returned by every /v1 failure. Documentation model only.
    PublicProgressOut:
      properties:
        total_models:
          type: integer
          title: Total Models
        completed_models:
          type: integer
          title: Completed Models
        successful_models:
          type: integer
          title: Successful Models
        failed_models:
          type: integer
          title: Failed Models
      additionalProperties: false
      type: object
      required:
        - total_models
        - completed_models
        - successful_models
        - failed_models
      title: PublicProgressOut
    PublicErrorObject:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        details:
          additionalProperties: true
          type: object
          title: Details
      additionalProperties: false
      type: object
      required:
        - code
        - message
      title: PublicErrorObject
  securitySchemes:
    SenecaApiKey:
      type: http
      description: >-
        Workspace API key created while signed in on the Developers page. Send
        Authorization: Bearer seneca_sk_… A Clerk session token is not accepted.
      scheme: bearer

````

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