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

# Browse agent evaluation events in real time

> Browse every agent evaluation result with filters by agent ID and outcome. Page through the full log or narrow to failures in seconds.

The Events page (`/events`) is the raw log of every evaluation Pecta has processed for your organisation. It shows results newest first, 100 rows at a time. Navigate to **Events** in the sidebar to open it. You can filter the feed without leaving the page — results update immediately as you type or change the outcome selector.

## What each event shows

Each row in the `EventFeed` component displays the following fields from the `EventRow` type:

| Field          | Description                                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Timestamp**  | `created_at` in UTC, shown to the second (`YYYY-MM-DD HH:MM:SS`)                                                                          |
| **Agent**      | `agent_id` — the identifier your SDK or proxy reported                                                                                    |
| **Outcome**    | `PASS` (emerald) or `BLOCK` (red), derived from the boolean `passed` field                                                                |
| **Gate chips** | One chip per gate in the `gates` array — green for pass, red for fail, grey for skipped. Hover a chip to read the gate's `reason` string. |
| **Latency**    | `total_latency_ms` in milliseconds, right-aligned, showing the cumulative time across all gates                                           |

<Info>
  The `tool_name` field is stored on every event but is not displayed as a separate column in the current feed layout. It is available when you query `GET /v1/events` directly.
</Info>

The `reputation_score` at the time of the evaluation is stored on each event record and is available via the API, but the Events page focuses on gate-level detail rather than score history.

## Filters

Two filters sit above the event feed. Both reset the page offset to 0 when changed.

### Filter by agent

Type any `agent_id` into the **Filter by agent\_id** text input. The dashboard passes your input as the `agent_id` query parameter to `GET /v1/events`. The match is exact — use the full agent ID as registered.

### Filter by outcome

Use the **All / Passed / Failed** dropdown to restrict results to a specific outcome. Selecting **Passed** sets `passed=true` on the API request; selecting **Failed** sets `passed=false`. **All** omits the parameter entirely.

<Tip>
  Combine both filters to isolate failures from a specific agent. Set the outcome to **Failed** and type the agent ID to see exactly which gates that agent is tripping and when.
</Tip>

## Pagination

The feed loads 100 events per page. Use the **← Newer** and **Older →** buttons at the bottom of the page to move through the full history. The current position is shown as `Showing N–M` between the two buttons.

* **← Newer** is disabled when you are on the first page (offset 0).
* **Older →** is disabled when the current page returns fewer than 100 rows, indicating the end of the result set.

## API connection

The Events page reads from the same endpoint you can query directly:

```http theme={null}
GET /v1/events
Authorization: Bearer <pk_live_…>
```

Supported query parameters:

```
limit    integer   Max rows to return (default 50, max 100)
offset   integer   Skip this many rows (for pagination)
agent_id string    Filter to a single agent
passed   boolean   Filter by pass/fail outcome
from     string    ISO 8601 lower bound on created_at
to       string    ISO 8601 upper bound on created_at
```

Example — fetch the last 100 failed events for a specific agent:

```bash theme={null}
curl "https://api.pecta.ai/v1/events?limit=100&agent_id=my-bidder-v2&passed=false" \
  -H "Authorization: Bearer pk_live_…"
```

The response shape matches the `EventsPage` interface used by the dashboard:

```json theme={null}
{
  "events": [
    {
      "id": "ev_abc123",
      "agent_id": "my-bidder-v2",
      "tool_name": "place_bid",
      "passed": false,
      "gates": [
        { "name": "bid_sanity", "passed": false, "reason": "ratio 52x exceeds max 50x", "latency_ms": 1.2 },
        { "name": "impid_match", "passed": true, "latency_ms": 0.4 }
      ],
      "total_latency_ms": 3.8,
      "reputation_score": 712,
      "created_at": "2025-11-14T09:22:01.000Z"
    }
  ],
  "limit": 100,
  "offset": 0,
  "count": 1
}
```

<Note>
  Queries that span long time periods may be slower. Use the `from` and `to` parameters to constrain large historical queries for best performance.
</Note>