# List events

> List identification events in a time window, newest first, filtered by visitor or suspect level.

Last updated: 2026-09-17

```http
GET /api/v1/events
```

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

Returns events from the secret key's own organization and environment, newest first. The window can reach back 30 days.

**Query parameters**

- `from` (string, default `24 hours ago`): Start of the window, inclusive, RFC 3339.
- `to` (string, default `now`): End of the window, exclusive, RFC 3339.
- `page` (integer, default `1`): One-based page number. The offset may not exceed 10,000 events.
- `limit` (integer, default `10`): Events per page, at most 200.
- `visitor` (string): Only events for this exact visitor ID.
- `level` (string): Only events at `low`, `medium` or `high`.

`from` must be before `to`, the window may span at most 30 days, and it may not start more than 30 days ago. Otherwise the request fails with `422 invalid_window`.

## Response

- `rows` (array): The events on this page. Each has the [event fields](https://docs.fingerly.io/reference/get-event#response).
- `page` (integer): This page's number.
- `page_size` (integer): The page size applied.

There is no total count. A page with fewer rows than `page_size` is the last one.

## Errors

| Status | Code | When |
| --- | --- | --- |
| `401` | `unauthorized` | The key is not a valid secret key. |
| `422` | `invalid_window` | The window, page offset, level or visitor filter is not valid. |
| `422` | `validation_error` | A parameter has the wrong type. |

> **Note:** The server API does not answer browsers: a secret key sent with an `Origin` header is refused. Call it from your backend.

## Example request

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

```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?;
```

## Example response

```json 200
{
  "rows": [
    {
      "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
    }
  ],
  "page": 1,
  "page_size": 50
}
```

```json 422
{
  "error": {
    "code": "invalid_window",
    "message": "the event window must be positive and within retention",
    "status": 422
  },
  "request_id": "01a0a84c-0f11-7a3e-9c2d-4b5e6f708192"
}
```