# Reading events

> Read identification events with a secret key: one event by request ID, or a window of events filtered by visitor or level, for up to 30 days.

Last updated: 2026-09-17

Every identification is stored as an event you can read with a secret key for 30 days. Read one to [verify an identification](https://docs.fingerly.io/docs/server-side-verification), or list a window of them to investigate a visitor, backfill your warehouse or reconcile with webhooks.

## One event

```ts Node.js
import { load } from '@fingerly/node'

const fingerly = load({ secretKey: process.env.FINGERLY_SECRET_KEY! })
const event = await fingerly.events.get('01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4')
```

```python Python
import os
from fingerly import Fingerly

fingerly = Fingerly(secret_key=os.environ["FINGERLY_SECRET_KEY"])
event = fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```python Python (async)
import os
from fingerly import AsyncFingerly

fingerly = AsyncFingerly(secret_key=os.environ["FINGERLY_SECRET_KEY"])
event = await fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```go Go
import fingerly "github.com/fingerly-io/fingerly-go"

client := fingerly.New(os.Getenv("FINGERLY_SECRET_KEY"))
event, err := client.Events.Get(ctx, "01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```java Java
import io.fingerly.server.FingerlyClient;

FingerlyClient fingerly = FingerlyClient.builder()
    .secretKey(System.getenv("FINGERLY_SECRET_KEY"))
    .build();

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

```csharp .NET
using Fingerly;

var fingerly = new FingerlyClient(Environment.GetEnvironmentVariable("FINGERLY_SECRET_KEY"));
var ev = await fingerly.Events.GetAsync("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4");
```

```php PHP
<?php

$fingerly = new \Fingerly\Client(getenv('FINGERLY_SECRET_KEY'));
$event = $fingerly->events->get('01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4');
```

```ruby Ruby
require "fingerly"

fingerly = Fingerly::Client.new(secret_key: ENV.fetch("FINGERLY_SECRET_KEY"))
event = fingerly.events.get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4")
```

```rust Rust
let fingerly = fingerly::Client::new(std::env::var("FINGERLY_SECRET_KEY")?);
let event = fingerly.events().get("01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4").await?;
```

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

A single event also includes the archived submission as `document`, with the threshold and weights profile that scored it, and any deferred report as `deferred_signals`. See [Get an event](https://docs.fingerly.io/reference/get-event).

## A window of events

```ts Node.js
const page = await fingerly.events.list({ level: 'high', limit: 50 })
```

```python Python
page = fingerly.events.list(level="high", limit=50)
```

```python Python (async)
page = await fingerly.events.list(level="high", limit=50)
```

```go Go
page, err := client.Events.List(ctx, &fingerly.EventListParams{Level: "high", Limit: 50})
```

```java Java
EventPage page = fingerly.events().list(EventListParams.builder().level("high").limit(50).build());
```

```csharp .NET
var page = await fingerly.Events.ListAsync(new EventListOptions { Level = "high", Limit = 50 });
```

```php PHP
$page = $fingerly->events->list(['level' => 'high', 'limit' => 50]);
```

```ruby Ruby
page = fingerly.events.list(level: "high", limit: 50)
```

```rust Rust
let page = fingerly.events().list(&ListEvents { level: Some(Level::High), limit: Some(50), ..Default::default() }).await?;
```

```bash cURL
curl "https://us.api.fingerly.io/api/v1/events?level=high&limit=50" \
  -H "x-api-key: $FINGERLY_SECRET_KEY"
```

| Parameter | Default | Notes |
| --- | --- | --- |
| `from`, `to` | The last 24 hours | RFC 3339. At most 30 days wide, starting at most 30 days ago. |
| `page`, `limit` | `1`, `10` | `limit` is at most 200. Pages reach back at most 10,000 events. |
| `visitor` | none | One exact visitor ID. |
| `level` | none | `low`, `medium` or `high`. |

## Everything a visitor did

```ts Node.js
const history = await fingerly.events.list({
  visitor: 'X9pL2mRc7KvT4bQw8NdF',
  from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
  limit: 200,
})
```

```python Python
history = fingerly.events.list(
    visitor="X9pL2mRc7KvT4bQw8NdF",
    from_=datetime.now(timezone.utc) - timedelta(days=30),
    limit=200,
)
```

```python Python (async)
history = await fingerly.events.list(
    visitor="X9pL2mRc7KvT4bQw8NdF",
    from_=datetime.now(timezone.utc) - timedelta(days=30),
    limit=200,
)
```

## Paging through a window

```ts Node.js
async function* allEvents(from: Date, to: Date) {
  for (let page = 1; ; page++) {
    const result = await fingerly.events.list({ from, to, page, limit: 200 })
    yield* result.rows
    if (result.rows.length < result.page_size) return
  }
}
```

```python Python (async)
async def all_events(from_: datetime, to: datetime):
    page = 1
    while True:
        result = await fingerly.events.list(from_=from_, to=to, page=page, limit=200)
        for event in result.rows:
            yield event
        if len(result.rows) < result.page_size:
            return
        page += 1
```

> **Tip:** A page reaches back at most 10,000 events. To export more, split the window into smaller windows, or keep your own copy with the `identification.completed` [webhook](https://docs.fingerly.io/docs/webhooks).

## Triggers in events

Events group their triggers by [signal group](https://docs.fingerly.io/docs/signals): a trigger's `signal` is the group, such as `vpn`, and its `weight` is what the group added. The identify response and the `visitor.suspect` webhook list the individual signals.

> **Note:** Each secret key reads only its own environment. Reads are free and do not count against your rate limit.