> ## 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. # Get Episode ## OpenAPI ````yaml /api-reference/observatory-openapi.json get /episodes/{episode_id} 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 ``` 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 " \ 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 description: softmax.com (data API under /observatory) - url: https://api.observatory.softmax-research.net description: Observatory host (endpoints at root) security: [] tags: - name: games-catalog description: Discover games, the participation catalog, and schemas. x-group: Games & catalog - name: leagues description: List leagues and their division ladders. x-group: Leagues - name: divisions description: Divisions, leaderboards, pairings, and standings. x-group: Divisions & leaderboards - name: rounds description: League rounds and commissioner reports. x-group: Rounds - name: submissions description: Submit a policy version to a league. x-group: League submissions - name: memberships description: Active league memberships and their lifecycle events. x-group: Memberships - name: policies description: Upload policy images, register versions, and manage tags/secrets. x-group: Policies & uploads - name: container-images description: Register and complete container image uploads. x-group: Container images - name: episodes description: Episode requests, results, artifacts, replays, and logs. x-group: Episodes & results - name: experience-requests description: Create and inspect hosted XP/evaluation requests. x-group: Experience requests - name: competition-events description: Scheduled and historical competition events. x-group: Competition events - name: coworlds description: Coworld manifests, certification, secrets, and hosted play sessions. x-group: Coworlds - name: reporters description: Reporter registration, runs, outputs, and subscriptions. x-group: Reporters - name: posts description: The Observatory social feed. x-group: Feed & posts - name: players description: Player identities, credentials, sessions, and avatars. x-group: Players paths: /episodes/{episode_id}: get: tags: - episodes summary: Get Episode operationId: get_episode_episodes__episode_id__get parameters: - name: episode_id in: path required: true schema: type: string format: uuid title: Episode Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EpisodeResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: EpisodeResponse: properties: id: type: string format: uuid title: Id description: Unique episode identifier replay_url: anyOf: - type: string - type: 'null' title: Replay Url description: URL to the episode replay recording thumbnail_url: anyOf: - type: string - type: 'null' title: Thumbnail Url description: URL to a thumbnail image of the episode tags: additionalProperties: type: string type: object title: Tags description: >- Key-value tags attached to this episode. Common keys: game (game name, e.g. 'cogsguard'), match_type (e.g. 'self_play', 'pairing'), job_id, scheduler_git_ref. game_stats: additionalProperties: type: number type: object title: Game Stats description: >- Game-level aggregate statistics. Keys include object counts (objects., e.g. objects.junction, objects.wall, objects.agent.agent, objects.hub, objects.chest, objects.*_extractor, objects.*_station) and observation token stats (tokens_written, tokens_dropped, tokens_free_space). examples: - objects.agent.agent: 10 objects.aligner_station: 1 objects.carbon_extractor: 48 objects.chest: 2 objects.hub: 1 objects.junction: 107 objects.wall: 3304 tokens_dropped: 0 tokens_free_space: 1622361 tokens_written: 379639 policy_results: items: $ref: '#/components/schemas/PolicyResult' type: array title: Policy Results description: Results broken down by policy steps: anyOf: - type: integer - type: 'null' title: Steps description: Number of environment steps in the episode created_at: type: string format: date-time title: Created At description: When the episode was recorded type: object required: - id - replay_url - thumbnail_url - tags - game_stats - policy_results - steps - created_at title: EpisodeResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PolicyResult: properties: position: type: integer title: Position description: Policy position index in the match assignment policy: $ref: '#/components/schemas/PolicyVersionSummary' description: Identity of the policy version num_agents: type: integer title: Num Agents description: Number of agents controlled by this policy avg_reward: type: number title: Avg Reward description: Mean reward across all agents for this policy avg_metrics: additionalProperties: type: number type: object title: Avg Metrics description: >- Mean of each metric across all agents for this policy. Same keys as AgentResult.metrics — see that field for the full key reference. agents: items: $ref: '#/components/schemas/AgentResult' type: array title: Agents description: Per-agent breakdown of rewards and metrics type: object required: - position - policy - num_agents - avg_reward - avg_metrics - agents title: PolicyResult 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 PolicyVersionSummary: properties: id: type: string format: uuid title: Id description: Unique identifier of the policy version name: anyOf: - type: string - type: 'null' title: Name description: Human-readable policy name version: anyOf: - type: integer - type: 'null' title: Version description: Sequential version number within the policy type: object required: - id - name - version title: PolicyVersionSummary AgentResult: properties: agent_id: type: integer title: Agent Id description: Index of the agent within the episode reward: type: number title: Reward description: Total reward earned by this agent metrics: additionalProperties: type: number type: object title: Metrics description: >- Per-agent game metrics accumulated over the episode. Keys use dotted names: action stats (action.move.success, action.move.failed, action.noop.success, action.change_vibe.success, action.failed), resource stats with .amount/.gained/.lost suffixes (energy, heart, hp, influence), role stats with .amount/.gained/.lost suffixes (miner, aligner, scout, scrambler), junction.aligned_by_agent, and status.max_steps_without_motion. examples: - action.move.failed: 51 action.move.success: 623 action.noop.success: 326 energy.amount: 8 energy.gained: 1954 energy.lost: 1946 hp.amount: 67 hp.gained: 1075 hp.lost: 1008 junction.aligned_by_agent: 2 status.max_steps_without_motion: 17 type: object required: - agent_id - reward - metrics title: AgentResult ````