Match Events

Derived basketball and tennis markers for one game, alongside the price history in +EV History.


GET /api/v1/historical/match-events

Enterprise tier required. Uses the history feature, like /api/v1/ev/history. Lower tiers receive 403 tier_restricted.

Query parametersPermalink for this section

Parameter	Type	Description
`game_id`	string	Required. Same game ID as `/api/v1/ev/history`.
`until`	string	RFC 3339 timestamp or Unix seconds. Defaults to now; future values are clamped to now. Only observations at or before this cutoff are included.


curl -G 'https://api.sharpapi.io/api/v1/historical/match-events' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'game_id=YOUR_GAME_ID' \
  --data-urlencode 'until=2026-10-22T00:01:00Z'

ResponsePermalink for this section

Illustrative basketball response; IDs and times are examples.


{
  "success": true,
  "events": [
    {
      "t": "2026-10-22T00:00:00Z",
      "kind": "tip",
      "label": "TIP",
      "side": ""
    }
  ],
  "serve": [],
  "meta": {
    "game_id": "example-game-id",
    "sport": "basketball",
    "supported": true,
    "as_of": "2026-10-22T00:01:00Z",
    "snapshots": 2,
    "truncated": false,
    "available": true,
    "serve_inferred": false,
    "sampling": "event times are when SharpAPI observed a scoreboard change, so they can lag the real event, and a change that cancels out between two observations is not seen",
    "max_lag_seconds": 30
  }
}

Event and serve fieldsPermalink for this section

Basketball: tip, period end and unanswered scoring run. Tennis: break of serve and set end.

Field	Description
`events[].t`	Observation time in UTC (RFC 3339, possibly fractional seconds).
`events[].kind`	`tip`, `period_end`, `run`, `break`, `set_end`
`events[].label`	Short display label; for example `TIP`, `Q1 end`, `8-0`, `BRK`, `SET`.
`events[].side`	`home`, `away`, or an empty string for a neutral event.
`serve`	Tennis only: intervals with `t0`, `t1`, `server`. On a tiebreak, `tiebreak: true` is present and `server` identifies the first server. Other sports return `[]`. Server/break inference depends on sampled scoreboards; it is not an authoritative point-by-point service feed.

Metadata and empty resultsPermalink for this section

Field	Description
`meta.game_id`	Requested game ID.
`meta.as_of`	Effective cutoff in UTC.
`meta.sport` / `meta.supported`	`basketball` and `tennis` are supported. Other sports return `supported: false` and empty arrays. With no rows, `sport` is empty and `supported` is false.
`meta.snapshots`	Number of scoreboard snapshots used. No rows returns `200`, `snapshots: 0` and empty arrays; this does not establish that nothing happened.
`meta.available`	`false` when the history reader is unavailable; this also returns an empty `200`. A query failure instead returns `500 upstream_error`.
`meta.truncated`	Whether the snapshot row limit cut the history short.
`meta.serve_inferred`	Whether tennis serving could be inferred from a known first server.
`meta.sampling` / `meta.max_lag_seconds`	Sampling explanation and nominal lag indicator; see limits below.

Observation-time limitsPermalink for this section

These are derived markers from sampled scoreboard changes, not play-by-play timestamps. They record when SharpAPI observed a change, not when it occurred at the source. max_lag_seconds is a nominal lag indicator, not a latency guarantee. Changes that cancel out between samples can be missed.

ErrorsPermalink for this section

400 validation_error for missing/invalid game_id or invalid until. Normal API-key authentication and rate limits apply.