# GET /v2/scan

**As-of scan**

Time-travel form of `GET /v2/scan`. Pass `?asof=YYYY-MM-DD` (or full ISO) and the server evaluates your `q` against the daily-state snapshot of every ticker on that day. Same SQL grammar, same response envelope as live; the `_meta.resolution: "daily"` marker and `_meta.frozen_fields` list signal that the universe was reconstructed from historical state.

## Plan access

- **Plan access.** Included on every plan.
- **Rate limit.** Hobby 600/min · Pro 2,000/min · Scale 10,000/min.
- **Asof depth.** All-time on every paid plan.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `q` | query | string | yes | SQL WHERE expression. Same grammar as live scan. Max 4000 chars. Example: `gap_up AND small_cap`. |
| `asof` | query | string | yes | Target date as `YYYY-MM-DD` or full ISO timestamp. The server evaluates the WHERE against the close-of-day snapshot for this date. Example: `2024-01-22`. |
| `universe` | query | string | no | Slug of a system or caller-owned universe. Scopes the scan to those tickers as of the same date. |
| `order` | query | string | no | Column to sort by. Same column whitelist as live scan. Default: `day_change_pct`. |
| `dir` | query | string | no | Sort direction. Enum: `asc`, `desc`. Default: `desc`. |
| `fields` | query | string | no | Comma-separated list of extra columns to include in each result row. Default columns are always present. Example: `rsi_14,relative_volume`. |
| `limit` | query | integer | no | Page size. Max 100. Default: `50`. |
| `cursor` | query | string | no | Opaque cursor from the previous response. |

## Status codes

- **200** — Page of matching rows at `asof` with `as_of`, `query`, `count`, `next_cursor`, and `results`. `_meta.resolution: "daily"` and `_meta.frozen_fields` describe the historical envelope.
- **400** — Missing/malformed `asof`, malformed `q`, unknown column, invalid `order`/`dir`/`fields`, or invalid cursor.
- **402** — Query references a premium signal and your plan does not include premium signals.
- **404** — Referenced `universe` does not exist.

## Sample response

```json
{
  "as_of": "2024-01-22",
  "query": { "q": "gap_up AND small_cap", "asof": "2024-01-22", "limit": 3, "order": "day_change_pct", "dir": "desc", "fields": [], "full": false, "universe": null },
  "count": 3,
  "next_cursor": "eyJhZnRlcl9vcmRlcl92YWx1ZSI6MC4wODksImFmdGVyX3RpY2tlciI6IkRKVCJ9",
  "_meta": {
    "resolution": "daily",
    "frozen_fields": ["name", "sector", "industry", "asset_type", "exchange"]
  },
  "results": [
    { "ticker": "SMCI", "name": "Super Micro Computer, Inc.", "asset_type": "CS", "price":  37.42, "day_change_pct": 0.187, "gap_pct": 0.094, "relative_volume": 5.2, "market_cap": 1980000000 },
    { "ticker": "SOUN", "name": "SoundHound AI, Inc.",        "asset_type": "CS", "price":   4.81, "day_change_pct": 0.142, "gap_pct": 0.061, "relative_volume": 4.8, "market_cap":  840000000 },
    { "ticker": "BBAI", "name": "BigBear.ai Holdings",         "asset_type": "CS", "price":   6.12, "day_change_pct": 0.118, "gap_pct": 0.054, "relative_volume": 3.2, "market_cap":  890000000 }
  ]
}
```

## Examples

### Who matched the small-cap breakout setup on Jan 22, 2024?

Request:

```shell
curl "https://api.tickerbot.io/v2/scan?q=gap_up%20AND%20market_cap%20%3C%202000000000&asof=2024-01-22&limit=3" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
{
  "as_of": "2024-01-22",
  "query": { "q": "gap_up AND small_cap", "asof": "2024-01-22", "limit": 3, "order": "day_change_pct", "dir": "desc", "fields": [], "full": false, "universe": null },
  "count": 3,
  "next_cursor": "eyJhZnRlcl9vcmRlcl92YWx1ZSI6MC4wODksImFmdGVyX3RpY2tlciI6IkRKVCJ9",
  "_meta": {
    "resolution": "daily",
    "frozen_fields": ["name", "sector", "industry", "asset_type", "exchange"]
  },
  "results": [
    { "ticker": "SMCI", "name": "Super Micro Computer, Inc.", "asset_type": "CS", "price":  37.42, "day_change_pct": 0.187, "gap_pct": 0.094, "relative_volume": 5.2, "market_cap": 1980000000 },
    { "ticker": "SOUN", "name": "SoundHound AI, Inc.",        "asset_type": "CS", "price":   4.81, "day_change_pct": 0.142, "gap_pct": 0.061, "relative_volume": 4.8, "market_cap":  840000000 },
    { "ticker": "BBAI", "name": "BigBear.ai Holdings",         "asset_type": "CS", "price":   6.12, "day_change_pct": 0.118, "gap_pct": 0.054, "relative_volume": 3.2, "market_cap":  890000000 }
  ]
}
```

### Replay a fundamental scan against a past quarter

Request:

```shell
curl "https://api.tickerbot.io/v2/scan?q=above_sma_50%20AND%20pe_ratio%20%3C%2025%20AND%20market_cap%20%3E%2010000000000&asof=2024-03-29&fields=pe_ratio" \
  -H "Authorization: Bearer YOUR_KEY"
```

Response (`200`):

```json
{
  "as_of": "2024-03-29",
  "query": { "q": "above_sma_50 AND pe_ratio < 25 AND market_cap > 10000000000", "asof": "2024-03-29", "limit": 50, "fields": ["pe_ratio"], "universe": null },
  "count": 18,
  "next_cursor": null,
  "_meta": { "resolution": "daily", "frozen_fields": ["name", "sector", "industry", "asset_type", "exchange"] },
  "results": [
    { "ticker": "JPM", "name": "JPMorgan Chase",      "asset_type": "CS", "price": 199.52, "day_change_pct": 0.012, "gap_pct": 0.002, "relative_volume": 1.05, "market_cap": 575000000000, "pe_ratio": 12.1 },
    "(...)"
  ]
}
```

## Notes

- Static fields aren't historized — `name`, `sector`, `industry`, `asset_type`, and `exchange` reflect their *current* values. `_meta.frozen_fields` lists exactly which ones.
- For per-ticker time series across many bars (rather than a single point-in-time snapshot), use [Signal history](/docs/endpoints/signals/history) or [Ticker as-of date](/docs/endpoints/tickers/history).
- All paid plans get full asof history. Missing daily state for the requested date returns an empty `results` array with the echoed `asof`.

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/scan/asof