Stats API
Menu
Sign in Start building
Agent API use case

Football data for AI agents
grounded in a stable contract.

Give a tool-calling agent a small, typed football surface with explicit coverage and freshness signals, so it reports what it knows and says so when it does not.

Start building → Explore endpoints
Why Stats API

A small, reliable tool surface for football agents.

Connect a server-side agent to the OpenAPI contract, keep the bearer key outside the model context, and expose only the operations the workflow needs.

Start with competition discovery, team lookup, and filtered fixtures. Handle 401, 429, and 503 responses explicitly instead of asking the model to improvise around failures.

The hardest problem in agent tooling is not calling the API — it is stopping the model inventing entities. A model asked for "Arsenal fixtures" will happily fabricate an identifier. Resolve the name to a Stats API team ID with a real search call, then pass that ID to every subsequent tool call. The identifier is the grounding.

Give the agent the documented availability fields. Match statistics carry coverage flags; season summaries distinguish available, not_observed and observed_empty. These fields describe their own scope and must not be expanded into a claim of complete competition coverage.

Ingestion is scheduled rather than streamed. Read the timing fields documented for the requested resource; a coverage-summary observation does not establish freshness for a different match, season or market. Missing timestamps remain unknown.

01

Least-privilege tools

Expose only required read operations to the agent runtime. An agent does not need every endpoint to answer one question.

02

Schema-grounded output

Use API responses as facts, then let the model summarise or transform them. Never let it supply the numbers.

03

Resolve, then reference

Turn names into Stats API identifiers with a search call before any downstream request.

04

Coverage as a first-class answer

Let the agent report "not covered" from the coverage flag instead of guessing.

05

Quota-aware workflows

Read X-StatsAPI-Cache and the quota headers; cache at the application layer where the same question repeats.

06

Explicit failure paths

Map 401, 403, 429 and 503 to distinct agent behaviours. Retrying a 403 never helps.

Agent tool surface

Ground the model; never let it supply the numbers.

An agent fails in two ways on sports data: it invents an identifier, or it invents a statistic for a competition nobody covers. Both are solved the same way — resolve names to Stats API IDs with a real call, and let the coverage flag answer for absence.

Good agent tools
Expose these
Search and resolve ✓ Turn a competition or team name into a stable ID before any downstream call.
Filtered fixtures ✓ Bounded queries by competition, season, team, status and UTC date window.
Match detail and statistics ✓ One call returns the scoreline, team statistics and coverage state together.
Coverage summary ✓ Lets the agent answer "not covered" from data rather than guessing.
Keep out of the tool list
Avoid these patterns
Raw ID guessing — Never let the model construct an identifier it did not receive from a response.
Unbounded listing — A tool with no filter invites the model to page forever and burn quota.
Keys in context — Hold the bearer token server-side; it should never enter the prompt.
Silent retries — Map 401, 403, 429 and 503 to distinct behaviours. Retrying a 403 never helps.
Agent workflow

Resolve, then reference.

One search call converts a human name into a stable ID. Every later call passes that ID, so the model never has to remember or invent an identifier, and the transcript stays auditable.

Read the match endpoint guide →
1 · Find a competition ID
curl --silent --show-error \
  "https://stats-api.com/api/v1/football/competitions?q=Premier%20League" \
  -H "Authorization: Bearer ${STATS_API_KEY}" \
  -H "Accept: application/json"
2 · Fetch its completed matches
curl --silent --show-error \
  "https://stats-api.com/api/v1/football/matches?competition_id=${COMPETITION_ID}&status=finished" \
  -H "Authorization: Bearer ${STATS_API_KEY}" \
  -H "Accept: application/json"
Agent building blocks

The contract, the limits, and the ID strategy.

These pages document the typed schema an agent reads against, the quota behaviour it must handle, and why identifiers stay stable across a provider change.

Contract

OpenAPI reference

Typed schemas and required fields for every published operation.

Read more AI integration

Football AI API

How the contract is shaped for retrieval and tool calling.

Read more Engineering guide

Keep football IDs stable

Why agent memory and joins should not depend on upstream identifiers.

Read more
Build with football data

One key. One contract.
A clearer path to production.

View pricing →