Quickstart

This page covers provisioning a key and issuing a first request, about five minutes end-to-end.

Or skip the code entirely: to use StatMuse in Claude, ChatGPT or another agent, you don’t need a key at all. Connect via MCP instead.

1. Provision an API key

Sign in at the API portal with your statmuse.com account and create a key from the dashboard. The raw key is shown exactly once. Copy it into your secret store before dismissing the dialog.

An account can hold multiple keys, one per app or environment, each revocable independently. Rotation is covered in Authentication.

2. Make your first request

Pass the key in the x-statmuse-api-key header. The input query parameter is your question, URL-encoded.

cURL

curl "https://api.statmuse.com/sports/nba/v1/ask?input=who+led+the+nba+in+scoring+in+2024-25" \
  -H "x-statmuse-api-key: $STATMUSE_API_KEY"

TypeScript

const url = new URL("https://api.statmuse.com/sports/nba/v1/ask");
url.searchParams.set("input", "who led the nba in scoring in 2024-25");

const res = await fetch(url, {
  headers: { "x-statmuse-api-key": process.env.STATMUSE_API_KEY! },
});

if (!res.ok) {
  throw new Error(`StatMuse API error: ${res.status}`);
}

const body = await res.json();

3. Read the response

A successful stats response looks like this (abridged):

{
  "type": "stats",
  "input": {
    "original": "who led the nba in scoring in 2024-25"
  },
  "answer": {
    "text": "Shai Gilgeous-Alexander averaged the most points per game in 2024-25, with 32.7 per game.",
    "markdown": "[Shai Gilgeous-Alexander](https://www.statmuse.com/nba/player/shai-gilgeous-alexander-9773) averaged the most points per game in 2024-25, with 32.7 per game."
  },
  "query": { "stats": ["PointsPerGame", "GamesPlayed", "Points"] },
  "data": {
    "results": [
      {
        "context": [
          {
            "type": "player",
            "playerId": 9773,
            "longName": "Shai Gilgeous-Alexander"
          },
          {
            "type": "team",
            "teamId": 38,
            "shortName": "Thunder",
            "abbreviation": "OKC"
          },
          {
            "type": "seasonYear",
            "seasonYear": 2025,
            "seasonYearDisplay": "2024-25",
            "seasonType": "regularSeason"
          }
        ],
        "stats": {
          "PointsPerGame": { "value": 32.68421053, "display": "32.7" },
          "GamesPlayed": { "value": 76, "display": "76" },
          "Points": { "value": 2484, "display": "2,484" }
        }
      }
    ]
  }
}

The type field is a discriminator. Stats questions return "stats" with the full payload above; other questions return "unknown" carrying only input and answer. Inspect type before reading the rest of the body. See Asking Questions for the full model.

Successful responses also carry X-Quota-* headers reporting remaining period quota. See Rate Limits & Quotas.

Next steps

• Asking Questions: the full response shape and how to branch on it.
• Errors: the problem-details slug taxonomy you’ll see on 4xx and 5xx responses.
• Rate Limits & Quotas: burst limits, period quotas and the headers that report them.