Prefer to chat? Query the API with natural language using our AI Skill →

Give your AI tool live Cito endpoint context before you write integration code.

Open AI Skill

Public docs assistant

Tell Cito API what you are building.

Get endpoint recommendations, exact requests, code snippets, and a free-key CTA without digging through every page.

Docs/Call of Duty API/Matches

Back to Call of Duty API

Matches

Access match details, live scores, and per-map player statistics

List Recent Matches

GET/cod/matches

GET/cod/matches/recent

Get recently completed matches with team, score, winner, tournament, and schedule metadata. Supports page/limit pagination, offset pagination, season filters, team filters, and date ranges for historical CDL databases.

Query Parameters

Parameter	Type	Description
`team`	string	Team slug filter, e.g. optic-texas
`tournamentId`	string	Tournament ID filter
`season`	string	Tournament season year
`startDate`	string	Start date filter, e.g. 2026-04-01
`endDate`	string	End date filter, e.g. 2026-04-30
`page`	number	Page number for page-based pagination
`days`	number	Only matches completed in the last N days
`limit`	number	Results to return (default: 25, max: 100)
`offset`	number	Pagination offset

Example Request

GET /api/v1/cod/matches?season=2025&page=2&limit=25

Response

{
  "success": true,
  "count": 25,
  "total": 1464,
  "pagination": {
    "limit": 25,
    "offset": 25,
    "page": 2,
    "totalPages": 59,
    "hasMore": true,
    "nextPage": 3,
    "nextOffset": 50
  },
  "data": [
    {
      "id": "...",
      "matchId": "bp-match-325854",
      "bpMatchId": 325854,
      "round": "Winners Round 1",
      "status": "completed",
      "startsAt": "2025-01-28T18:00:00Z",
      "tournament": {
        "tournamentId": "cdl-major-1-2025",
        "name": "CDL Major 1"
      },
      "team1": {
        "slug": "optic-texas",
        "name": "OpTic Texas",
        "score": 3
      },
      "team2": {
        "slug": "atlanta-faze",
        "name": "Atlanta FaZe",
        "score": 1
      },
      "winnerSlug": "optic-texas"
    }
  ]
}

List Upcoming Matches

GET/cod/matches/upcoming

Get upcoming scheduled and live matches from the database. Use this for team pages, countdowns, and schedule widgets.

Query Parameters

Parameter	Type	Description
`team`	string	Team slug filter
`tournamentId`	string	Tournament ID filter
`season`	string	Tournament season year
`limit`	number	Results to return (default: 25, max: 100)
`offset`	number	Pagination offset

Example Request

GET /api/v1/cod/matches/upcoming?season=2026

Response

{
  "success": true,
  "count": 1,
  "total": 8,
  "data": [
    {
      "id": "...",
      "matchId": "12600",
      "status": "scheduled",
      "startsAt": "2026-02-07T19:00:00Z",
      "bestOf": 5,
      "tournament": {
        "name": "CDL Major 2 Qualifiers",
        "season": "2026"
      },
      "team1": {
        "slug": "optic-texas",
        "name": "OpTic Texas",
        "score": 0
      },
      "team2": {
        "slug": "los-angeles-thieves",
        "name": "Los Angeles Thieves",
        "score": 0
      }
    }
  ]
}

Get Match Details

GET/cod/matches/:id

Get full match details including per-map scores, player stats, and VOD links.

Example Request

GET /api/v1/cod/matches/12588

Response

{
  "success": true,
  "data": {
    "id": "...",
    "matchId": "12588",
    "round": "Winners Round 1",
    "team1": {
      "slug": "optic-texas",
      "name": "OpTic Texas",
      "logoUrl": "..."
    },
    "team2": {
      "slug": "atlanta-faze",
      "name": "Atlanta FaZe",
      "logoUrl": "..."
    },
    "team1Score": 3,
    "team2Score": 1,
    "winnerSlug": "optic-texas",
    "matchDate": "2025-01-28T18:00:00Z",
    "status": "completed",
    "tournament": {
      "name": "CDL Major 1",
      "id": "cdl-major-1-2025"
    },
    "maps": [
      {
        "mapNumber": 1,
        "mapName": "Rewind",
        "mapImageUrl": "https://...",
        "gameMode": "Hardpoint",
        "team1Score": 250,
        "team2Score": 180,
        "played": true,
        "pickedBy": "optic-texas"
      }
    ],
    "playerStats": [...]
  }
}

Get Match Maps

GET/cod/matches/:id/maps

Get per-map breakdown for a match including scores and game modes.

Response

{
  "success": true,
  "data": [
    {
      "mapNumber": 1,
      "mapName": "Rewind",
      "gameMode": "Hardpoint",
      "team1Score": 250,
      "team2Score": 180,
      "winner": "optic-texas",
      "duration": "10:23"
    }
  ]
}

Get Map Player Stats

GET/cod/matches/:id/maps/:mapNumber/player-stats

Get individual player stats for a specific map in a match.

Example Request

GET /api/v1/cod/matches/12588/maps/1/player-stats

Response

{
  "success": true,
  "data": {
    "map": {
      "mapNumber": 1,
      "mapName": "Rewind",
      "gameMode": "Hardpoint"
    },
    "players": [
      {
        "ign": "Shotzzy",
        "team": "optic-texas",
        "kills": 32,
        "deaths": 24,
        "kd": 1.33,
        "damage": 4850,
        "hillTime": "1:45",
        "engagements": 56
      }
    ]
  }
}

Get Match Player Stats

GET/cod/matches/:id/player-stats

Get match-level per-player totals aggregated across all maps, with optional game/map-level player stats included. This is the recommended endpoint for fantasy, betting, post-match reports, and player performance dashboards.

Query Parameters

Parameter	Type	Description
`includeMaps`	boolean	Include per-map/game player stat rows for each player (default: true)

Example Request

GET /api/v1/cod/matches/bp-match-214935/player-stats?includeMaps=true

Response

{
  "success": true,
  "data": {
    "match": {
      "matchId": "bp-match-214935",
      "bpMatchId": 214935,
      "status": "completed",
      "round": "Round 2",
      "matchDate": "2026-04-25T20:30:00.000Z"
    },
    "teams": {
      "team1": {
        "slug": "faze-vegas",
        "name": "FaZe Vegas"
      },
      "team2": {
        "slug": "riyadh-falcons",
        "name": "Riyadh Falcons"
      }
    },
    "score": {
      "team1": 3,
      "team2": 1,
      "formatted": "3-1"
    },
    "winnerSlug": "faze-vegas",
    "source": "breakingpoint",
    "count": 8,
    "players": [
      {
        "playerName": "Simp",
        "teamSlug": "faze-vegas",
        "mapsPlayed": 4,
        "kills": 88,
        "deaths": 70,
        "assists": 31,
        "kd": 1.26,
        "damage": 10425,
        "hillTime": 91,
        "firstBloods": 3,
        "plants": 1,
        "defuses": 0,
        "highestStreak": 8,
        "ratings": {
          "overall": 1.08
        },
        "maps": [
          {
            "mapNumber": 1,
            "mapName": "Protocol",
            "gameMode": "Hardpoint",
            "kills": 28,
            "deaths": 20,
            "damage": 3290
          }
        ]
      }
    ]
  }
}

Get Live Matches

GET/cod/matches/live

GET/cod/cdl/live

Get currently live matches with real-time scores. Perfect for live score tickers and notifications.

Response

{
  "success": true,
  "isLive": true,
  "count": 1,
  "data": [
    {
      "matchId": "...",
      "tournament": "CDL Major 1",
      "round": "Winners Final",
      "team1": {
        "name": "OpTic Texas",
        "slug": "optic-texas",
        "score": 2
      },
      "team2": {
        "name": "Atlanta FaZe",
        "slug": "atlanta-faze",
        "score": 1
      },
      "currentMap": {
        "mapNumber": 4,
        "mapName": "Highrise",
        "gameMode": "Hardpoint"
      },
      "bestOf": 5,
      "status": "live",
      "startedAt": "2025-01-28T19:00:00Z"
    }
  ]
}

Tournaments

CDL League