# Results

A verdict for every outcome official evidence can settle, and nothing guessed.

## What a result is

`GET /v1/results` returns graded outcomes for finished events. Each outcome carries the same outcome id as its [prices](https://sockodds.com/docs/odds/), so you can settle a bet by looking up the id you priced.

Results are graded from official result sources only, never from a bookmaker's settlement. An outcome that official evidence cannot settle is left out, never guessed. A market settles only once every one of its outcomes can be graded.

## Ask for results

| Parameter | Meaning |
| --- | --- |
| `event_id` | One event's result. |
| `league` | Results for one league, such as `nfl`. On the free Developer plan, `league` is required. |
| `starts_after`, `starts_before` | A window on the events' scheduled start, in UTC. |
| `limit`, `cursor` | Results per page and the next page. See [Pagination](https://sockodds.com/docs/pagination/). |

Here is the result of an NFL game that has been played:

```bash
curl -sS "https://api.sockodds.com/v1/results?event_id=ev_000ckk06psy5" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"
```

```javascript
const response = await fetch("https://api.sockodds.com/v1/results?event_id=ev_000ckk06psy5", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));
```

```python
import json, os, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/results?event_id=ev_000ckk06psy5",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
with urllib.request.urlopen(request) as response:
    print(json.dumps(json.load(response), indent=2))
```

Response (from a local copy of the API with invented test prices):

```json
{
  "data": [
    {
      "event": {
        "id": "ev_000ckk06psy5",
        "name": "Arizona Cardinals v Atlanta Falcons",
        "league": {
          "key": "nfl",
          "name": "NFL"
        },
        "scheduled_start": "2026-10-12T08:00:00.000Z",
        "status": "final",
        "participants": [
          {
            "role": "away",
            "identity": {
              "key": "atlanta_falcons",
              "name": "Atlanta Falcons"
            }
          },
          {
            "role": "home",
            "identity": {
              "key": "arizona_cardinals",
              "name": "Arizona Cardinals"
            }
          }
        ]
      },
      "status": "final",
      "settlement": "partial",
      "pending_markets": 1,
      "settled_at": "2026-10-12T12:00:00.000Z",
      "outcomes": [
        {
          "id": "oc_1dppq89hj6hzh2vs",
          "name": "Arizona Cardinals",
          "verdict": "won",
          "market": {
            "id": "mk_w3g0d83k64amvfmc",
            "key": "winner",
            "name": "Winner",
            "period": "full",
            "subject": null
          },
          "side": "home",
          "line": null
        },
        {
          "id": "oc_9cefdq0gf0ng5wz9",
          "name": "Arizona Cardinals",
          "verdict": "won",
          "market": {
            "id": "mk_809y8e9bfgq739jt",
            "key": "handicap",
            "name": "Handicap",
            "period": "full",
            "subject": null
          },
          "side": "home",
          "line": -3.5
        },
        {
          "id": "oc_cde9mrxgjh51dkzy",
          "name": "Atlanta Falcons",
          "verdict": "lost",
          "market": {
            "id": "mk_w3g0d83k64amvfmc",
            "key": "winner",
            "name": "Winner",
            "period": "full",
            "subject": null
          },
          "side": "away",
          "line": null
        },
        {
          "id": "oc_mrajcnv0jg71twnp",
          "name": "Atlanta Falcons",
          "verdict": "lost",
          "market": {
            "id": "mk_809y8e9bfgq739jt",
            "key": "handicap",
            "name": "Handicap",
            "period": "full",
            "subject": null
          },
          "side": "away",
          "line": 3.5
        }
      ]
    }
  ],
  "meta": {
    "count": 1,
    "cursor": null
  },
  "links": {
    "next": null
  }
}
```

## Reading a result

| Field | What it holds |
| --- | --- |
| `event` | The event, in the same shape as `/v1/events/{event_id}`. |
| `status` | `final`, or `corrected` when the official source changed a result after we first published it. |
| `settlement` | `complete` when every market we quoted on the event is settled. `partial` while any market is still pending. |
| `pending_markets` | How many quoted markets are still waiting for official evidence. |
| `settled_at` | When the result was last settled or extended, in UTC. |
| `outcomes` | The graded outcomes. |

Each outcome has its `id`, `name`, `side` and `line`, the `market` it belongs to (`id`, `key`, `name`, `period`, `subject`), and a `verdict`:

| `verdict` | Meaning |
| --- | --- |
| `won` | The selection won. |
| `lost` | The selection lost. |
| `void` | The bet is void and the stake is returned. |
| `dead_heat` | A tie the rules settle as a dead heat. `dead_heat_factor` is the share of the stake paid at the quoted price; the rest of the stake is lost. |

A dead heat pays `stake × dead_heat_factor × price`. A $10 bet at 1.90 with a factor of 0.5 returns $9.50. Dead heats with a factor of 0.5 apply to a drawn AFL or AFLW head to head, a drawn AFLW quarter or half winner, and a Rugby League World Cup head to head still level after golden point.

## Partial results grow, they do not change

Each market settles on its own once official evidence settles all of its outcomes. So a result can be published with `settlement: partial` while some markets wait, for example player markets that need detail the official source has not published yet. When more markets settle, the same event's result gains the new outcomes and `pending_markets` falls. Verdicts already published stay as they are.

If an official source corrects a result, the event's `status` becomes `corrected` and `settled_at` moves later. Re-read any event whose `status` or `settled_at` changed since you last settled it.

## What you will not find

- **Events we never priced.** Results grade the outcomes we quoted, so an event with no prices has no result.
- **Guesses.** A tie with no published rule, an unusual finish, or a player whose participation the official source does not confirm stays pending.
- **A zero.** A missing verdict means the outcome is not settled yet, never that it lost.

## Settle from a program

This program reads NFL results and prints each outcome's verdict:

```javascript
const response = await fetch("https://api.sockodds.com/v1/results?league=nfl", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
const body = await response.json();
for (const result of body.data) {
  const pending = result.pending_markets === 1 ? "1 market" : `${result.pending_markets} markets`;
  console.log(`${result.event.name}: ${result.settlement}, ${pending} pending`);
  for (const outcome of result.outcomes) {
    const line = outcome.line === null ? "" : ` ${outcome.line > 0 ? "+" : ""}${outcome.line}`;
    const share = outcome.verdict === "dead_heat" ? ` (${outcome.dead_heat_factor} of the stake)` : "";
    console.log(`  ${outcome.market.name} (${outcome.market.period}): ${outcome.name}${line} ${outcome.verdict}${share}`);
  }
}
```

```python
import json, os, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/results?league=nfl",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
with urllib.request.urlopen(request) as response:
    body = json.load(response)
for result in body["data"]:
    pending = "1 market" if result["pending_markets"] == 1 else f"{result['pending_markets']} markets"
    print(f"{result['event']['name']}: {result['settlement']}, {pending} pending")
    for outcome in result["outcomes"]:
        line = "" if outcome["line"] is None else " " + ("+" if outcome["line"] > 0 else "") + str(outcome["line"])
        share = f" ({outcome['dead_heat_factor']} of the stake)" if outcome["verdict"] == "dead_heat" else ""
        print(f"  {outcome['market']['name']} ({outcome['market']['period']}): {outcome['name']}{line} {outcome['verdict']}{share}")
```

Output (from a local copy of the API with invented test prices):

```text
Arizona Cardinals v Atlanta Falcons: partial, 1 market pending
  Winner (full): Arizona Cardinals won
  Handicap (full): Arizona Cardinals -3.5 won
  Winner (full): Atlanta Falcons lost
  Handicap (full): Atlanta Falcons +3.5 lost
```

For a ledger that settles bets as results arrive, see [Settle bets](https://sockodds.com/docs/examples/settle-bets/).