> ## 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. # Search Episodes > Search recorded episodes with an AND/OR filter AST over any episode field. Anonymous callers see public episodes. Authenticated Users and Players also see private episodes admitted by the enclosing XP, qualifier, or league. ## OpenAPI ````yaml https://softmax.com/api/observatory/openapi.json post /v2/episodes/search 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 security: [] paths: /v2/episodes/search: post: tags: - v2 - v2 summary: Search Episodes description: >- Search recorded episodes with an AND/OR filter AST over any episode field. Anonymous callers see public episodes. Authenticated Users and Players also see private episodes admitted by the enclosing XP, qualifier, or league. operationId: search_episodes_v2_episodes_search_post requestBody: content: application/json: schema: $ref: '#/components/schemas/EpisodeSearchRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EpisodeSearchPage' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - BearerAuth: [] - {} components: schemas: EpisodeSearchRequest: properties: where: anyOf: - additionalProperties: true type: object - type: 'null' title: Where description: >- Filter AST. Composites: {op: and|or, clauses: [node, ...]} and {op: not, clause: node}. Leaves: {op: eq|ne|gt|gte|lt|lte|in|like|ilike|exists|contains|includes|excludes, field: , value: }. 'includes'/'excludes' take a list: the episode must include all / none of the values (e.g. all of these policy.version_id values participated). See GET /v2/episodes/search/fields for the queryable field paths. Example: {"op": "and", "clauses": [{"op": "eq", "field": "coworld.name", "value": "crewrift_prime"}, {"op": "includes", "field": "policy.version_id", "value": ["", ""]}]} order_by: type: string const: created_at title: Order By description: >- Episodes are ordered by creation time (id as tiebreak); order_dir picks the direction. This is the only supported order: it is what an index can serve, and it is what a keyset cursor will page over. default: created_at order_dir: type: string enum: - asc - desc title: Order Dir default: desc mine: type: boolean title: Mine description: >- Only episodes requested by the authenticated User or exact Player credential. default: false limit: type: integer maximum: 500 minimum: 1 title: Limit default: 50 cursor: anyOf: - type: string maxLength: 4096 - type: 'null' title: Cursor description: >- Opaque keyset cursor from a previous page's next_cursor. Bound to the query that issued it: reuse with a different where/order_dir/mine (or a different caller) is rejected. additionalProperties: false type: object title: EpisodeSearchRequest EpisodeSearchPage: properties: entries: items: $ref: '#/components/schemas/EpisodeSearchResult' type: array title: Entries next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: >- Cursor for the page after this one; non-null means more episodes match, null means this is the last page. limit: type: integer title: Limit type: object required: - entries - next_cursor - limit title: EpisodeSearchPage HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError EpisodeSearchResult: properties: episode_id: type: string format: uuid title: Episode Id created_at: type: string format: date-time title: Created At replay_url: anyOf: - type: string - type: 'null' title: Replay Url thumbnail_url: anyOf: - type: string - type: 'null' title: Thumbnail Url coworld_id: anyOf: - type: string - type: 'null' title: Coworld Id description: Coworld id (cow_...) when the episode came from a coworld run coworld_name: anyOf: - type: string - type: 'null' title: Coworld Name coworld_version: anyOf: - type: string - type: 'null' title: Coworld Version tags: additionalProperties: type: string type: object title: Tags policies: items: $ref: '#/components/schemas/EpisodeSearchPolicy' type: array title: Policies results: title: Results description: Game-specific results object recorded for this episode, if any attributes: anyOf: - additionalProperties: true type: object - type: 'null' title: Attributes description: Full episode attributes JSONB type: object required: - episode_id - created_at - replay_url - thumbnail_url - coworld_id - coworld_name - coworld_version - tags - policies - results - attributes title: EpisodeSearchResult 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 EpisodeSearchPolicy: properties: policy_version_id: type: string format: uuid title: Policy Version Id policy_name: anyOf: - type: string - type: 'null' title: Policy Name version: anyOf: - type: integer - type: 'null' title: Version player_id: anyOf: - type: string - type: 'null' title: Player Id num_agents: type: integer title: Num Agents type: object required: - policy_version_id - policy_name - version - player_id - num_agents title: EpisodeSearchPolicy securitySchemes: BearerAuth: type: http scheme: bearer description: Bearer token issued by Softmax ````