# Get fair value

Source: https://langbot.ai/docs/api/live-events/get-fair-value

`GET /v1/models/fair-value`

A pre-event statistic per open market, from how often the speaker said the market's words in past recorded appearances.

**Auth.** An API token: `Authorization: Bearer lb_…` ([create one](https://langbot.ai/app/tokens)). Signed-in web sessions work too.

**Limits.** One model call per call (100 a day on Free; unlimited on Builder and Standard).

## Parameters

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | no | An event (`ev_…`); every open market of it. Send this or `ticker`. |
| `ticker` | string | no | One market. Send this or `event_id`. |
| `window_days` | integer | no | History window in days. 1 to 3650. |

## Request

**curl**

```bash
curl "https://api.langbot.ai/v1/models/fair-value?event_id=ev_nvda_q3_2026" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN"
```

**Python**

```python
from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    fv = await lb.fair_value("ev_nvda_q3_2026")
    for m in fv["markets"]:
        print(m["ticker"], m["model_p"], m["n_events"], m["market_mid"])
```

**TypeScript**

```ts
import { LangbotClient } from "@langbotai/sdk";

const lb = new LangbotClient(); // reads LANGBOT_API_TOKEN
const fv = await lb.fairValue({ eventId: "ev_nvda_q3_2026" });
console.log(fv.markets);
```

## Response

`200 OK`

```json
{
  "ts": 1760040000000,
  "as_of": 1760040000000,
  "window_days": 365,
  "event": { "id": "ev_nvda_q3_2026", "title": "NVIDIA Q3 FY2027 earnings call", "kind": "earnings", "starts_at": 1760050800000 },
  "model": { "name": "fair_value", "version": 1, "prior_strength_events": 5 },
  "count": 1,
  "markets": [
    {
      "ticker": "KXEARNINGSMENTIONNVDA-26OCT-BLACKWELL",
      "phrase": "blackwell",
      "min_count": 1,
      "model_p": 0.94,
      "history_p": 0.97,
      "n_events": 6,
      "per_minute_rate": 0.21,
      "expected_minutes": 60,
      "base_rate": { "scope": "speaker_phrase", "yes_rate": 0.86, "n": 7 },
      "market_mid": 0.92,
      "difference": 0.02,
      "history": [],
      "excluded": { "count": 0, "by_reason": {}, "events": [] },
      "caveats": ["6 past appearances"]
    }
  ],
  "caveats": []
}
```

`model_p` is a Poisson rate scaled to the event's expected length and shrunk toward the venue base rate. `difference` is `model_p − market_mid`. Statistics under a stated model, not a signal: read `n_events` and `caveats`.

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `bad_request` | Neither `event_id` nor `ticker` was sent, or the ticker is not on the event. |
| 404 | `not_found` | Unknown event or ticker. |
| 401 | `auth_required` | No token was sent. |
| 401 | `token_invalid` | The token was not recognised (mistyped, revoked or expired). |
| 422 | `validation_error` | A parameter failed validation; `detail[].loc` names it. |
| 429 | `quota_exceeded` | Today's model calls are spent; `quota.resets_at` says when they reset. |
| 429 | `rate_limited` | Over your request budget; wait `Retry-After` seconds. |

Every error body is `{"detail": …, "code": "…"}`; branch on `code`. All codes: [Errors](https://langbot.ai/docs/api#errors).