# Get an event

> Read one identification event by its request ID with a secret key. This is how your server verifies what a client reported.

Last updated: 2026-09-17

```http
GET /api/v1/events/{request_id}
```

Authentication: Secret key (`x-api-key: fly_sk_…`)

Returns the stored event for a request ID, from the secret key's own organization and environment. Use it to [verify an identification](https://docs.fingerly.io/docs/server-side-verification) before you act on it.

**Path parameters**

- `request_id` (string, required): The `request_id` an SDK returned.

## Response

- `request_id` (string): The identification's ID, a UUIDv7.
- `visitor_id` (string): The visitor the device was identified as.
- `occurred_at` (string): When the request arrived, RFC 3339 in UTC.
- `state` (string): `enriched`, or `unavailable` when the network lookup could not run.
- `environment` (string): `production`, `staging` or `development`.
- `platform` (string): The scoring profile applied: `web`, `android` or `ios`.
- `sdk_platform` (string): The SDK that sent the report, such as `web`, `ios` or `flutter-android`.
- `sdk_version` (string): The SDK's version.
- `origin` (string): The site the request came from. Omitted for native apps.
- `tag` (string): Your tag, as sent. Omitted when none was sent.
- `ip_address` (string): The visitor's IP address.
- `country_code` (string): ISO 3166-1 alpha-2 country of the address.
- `country_name` (string): The country's name.
- `asn` (string): The network's autonomous system number.
- `asn_name` (string): The network's name.
- `anonymity_network` (string): `tor`, `vpn`, `proxy` or `hosting`. Omitted for an ordinary connection.
- `agent` (string): The browser or app.
- `agent_version` (string): Its version.
- `os` (string): The operating system.
- `device_kind` (string): `desktop`, `mobile`, `tablet` or `server`.
- `visitor_kind` (string): `human`, `ai_bot`, `automation` or `search_crawler`.
- `suspect_score` (integer | null): The score. `null` when the request was not scored.
- `suspect_level` (string): `low`, `medium` or `high`. Omitted when not scored.
- `triggers` (array): The signal groups that fired, heaviest first. Always present, possibly empty.
  - `signal` (string): The [signal group](https://docs.fingerly.io/docs/signals), such as `vpn` or `bot`.
  - `weight` (integer): The group's combined weight in this score.
  - `confidence` (string): `low`, `medium` or `high`.
- `has_document` (boolean): Whether the archived submission can be read with [Get an event](https://docs.fingerly.io/reference/get-event).

**Archived detail**

- `document` (object): The archived submission as Fingerly stored it, including the scoring details: the threshold and weights profile applied. Present when `has_document` is `true` and the archive could be read.
- `deferred_signals` (object): The deferred report attached to this request, when one arrived.

> **Note:** Events are readable for 30 days. An event normally becomes readable within a few seconds of the identification. Allow for that when a client sends you a request ID immediately.

## Errors

| Status | Code | When |
| --- | --- | --- |
| `401` | `unauthorized` | The key is not a valid secret key. |
| `404` | `event_not_found` | No such event in this environment, or it is older than 30 days. |
| `422` | `invalid_request_id` | The path is not a Fingerly request ID. |

## Example request

```bash cURL
curl "https://us.api.fingerly.io/api/v1/events/01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4" \
  -H "x-api-key: $FINGERLY_SECRET_KEY"
```

```ts Node.js
const event = await fingerly.events.get('01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4')
```

```python Python
event = fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```python Python (async)
event = await fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```go Go
event, err := client.Events.Get(ctx, "01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```java Java
Event event = fingerly.events().get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4");
```

```csharp .NET
var ev = await fingerly.Events.GetAsync("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4");
```

```php PHP
$event = $fingerly->events->get('01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4');
```

```ruby Ruby
event = fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```rust Rust
let event = fingerly.events().get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4").await?;
```

## Example response

```json 200
{
  "request_id": "01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4",
  "visitor_id": "X9pL2mRc7KvT4bQw8NdF",
  "occurred_at": "2026-09-16T09:41:12.482Z",
  "state": "enriched",
  "environment": "production",
  "platform": "web",
  "sdk_platform": "web",
  "sdk_version": "0.1.0",
  "origin": "https://shop.example.com",
  "tag": "checkout:8412",
  "ip_address": "203.0.113.42",
  "country_code": "DE",
  "country_name": "Germany",
  "asn": "AS64502",
  "asn_name": "Example Hosting",
  "anonymity_network": "tor",
  "agent": "Firefox",
  "agent_version": "128.0",
  "os": "Windows",
  "device_kind": "desktop",
  "visitor_kind": "automation",
  "suspect_score": 37,
  "suspect_level": "high",
  "triggers": [
    {
      "signal": "tor",
      "weight": 14,
      "confidence": "high"
    },
    {
      "signal": "bot",
      "weight": 9,
      "confidence": "medium"
    },
    {
      "signal": "browser_tampering",
      "weight": 8,
      "confidence": "medium"
    },
    {
      "signal": "high_activity",
      "weight": 6,
      "confidence": "low"
    }
  ],
  "has_document": true
}
```

```json 404
{
  "error": {
    "code": "event_not_found",
    "message": "no such event",
    "status": 404
  },
  "request_id": "01a0a84c-0f11-7a3e-9c2d-4b5e6f708192"
}
```