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

# Read recent events

> Pull your organization's events from the last 30 days into your own systems

`POST /v1/events` returns your organization's events from the last 30 days, oldest first. Use it to copy events into your own systems, to catch up after downtime, or to poll on a schedule.

Call it from your server with your `org_` API key. A partner admin session token also works (see [Admin session tokens](https://docs.fourdos.dev/authentication.md#admin-session-tokens)).

```bash theme={null}
export API_BASE_URL="https://api.develop.fourdos.dev"
export API_KEY="org_…"
```

## 1. Request events

```bash theme={null}
curl -X POST "$API_BASE_URL/v1/events?since=2026-11-10T00:00:00Z&types=identity.*,xp.redeemed" \
  -H "Authorization: Bearer $API_KEY"
```

The filters go in the query string; the request has no body.

| Query parameter | Status | Notes |
| - | - | - |
| `since` | Optional | ISO 8601 UTC datetime, for example `2026-11-10T00:00:00Z`. Returns events at or after this time. Defaults to 30 days ago; an earlier value is moved up to 30 days ago. |
| `types` | Optional | Comma-separated event types. `xp.redeemed` matches that type exactly; `identity.*` matches every type that starts with `identity.`. Without it, all types are returned. |

Call it once without `types` to see which event types your organization produces and how each is spelled.

## 2. Read the response

`200 OK`, an array of events:

```json theme={null}
[
  {
    "id": "…",
    "event_id": "…",
    "event_type": "xp.redeemed",
    "event_version": 1,
    "org_id": "…",
    "occurred_at": "2026-11-10T14:03:11.000Z",
    "payload": {
      "spec_version": "1.0",
      "actor": { "type": "service" },
      "data": {
        "user_id": "…",
        "org_id": "…",
        "reward_id": "…",
        "redemption_id": "…",
        "amount": "500"
      }
    }
  }
]
```

| Field | Notes |
| - | - |
| `event_id` | The event's id. Use it to deduplicate. |
| `event_type` | Dotted type name, for example `identity.user.created` |
| `event_version` | Version of that type's payload |
| `org_id` | Your organization |
| `occurred_at` | When the event happened. Events are ordered by this field, oldest first. |
| `payload.data` | The type-specific fields |
| `payload.actor` | Who caused the event, with a `type` and usually an `id`. Can be `null`. |

Only your own organization's events are returned.

## 3. Page through more than 1,000 events

One call returns at most 1,000 events, and there is no cursor. When you get 1,000 back, call again with `since` set to the last event's `occurred_at`. Events at that exact time come back again, so drop any `event_id` you already have.

Events older than 30 days are gone from this call. If you need a longer history, store what you read.

## Errors

| Status | Code | When |
| - | - | - |
| `401` | `UNAUTHORIZED` | No valid credential |
| `403` | `FORBIDDEN` | The credential has no organization, for example a platform admin session with no active organization |
| `422` | `VALIDATION_ERROR` | `since` is not an ISO 8601 UTC datetime |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.