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

# Create Run

> Start a run. Without `companies`: events from the question (Fast, Standard or Max). With `companies`:
each company's news (`kind: companies`). It runs in the background; follow it with `GET /runs/{run_id}/progress`.



## OpenAPI

````yaml /api-reference/agent/openapi.json post /runs
openapi: 3.1.0
info:
  title: NewsCatcher Agent API
  description: >-
    Agent runs (events from a query, or news about companies), company lists and
    monitors. Authenticate with your API key in the x-api-key header.
  version: 1.0.0
servers:
  - url: https://api.newscatcherapi.com/agent
    description: Production server
security: []
paths:
  /runs:
    post:
      tags:
        - runs
      summary: Create Run
      description: >-
        Start a run. Without `companies`: events from the question (Fast,
        Standard or Max). With `companies`:

        each company's news (`kind: companies`). It runs in the background;
        follow it with `GET /runs/{run_id}/progress`.
      operationId: create_run_runs_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRunResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Many Requests
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateRunRequest:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: >-
            What to find, e.g. 'Bank M&A deals announced in the US since Sep
            15'. Required without companies. With companies it is optional: only
            stories about it are kept, e.g. 'funding and acquisitions' (blank:
            every story about the companies).
        companies:
          anyOf:
            - $ref: '#/components/schemas/CompaniesIn'
            - type: 'null'
          description: Find news about these companies instead of events from the question.
        lookback_days:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lookback Days
          description: >-
            With companies: how many days back from today (1-365, default 30).
            Event runs read their time window from the query.
        include_market_activity:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Include Market Activity
          description: >-
            With companies: keep market_activity stories (stock moves, analyst
            ratings; default true).
        read_web:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Read Web
          description: >-
            With companies: also read their own newsroom and the web (default
            true).
        recheck_borderline:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Recheck Borderline
          description: >-
            With companies: a stronger model rechecks borderline web pages for
            little-covered companies (default true).
        mode:
          type: string
          enum:
            - fast
            - standard
            - max
          title: Mode
          description: >-
            fast: one agent, about 1-3 minutes. standard: deep research (planned
            slices, every web page read, each row verified, a cited briefing),
            about 10-30 minutes. max: deep research with stronger models, higher
            recall and cost. With companies: standard only (the default there).
            "default", Standard's name before 0.10.0, is still accepted.
          default: fast
        max_rows:
          anyOf:
            - type: integer
              enum:
                - 50
                - 100
                - 150
                - 200
            - type: 'null'
          title: Max Rows
          description: >-
            Without companies: rows to return at most, in every mode: 50
            (default), 100, 150 or 200, up to your plan's cap (100 today; more
            is refused with too_many_rows). A run is charged per 50 rows
            delivered past the first 50.
        keep_updated:
          anyOf:
            - $ref: '#/components/schemas/KeepUpdatedIn'
            - type: 'null'
          description: >-
            Keep it updated: once the run succeeds, the agent makes a monitor of
            it (a companies run -> a company monitor, following its company list
            if any; an events run -> a dataset monitor). The run is the
            monitor's first run; the monitor then delivers only what is new. Its
            state is the run's keep_updated.
      type: object
      title: CreateRunRequest
      description: >-
        POST /runs: one entry point. Without `companies` it finds events from
        the query (Fast, Standard or

        Max); with `companies` it finds each company's news stories (Standard;
        the query, if any, keeps the stories

        about it).
    CreateRunResponse:
      properties:
        run_id:
          type: string
          format: uuid
          title: Run Id
        status:
          type: string
          title: Status
        kind:
          type: string
          title: Kind
          default: events
        run_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Run Ids
        batch_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Batch Id
        list_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: List Id
        keep_updated:
          anyOf:
            - $ref: '#/components/schemas/KeepUpdatedOut'
            - type: 'null'
      type: object
      required:
        - run_id
        - status
      title: CreateRunResponse
      description: A queued run.
    ErrorResponse:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ErrorResponse
      description: 'Every error: a stable code and a message to show the user.'
    CompaniesIn:
      properties:
        list_id:
          anyOf:
            - type: string
            - type: 'null'
          title: List Id
          description: >-
            A company list's id (a UUID; POST /companies/lists). Companies not
            resolved yet are waited for; a list bigger than one run allows
            starts several runs (one batch).
        items:
          items:
            $ref: '#/components/schemas/CompanyIn'
          type: array
          title: Items
          description: Companies by domain, instead of list_id.
        save_as_list:
          type: boolean
          title: Save As List
          description: Also save the typed items as a company list (returned as list_id).
          default: false
        list_name:
          anyOf:
            - type: string
            - type: 'null'
          title: List Name
          description: 'The saved list''s name (default: the run''s name).'
      type: object
      title: CompaniesIn
      description: >-
        The companies a run finds news about: a company list, or companies typed
        in.
    KeepUpdatedIn:
      properties:
        schedule:
          anyOf:
            - $ref: '#/components/schemas/ScheduleIn'
            - type: 'null'
          description: >-
            When the monitor delivers (default: daily at 09:00 UTC; Standard/Max
            events runs: weekly on today's weekday).
        name:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Name
          description: 'The monitor''s name (default: the run''s name).'
      type: object
      title: KeepUpdatedIn
      description: >-
        Keep the run's results updated: once the run succeeds, the agent makes a
        monitor of it.
    KeepUpdatedOut:
      properties:
        status:
          type: string
          enum:
            - pending
            - created
            - failed
            - not_created
          title: Status
        monitor_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Monitor Id
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        schedule:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Schedule
      type: object
      required:
        - status
      title: KeepUpdatedOut
      description: 'A run started with keep_updated: its monitor, once made.'
    CompanyIn:
      properties:
        domain:
          type: string
          title: Domain
          description: The company's website, e.g. stripe.com (a URL works too).
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Optional name; a mismatch with the pinned profile rebuilds it.
      type: object
      required:
        - domain
      title: CompanyIn
      description: A company to follow.
    ScheduleIn:
      properties:
        every:
          type: string
          enum:
            - day
            - week
            - hours
          title: Every
          default: day
        at:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          title: At
          description: Local time, HH:MM (24-hour).
          default: '09:00'
        tz:
          type: string
          title: Tz
          description: IANA timezone, e.g. Europe/Berlin.
          default: UTC
        weekday:
          anyOf:
            - type: integer
              maximum: 6
              minimum: 0
            - type: 'null'
          title: Weekday
          description: 'Weekly only: 0 = Monday ... 6 = Sunday.'
        hours:
          anyOf:
            - type: integer
              maximum: 23
              minimum: 1
            - type: 'null'
          title: Hours
          description: >-
            every: hours only: hours between runs, counted from `at` each day.
            Refused with invalid_schedule below your plan's minimum interval (24
            hours on Free and PAYG).
      type: object
      title: ScheduleIn
      description: >-
        When the monitor runs: daily (default) or weekly at a local time in a
        timezone, or every few hours from that

        time when your plan allows runs more often than daily.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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