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

# Run Tournament Sim

> Simulate a tournament over this division's recorded pairwise results.



## OpenAPI

````yaml https://softmax.com/api/observatory/openapi.json post /v2/divisions/{division_id}/tournament-sim
openapi: 3.1.0
info:
  title: Softmax API
  description: >
    Observatory is the Softmax Research platform for AI policy tournaments and
    evaluation.

    Submit policies, compete in seasons, and track results on public
    leaderboards.


    ---


    ## Authentication


    Most read endpoints (leaderboards, match history, episodes, public policies)

    work without auth. Submitting policies or accessing your own data requires

    a Bearer token:


    ```

    Authorization: Bearer <your-token>

    ```


    To get a token, install [cogames](https://pypi.org/project/cogames/) and
    run:


    ```bash

    cogames auth login

    ```


    A `401` response means no token was provided. A `403` means the token

    is invalid or expired.


    ### Verify your token


    ```bash

    curl -H "Authorization: Bearer <your-token>" \
      https://softmax.com/api/observatory/whoami
    ```


    Returns `{"user_email": "you@example.com"}` on success.
  version: 1.0.0
servers:
  - url: https://softmax.com/api/observatory
security: []
paths:
  /v2/divisions/{division_id}/tournament-sim:
    post:
      tags:
        - v2
        - v2
      summary: Run Tournament Sim
      description: Simulate a tournament over this division's recorded pairwise results.
      operationId: run_tournament_sim_v2_divisions__division_id__tournament_sim_post
      parameters:
        - name: division_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^div_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            title: Division Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2TournamentSimRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2TournamentSimReport'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    V2TournamentSimRequest:
      properties:
        structure:
          type: string
          enum:
            - single_elim
            - double_elim
            - round_robin
            - elimination_rounds
            - evolutionary
          title: Structure
        rounds_window:
          type: integer
          maximum: 200
          minimum: 1
          title: Rounds Window
          description: How many recent completed rounds feed the matrix
          default: 20
        window_start:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Window Start
          description: >-
            Only rounds created at/after this time feed the matrix (overrides
            rounds_window; capped at the 200 most recent matching rounds —
            matrix.rounds_truncated reports when the cap dropped older ones)
        window_end:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Window End
          description: Only rounds created at/before this time
        coworld_version_min:
          anyOf:
            - type: string
            - type: 'null'
          title: Coworld Version Min
          description: >-
            Oldest coworld version whose episodes count; 'latest' (default) =
            newest in window; null = all
          default: latest
        coworld_version_max:
          anyOf:
            - type: string
            - type: 'null'
          title: Coworld Version Max
          description: >-
            Newest coworld version whose episodes count; 'latest' = newest in
            window
        n_sims:
          type: integer
          maximum: 2000
          minimum: 1
          title: N Sims
          default: 1000
        seed:
          type: integer
          title: Seed
          default: 0
        best_of:
          type: integer
          maximum: 15
          minimum: 1
          title: Best Of
          default: 1
        seeding:
          type: string
          enum:
            - record
            - random
          title: Seeding
          default: record
        mutual_rule:
          type: string
          enum:
            - coinflip
            - redraw
            - loss_both
          title: Mutual Rule
          default: loss_both
        smoothing:
          type: number
          maximum: 10
          minimum: 0
          title: Smoothing
          default: 1
        rr_passes:
          type: integer
          maximum: 20
          minimum: 1
          title: Rr Passes
          default: 1
        eliminate_per_round:
          type: integer
          maximum: 8
          minimum: 1
          title: Eliminate Per Round
          default: 1
        grand_final_reset:
          type: boolean
          title: Grand Final Reset
          default: true
        pop_size:
          type: integer
          maximum: 500
          minimum: 2
          title: Pop Size
          default: 100
        generations:
          type: integer
          maximum: 500
          minimum: 1
          title: Generations
          default: 200
        roster_mode:
          type: string
          enum:
            - window
            - champions
            - top_n
            - top_percent
          title: Roster Mode
          description: >-
            window = everyone seen in the rounds window; champions = current
            champion policy only (one per player); top_n / top_percent = best
            window records
          default: window
        roster_n:
          type: integer
          maximum: 32
          minimum: 2
          title: Roster N
          default: 8
        roster_percent:
          type: number
          maximum: 100
          exclusiveMinimum: 0
          title: Roster Percent
          default: 50
        roster_only:
          type: boolean
          title: Roster Only
          description: Return the roster + win model without simulating
          default: false
        sufficiency:
          type: boolean
          title: Sufficiency
          description: >-
            Posterior-resample the win model to judge whether the recorded 1v1
            data is sufficient
          default: true
        sufficiency_draws:
          type: integer
          maximum: 100
          minimum: 1
          title: Sufficiency Draws
          default: 24
        sufficiency_inner_sims:
          type: integer
          maximum: 500
          minimum: 10
          title: Sufficiency Inner Sims
          default: 150
        policy_version_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Policy Version Ids
          description: Explicit roster override; takes precedence over roster_mode
        exclude_policy_version_ids:
          items:
            type: string
          type: array
          title: Exclude Policy Version Ids
          description: Manually excluded policies, applied after roster_mode selection
        policy_cutoff:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Policy Cutoff
          description: >-
            Exclude policies submitted to the league after this time; champions
            become each player's last champion policy submitted at/before it
      additionalProperties: false
      type: object
      required:
        - structure
      title: V2TournamentSimRequest
    V2TournamentSimReport:
      properties:
        division_id:
          type: string
          title: Division Id
        league_id:
          type: string
          title: League Id
        matrix:
          additionalProperties: true
          type: object
          title: Matrix
        roster:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Roster
        note_prefix:
          type: string
          title: Note Prefix
          default: ''
        missing_data_pairs:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Missing Data Pairs
          default: []
        data_requests:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Data Requests
          default: []
        access:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Access
        coworld_versions:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Coworld Versions
          default: []
        win_model:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Win Model
        config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Config
        showcase:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Showcase
        monte_carlo:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Monte Carlo
        sufficiency:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Sufficiency
      type: object
      required:
        - division_id
        - league_id
        - matrix
        - roster
      title: V2TournamentSimReport
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token issued by Softmax

````