{
  "openapi": "3.0.1",
  "info": {
    "title": "ESPN Sports Data Scraper: Scores, Boxscores, Gamelogs & Odds",
    "description": "Extract ESPN sports data in bulk from its public API: live and historical scores, boxscores, odds, standings, schedules, rosters and player gamelogs, 17 leagues. Flat CSV, Excel and pandas output, no API key. Run via API, schedule runs, or integrate with other tools and AI workflows.",
    "version": "0.2",
    "x-build-id": "jWGp7hhtlk3jFsFNn"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/mrbridge~espn-sports-data-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-mrbridge-espn-sports-data-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/mrbridge~espn-sports-data-scraper/runs": {
      "post": {
        "operationId": "runs-sync-mrbridge-espn-sports-data-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/mrbridge~espn-sports-data-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-mrbridge-espn-sports-data-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "dataType",
          "league"
        ],
        "properties": {
          "dataType": {
            "title": "Data type",
            "enum": [
              "scoreboard",
              "gameSummary",
              "playByPlay",
              "playerBoxscore",
              "schedule",
              "teams",
              "standings",
              "roster",
              "athletes",
              "athleteGamelog",
              "news"
            ],
            "type": "string",
            "description": "What to extract. Each type produces its own flat row shape. See the README for the full field list per type.",
            "default": "scoreboard"
          },
          "league": {
            "title": "League",
            "enum": [
              "nfl",
              "college-football",
              "nba",
              "wnba",
              "mens-college-basketball",
              "womens-college-basketball",
              "mlb",
              "nhl",
              "eng.1",
              "esp.1",
              "ita.1",
              "ger.1",
              "fra.1",
              "usa.1",
              "uefa.champions",
              "uefa.europa",
              "fifa.world"
            ],
            "type": "string",
            "description": "Which league to pull from. 17 leagues in v1. Not every data type is available for every league (see the capability matrix in the README).",
            "default": "nba"
          },
          "startDate": {
            "title": "Start date",
            "type": "string",
            "description": "Start of the date range for a scoreboard pull, format YYYY-MM-DD. Use this with End date, or use Seasons for full-season bulk."
          },
          "endDate": {
            "title": "End date",
            "type": "string",
            "description": "End of the date range for a scoreboard pull, format YYYY-MM-DD. Inclusive."
          },
          "seasons": {
            "title": "Seasons",
            "type": "array",
            "description": "One season year per line, for bulk multi-season pulls (scoreboard, standings, gamelog). Season bounds are discovered from ESPN, never hardcoded.",
            "items": {
              "type": "string"
            }
          },
          "seasonType": {
            "title": "Season type",
            "enum": [
              "all",
              "1",
              "2",
              "3"
            ],
            "type": "string",
            "description": "Which part of the season to pull. Default is All (preseason + regular season + postseason) for a complete season. Pick a single type to narrow the pull.",
            "default": "all"
          },
          "teamIds": {
            "title": "Team IDs",
            "type": "array",
            "description": "ESPN team IDs, one per line. Required for Team schedule and Roster.",
            "items": {
              "type": "string"
            }
          },
          "eventIds": {
            "title": "Event (game) IDs",
            "type": "array",
            "description": "ESPN event/game IDs, one per line. Used by Game summary, Play-by-play and Player boxscore. You can also chain these automatically from a scoreboard run with 'Also fetch game details'.",
            "items": {
              "type": "string"
            }
          },
          "athleteIds": {
            "title": "Athlete IDs",
            "type": "array",
            "description": "ESPN athlete IDs, one per line. Required for Athlete gamelog.",
            "items": {
              "type": "string"
            }
          },
          "withGameDetails": {
            "title": "Also fetch game details",
            "type": "boolean",
            "description": "On a scoreboard run, chain a detail fetch (summary and/or play-by-play and/or player boxscore) for every game found. Warning: this multiplies cost - each game adds a game-detail charge (de-duplicated per game).",
            "default": false
          },
          "includeOdds": {
            "title": "Include odds",
            "type": "boolean",
            "description": "Attach betting odds (spread, moneyline, over/under) to game detail rows when available.",
            "default": false
          },
          "includeBoxscore": {
            "title": "Include boxscore",
            "type": "boolean",
            "description": "Include team-level boxscore stats on Game summary rows.",
            "default": true
          },
          "resolveRefs": {
            "title": "Resolve athlete references",
            "type": "boolean",
            "description": "For the Athletes directory: resolve each athlete reference into a full profile (extra requests). Turn off to emit only IDs and reference URLs (much cheaper).",
            "default": true
          },
          "allSeasons": {
            "title": "All available seasons (gamelog)",
            "type": "boolean",
            "description": "For Athlete gamelog: discover and pull every season available for the athlete, instead of listing them in Seasons.",
            "default": false
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "flat",
              "raw",
              "both"
            ],
            "type": "string",
            "description": "flat = one flat snake_case row (data-science ready). raw = the ESPN JSON fragment for the entity. both = flat plus a raw field.",
            "default": "flat"
          },
          "maxItems": {
            "title": "Max items (dataset rows)",
            "minimum": 0,
            "type": "integer",
            "description": "Cap the number of dataset ROWS. 0 = unlimited. Note: this bounds rows, not cost. To cap spend, use Max charged events below.",
            "default": 0
          },
          "maxChargedEvents": {
            "title": "Max charged events (cost cap)",
            "minimum": 0,
            "type": "integer",
            "description": "Hard cost ceiling: stop after this many billed events. 0 = unlimited. This is the field to use for cost control (a game with details, or a season gamelog, produces many rows but few charges).",
            "default": 0
          },
          "ncaaGroups": {
            "title": "NCAA groups",
            "minimum": 1,
            "type": "integer",
            "description": "NCAA scoreboard grouping: 50 = FBS / top division (default), 80 = all Division I. Ignored for non-NCAA leagues.",
            "default": 50
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Datacenter proxies are sufficient for ESPN's open API and are the default. Residential is unnecessary here (wasted cost) but available if 403s ever appear.",
            "default": {
              "useApifyProxy": true
            }
          },
          "internalCaptureMode": {
            "title": "Internal capture mode",
            "type": "boolean",
            "description": "Maintainer-only. When true, captures raw ESPN responses to a named KV store for building test fixtures. Not for normal use.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}