> ## Documentation Index > Fetch the complete documentation index at: https://docs.ticktock.bet/llms.txt > Use this file to discover all available pages before exploring further. # List Matches > Bucketed list of live, upcoming, and finished CS2 matches ## What it returns Without `?status`: a bucketed list — live matches first, then upcoming, then finished. With a status filter, only that bucket comes back, sorted appropriately. Phantom 0-0 finished/cancelled rows are filtered out — only matches that actually played are returned. Each row carries the basic match shape (id, teams, event, status, scheduled\_at, live score). Internal fields like integration IDs and `data_delay_seconds` only come through if your key has `cs2:matches:internals`. ## Required scope * **Minimum:** `cs2:matches:list` ## Common queries | Goal | Query | | ----------------- | -------------------------------- | | Live now | `?status=live` | | Upcoming next 24h | `?status=upcoming` | | Recently finished | `?status=finished` | | Just count | `?limit=1` and read `meta.total` | ## Example ```bash theme={null} curl -H "X-API-Key: $TT_KEY" \ "https://ticktock.bet/cs2/v1/matches?status=live&limit=20" ``` ```json theme={null} { "data": [ { "id": "52ef…", "team_a": "Sashi", "team_b": "OG", "event": "ESL Pro League S20", "bo_type": "bo3", "status": "live", "scheduled_at": "2026-05-10T17:00:00+00:00", "score_a": 1, "score_b": 0, "hltv_event_id": 7438, "team_a_hltv_id": 7187, "team_b_hltv_id": 5995 } ], "meta": { "count": 1, "limit": 20 } } ``` ## OpenAPI ````yaml openapi/cs2-api.json GET /cs2/v1/matches openapi: 3.1.0 info: title: TickTock B2B API description: >- Unified CS2 API (``/cs2/v1/*``) plus sport-agnostic ``/v1/*`` meta endpoints. Tenant-authenticated via ``X-API-Key`` or ``x-access-token`` header (REST), or ``api_key`` query parameter (WebSocket). Field visibility is gated by per-key scopes — see ``docs/CS2_API_REFERENCE.md`` for the catalog and migration. version: 1.0.0 servers: - url: https://ticktock.bet description: Production (same-origin proxy) - url: https://feed.ticktock.bet description: Production (B2B subdomain) security: [] paths: /cs2/v1/matches: get: tags: - CS2 summary: List CS2 matches description: >- Without ``status``: bucketed list (live first, then upcoming, then finished). With ``status``: only that bucket, ordered appropriately. Phantom 0-0 finished/cancelled rows are filtered out — only matches that actually played are returned. Supports both JSON (default, rich per-match shape) and XML via ``Accept: application/xml`` or the ``.xml`` sibling URL. The XML body is the AMQP ```` envelope — a compact id/name/tournament/competitors shape, no per-map scores. operationId: list_matches_cs2_v1_matches_get parameters: - name: status in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by status: one of ('upcoming', 'live', 'finished', 'cancelled'). title: Status description: >- Filter by status: one of ('upcoming', 'live', 'finished', 'cancelled'). - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 default: 50 title: Limit - name: accept in: header required: false schema: type: string default: application/json title: Accept responses: '200': description: Successful Response content: application/json: schema: title: Response List Matches Cs2 V1 Matches Get example: data: - id: 52ef0d9c-7c1f-4c4e-9b3a-4a5e2f8b1c10 team_a: Sashi team_b: OG team_a_logo: https://images.ticktock.bet/teams/sashi.png team_b_logo: https://images.ticktock.bet/teams/og.png hltv_event_id: 7438 team_a_hltv_id: 7187 team_b_hltv_id: 5995 event: ESL Pro League S20 bo_type: bo3 status: live scheduled_at: '2026-05-10T17:00:00+00:00' score_a: 1 score_b: 0 map_name: de_mirage meta: count: 1 application/xml: {} '401': description: >- Missing API key. Pass either `X-API-Key: ` or `$x$access-token: ` on REST calls (or `?api_key=` on WebSocket handshakes). content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. required: - detail example: detail: Missing X-API-Key or $x$access-token header '403': description: >- API key authenticated but lacks the scope required for this endpoint, or the path's sport is not in the key's `sport_allowlist`. Use `GET /v1/whoami` to inspect the granted scope set. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. required: - detail example: detail: >- Required scope 'cs2:matches:detail' is not granted to this API key. Contact your account manager to extend the key's scopes. '422': description: >- Validation error — a query/path parameter failed validation. The body lists the offending fields. content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' example: detail: - type: enum loc: - query - time_filter msg: 'Input should be one of: 3m, 6m, 1y, all' input: 2w '429': description: >- Tenant rate limit exceeded. Default is 600 req/min per tenant; configurable per contract. WebSocket connections are not rate-limited at the request layer. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. required: - detail example: detail: Rate limit exceeded (600 req/min) headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 30 security: - XAPIKeyHeader: [] - XAccessTokenHeader: [] - UOFAccessTokenHeader: [] components: schemas: 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: XAPIKeyHeader: type: apiKey description: Tenant API key issued during onboarding in: header name: X-API-Key XAccessTokenHeader: type: apiKey description: UOF-standard alias for the tenant API key in: header name: x-access-token UOFAccessTokenHeader: type: apiKey description: Deprecated alias for x-access-token (backward compatibility) in: header name: $x$access-token ````