> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Read identification history

> List a domain, then read identifications and one visitor, device, user, or IP.

History reads the domain that owns your Private API Key. Call [Domain](https://docs.shieldlabs.ai/api/history-domain.md) first and use the returned `id` as `{domain_id}`. That value is a UUID, not the hostname. The literal `all` returns `403`. [Search](https://docs.shieldlabs.ai/api/history-search.md) lists identifications or users. [Card](https://docs.shieldlabs.ai/api/history-card.md) reads one record.

```bash theme={null}
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
  -H "Authorization: Bearer $SHIELDLABS_API_KEY"
```

```json theme={null}
{
  "data": {
    "type": "identification",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "risk": {
      "state": "ok",
      "band": "suspicious",
      "score": 30
    },
    "signals": {
      "state": "ok",
      "items": ["vpn"]
    }
  }
}
```

## Methods

| Method | Path | Purpose |
| - | - | - |
| `GET` | [`/api/v1/domains`](https://docs.shieldlabs.ai/api/history-domain) | `{ "domains": [{ "id", "domain" }] }`. A site key returns one row. |
| `GET` | [`/api/v1/domains/{domain_id}/history/{resource}`](https://docs.shieldlabs.ai/api/history-search) | List. `{resource}` is `identifications` or `user`. |
| `GET` | [`/api/v1/domains/{domain_id}/history/{resource}/{resource_id}`](https://docs.shieldlabs.ai/api/history-card) | One record. `{resource}` is `identifications`, `user`, `visitor`, `device`, or `ip`. |

A list of `visitor`, `device`, or `ip` returns `403`. Read those one record at a time.

## Authentication

**Authorization** `string` *required*

`Bearer PRIVATE_API_KEY`. Use the domain's Private API Key, not its browser Public Key or Management Secret Key.

A missing identification returns `404`. For a new Identification ID, use a bounded retry or an SDK retrieval helper. Bind the result to the expected domain, account and protected action before using it.

## Path parameters

**domain\_id** `string` *required*

Public domain id from `GET /api/v1/domains`.

**resource** `string` *required*

`identifications` or `user` for a list. `identifications`, `user`, `visitor`, `device`, or `ip` for one record.

**resource\_id** `string` *required*

The record id. Required on the one-record path. URL-encode it once. An IP is IPv4.

A hostname, `all`, an empty id, `.` or `..`, a slash, a backslash, or a control character is rejected.

## Query parameters

**from** `string`

Window start, RFC 3339. Send `from` and `to` together, or omit both. A list defaults to the last 24 hours.

**to** `string`

Window end, RFC 3339.

**snapshot** `string`

Value of the `History-Snapshot` response header. Sending it continues the same read.

**limit** `integer` (default: 20)

List page size, from 1 to 100.

**page\_token** `string`

Continuation from `next_page_token`.

**risk\_bands** `string`

Repeat for `trusted`, `suspicious`, or `dangerous`.

**ids** `string`

One user id. Only on the `user` list. A second value is rejected.

**is\_vpn** `boolean`

`true` or `false`. The same form applies to the other published `is_*` flags, `network_check_incomplete`, `check_incomplete`, `ip_mismatch`, `latency_test`, `device_spoofing`, `banned_ip`, `ai_bot`, and `ai_browser`. Several flags combine with AND.

**risk\_signals** `string`

Repeat a public signal code, such as `vpn`. Several codes combine with OR.

**source** `string`

Traffic source. Repeat with `campaign`. At most 8 values together, matched if any value matches. `_empty` means no referrer.

**campaign** `string`

Campaign name. `No campaign` matches visits with no campaign.

**hre\_min\_accounts** `integer` (default: 3)

Minimum linked accounts for a high-risk event, from 3 to 99.

**hre\_min\_devices** `integer` (default: 4)

Minimum linked devices for a high-risk event, from 4 to 99.

**device\_id\_source** `string`

Only on a device record: `legacy` or `fp21_record`.

A nested `filter`, `chips`, or `offset` returns `400`.

## Response

A list returns `{ "data": [ ... ], "next_page_token": null }`. One record returns `{ "data": { ... } }`. Successful responses also send `History-Snapshot`, `History-Snapshot-Expires-At`, `History-Window-From`, and `History-Window-To`.

**data** `object | object[]` *required*

One card, or the cards for this page. See [History card](https://docs.shieldlabs.ai/api/models.md#history-card).

**next\_page\_token** `string`

Present on a list. `null` means there is no next page.

History and webhooks have different field names:

| History card | Scored webhook `data` |
| - | - |
| `id` when `type` is `identification` | `identification_id` |
| `risk.score` when `risk.state` is `ok` | `risk_score` |
| `risk.band` | Trusted, Suspicious or Dangerous label for that score |
| `signals.items` | Signal names in `signals`. The webhook also includes each contribution. |

## Pagination

List one user's identifications and follow `next_page_token`:

```js theme={null}
async function readAccountHistory(domainId, userHid, maxRows = 500) {
  const rows = [];
  let pageToken = '';
  while (rows.length < maxRows) {
    const url = new URL(
      `/api/v1/domains/${domainId}/history/user`,
      'https://account.shieldlabs.ai',
    );
    url.searchParams.append('ids', userHid);
    url.searchParams.set('limit', String(Math.min(100, maxRows - rows.length)));
    if (pageToken) url.searchParams.set('page_token', pageToken);
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.SHIELDLABS_API_KEY}` },
    });
    if (!response.ok) throw new Error(`History API ${response.status}`);
    const page = await response.json();
    rows.push(...page.data);
    pageToken = page.next_page_token || '';
    if (!pageToken || page.data.length === 0) break;
  }
  return { rows, truncated: Boolean(pageToken) };
}
```

History reads do not consume identification quota. The History endpoint allows 15 requests per second per domain; back off on `429`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_query` / `invalid_domain_scope` / `invalid_id` | Bad parameter, hostname, or id |
| `401` | auth message | Missing or invalid Private API Key |
| `403` | `domain_scope_not_supported` / `entity_list_disabled` | `all`, or a list of visitor, device, or IP |
| `404` | `not_found` / `unknown_domain` | No such record or domain |
| `429` | rate limit | Domain request limit reached |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.