> ## 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.

# GET /v1/events — list evaluation events

> Retrieve a paginated list of evaluation events for your organization. Filter by agent, gate verdict, or time range to find exactly the events you need.

`GET /v1/events` returns a paginated list of evaluation events scoped to your organization. Each event records the gate results, latency, overall verdict, and reputation score at the time of evaluation. Events are returned in reverse chronological order — newest first.

Results are always isolated to your organization. There is no way to retrieve events from another organization, even with a valid key.

## Endpoint

```
GET https://api.pecta.ai/v1/events
```

## Authentication

Required. Pass your API key as a Bearer token:

```
Authorization: Bearer pk_live_<your-key>
```

## Query parameters

<ParamField query="limit" type="number" default="50">
  Maximum number of events to return. Minimum `1`, maximum `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of events to skip before returning results. Use with `limit` to paginate. Maximum `100000`.
</ParamField>

<ParamField query="agent_id" type="string">
  Filter to events for a specific agent. Must match exactly. Maximum 200 characters.
</ParamField>

<ParamField query="passed" type="string">
  Filter by gate verdict. Accepts the string `"true"` or `"false"`. Omit to return events regardless of verdict.
</ParamField>

<ParamField query="from" type="string">
  Return events on or after this timestamp. ISO 8601 UTC format, e.g. `2026-05-01T00:00:00Z`.
</ParamField>

<ParamField query="to" type="string">
  Return events on or before this timestamp. ISO 8601 UTC format, e.g. `2026-05-07T23:59:59Z`.
</ParamField>

## Response fields

<ResponseField name="events" type="array">
  Array of event objects, ordered newest first.

  <Expandable title="Event fields">
    <ResponseField name="events[].id" type="string">
      Unique event ID.
    </ResponseField>

    <ResponseField name="events[].agent_id" type="string">
      The agent that produced the evaluated output.
    </ResponseField>

    <ResponseField name="events[].tool_name" type="string">
      Tool or function name, if provided at evaluation time.
    </ResponseField>

    <ResponseField name="events[].passed" type="boolean">
      Overall gate verdict for this evaluation.
    </ResponseField>

    <ResponseField name="events[].gates" type="array">
      Per-gate results at the time of evaluation.
    </ResponseField>

    <ResponseField name="events[].total_latency_ms" type="number">
      Total gate evaluation time in milliseconds.
    </ResponseField>

    <ResponseField name="events[].reputation_score" type="number">
      The agent's reputation score immediately after this evaluation.
    </ResponseField>

    <ResponseField name="events[].created_at" type="string">
      ISO 8601 UTC timestamp of the evaluation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="limit" type="number">
  The `limit` value applied to this request.
</ResponseField>

<ResponseField name="offset" type="number">
  The `offset` value applied to this request.
</ResponseField>

<ResponseField name="count" type="number">
  Number of events returned in this response. Less than or equal to `limit`. Use `count < limit` to detect the last page.
</ResponseField>

## Example request

```bash theme={null}
curl --get \
  --url "https://api.pecta.ai/v1/events" \
  --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "agent_id=summarizer-v2" \
  --data-urlencode "passed=false" \
  --data-urlencode "from=2026-05-01T00:00:00Z" \
  --data-urlencode "limit=10"
```

## Example response

```json theme={null}
{
  "events": [
    {
      "id": "evt_4nRpK2mWxZa",
      "agent_id": "summarizer-v2",
      "tool_name": "generate_summary",
      "passed": false,
      "gates": [
        { "name": "filesystem", "passed": true,  "latency_ms": 2 },
        { "name": "pii",        "passed": false, "latency_ms": 5,
          "reason": "output contains email address" },
        { "name": "content",    "passed": true,  "latency_ms": 3 }
      ],
      "total_latency_ms": 10,
      "reputation_score": 584,
      "created_at": "2026-05-06T11:32:44.000Z"
    },
    {
      "id": "evt_9cLqT7vNbYs",
      "agent_id": "summarizer-v2",
      "tool_name": "generate_summary",
      "passed": false,
      "gates": [
        { "name": "filesystem", "passed": true,  "latency_ms": 2 },
        { "name": "pii",        "passed": true,  "latency_ms": 3 },
        { "name": "content",    "passed": false, "latency_ms": 6,
          "reason": "response appears empty" }
      ],
      "total_latency_ms": 11,
      "reputation_score": 571,
      "created_at": "2026-05-03T08:17:02.000Z"
    }
  ],
  "limit": 10,
  "offset": 0,
  "count": 2
}
```