Capture API (v1)
Contents
Capture v1 is the new way to send events to PostHog. The legacy capture endpoints still work and stay supported. We plan to retire them in the future and will announce a date well in advance.
If you use a PostHog SDK, you don't need to call these endpoints yourself. Upgrade to an SDK version that uses capture v1 – see upgrading to capture v1 SDKs.
Capture v1 has two endpoints: one for analytics events and one for AI events. Both take a batch of events and tell you what happened to each event in the batch, so one bad event never costs you the rest.
| Legacy capture | Capture v1 | |
|---|---|---|
| Endpoints | /i/v0/e, /batch, and others | /i/v1/analytics/events, /i/v1/ai/events |
| Project token | In the body (api_key) | Authorization: Bearer header |
| Response | 200 for the whole request | Per-event results, plus clear status codes |
uuid, timestamp, distinct_id | Optional or inferred | Required on every event |
| Person processing and other settings | Legacy option properties ($-prefixed properties) | An options object on each event |
| Compression | gzip-js, lz64, base64, and others | gzip, deflate, br, zstd with Content-Encoding |
Endpoints
| Endpoint | Send |
|---|---|
POST <ph_client_api_host>/i/v1/analytics/events | All events except AI events |
POST <ph_client_api_host>/i/v1/ai/events | AI events only – events whose name starts with $ai_, like $ai_generation |
Use https://us.i.posthog.com for US Cloud and https://eu.i.posthog.com for EU Cloud. Both endpoints accept POST only.
Self-hosted (hobby) instances serve both endpoints from PostHog commit 1d6f4d0 (October 21, 2026) onward. Upgrade your instance before you move an SDK to capture v1. An older instance doesn't serve one or both endpoints. Server SDKs on capture v1 drop events that still get a 404 after their retries. The iOS, Android, and Flutter SDKs keep them queued until the path is served or their queue fills.
Send each event to its own endpoint
PostHog owns the $ai_ event name prefix. Don't use it for your own events.
- Send
$ai_events to/i/v1/ai/events. In an SDK, use its AI capture method, such ascapture_ai. - Send every other event to
/i/v1/analytics/events.
The AI endpoint drops any event that isn't an AI event, with the result detail misrouted_event. For now, the analytics endpoint still accepts AI events, so existing setups keep working while you move to v1. This is temporary, and we'll remove it in a future release. Large AI events always need the AI endpoint – see capturing large AI events.
Headers
Every request needs these headers. A missing or malformed header rejects the whole request.
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <ph_project_token> – your project token. A personal API key (phx_…) is refused. |
Content-Type | Yes | application/json |
User-Agent | Yes | Any value that identifies your client |
PostHog-Sdk-Info | Yes | <library>/<version>, for example my-backend/1.2.0. PostHog uses it to fill in $lib and $lib_version on events that don't set them. See library name and version. |
PostHog-Request-Id | Yes | A UUID for this request. Send the same ID on every retry of the request. PostHog returns it in a response header of the same name. |
PostHog-Attempt | Yes | The attempt number: 1 for the first try, 2 for the first retry, and so on |
PostHog-Request-Timestamp | Yes | The time you send this attempt, in RFC 3339 format. Set it again on every retry. PostHog uses it to correct for a wrong client clock. |
Content-Encoding | No | gzip, deflate, br, or zstd when the body is compressed |
Header values must be plain, visible ASCII characters.
Request body
| Field | Required | Description |
|---|---|---|
created_at | Yes | When you built this batch, in RFC 3339 format |
historical_migration | No | true to send the batch as a historical migration. It applies to every event in the request, so send historical and live events in separate requests. |
batch | Yes | The events. It can't be empty. |
Each event in batch:
| Field | Required | Description |
|---|---|---|
event | Yes | The event name, up to 200 bytes. See limits. |
uuid | Yes | A unique ID for this event. Use a UUIDv7. See event UUIDs. |
distinct_id | Yes | Who did it, up to 200 bytes. See choosing a distinct ID. |
timestamp | Yes | When the event happened, in RFC 3339 format with at least millisecond precision, like 2026-10-19T12:00:00.000Z. You can send more precise values. |
session_id | No | The session ID, as a string. Same as the $session_id property. |
window_id | No | The window ID, as a string. Same as the $window_id property. |
options | No | Settings for how PostHog processes this event. See event options. |
properties | No | The event's properties. Must be a JSON object. |
The capture spec in the SDK specs describes the full wire contract that PostHog SDKs follow.
Library name and version
Each event's $lib and $lib_version properties name the library that produced it. PostHog stores the values the event sends.
If an event's $lib is missing, empty, or not a string, PostHog sets both properties from the PostHog-Sdk-Info header. If $lib matches the library in the header and $lib_version is missing, empty, or not a string, PostHog fills in $lib_version from the header. If $lib names a different library, PostHog stores both properties as sent, even if $lib_version is missing, so set both when you override them.
If the PostHog-Sdk-Info value doesn't match <library>/<version> or is longer than 200 bytes, PostHog still accepts the request, but events without $lib are stored without it.
Event UUIDs
Every event needs its own uuid. Generate a new one for each event, and keep it the same when you retry that event. A UUIDv7 works best because it also records when you created the event.
Don't reuse a UUID from something else, like an order ID or a request ID, across events. If a request contains the same UUID more than once, PostHog keeps the first event with that UUID and drops the rest. That UUID's result counts the dropped copies in duplicates_dropped. On PostHog Cloud, PostHog also raises a duplicate_event_uuid ingestion warning in your project.
Choosing a distinct ID
A distinct ID connects events to one person. Use either:
- An ID for one visitor or device, such as an anonymous ID your client generates and stores, or
- Your own stable ID for a known user, such as their ID in your database.
Keep each distinct ID under 200 bytes. Capture v1 drops events with longer IDs, where legacy capture shortened them.
Don't use one value for many people or machines, such as a server name or a placeholder like anonymous, guest, system, or null. PostHog accepts events with common placeholder values like these but processes them without a person profile, and returns the result ok with the detail person_processing_disabled. A distinct ID that sends far more events than one person could is also rate limited. See identifying users for more.
Event options
Options control how PostHog processes an event. They replace the legacy option properties: the $-prefixed properties legacy capture reads as settings from properties.
| Option | Type | What it does | Replaces |
|---|---|---|---|
process_person_profile | Boolean | false sends an anonymous event that doesn't create or update a person profile | $process_person_profile |
cookieless_mode | Boolean | true processes the event with cookieless tracking | $cookieless_mode |
disable_skew_correction | Boolean | true keeps your timestamp as sent instead of correcting for clock skew, unless it's more than 23 hours in the future | $ignore_sent_at |
product_tour_id | String | Links the event to a product tour. You rarely need it | $product_tour_id |
- Booleans also accept common forms like
"true","false",1, and0.nullmeans "not set". product_tour_idalso accepts a whole number. An empty string means "not set".- PostHog ignores option names it doesn't know.
- An option value PostHog can't read drops the event with the detail
invalid_options.
Legacy option properties
Set these settings in options. The $process_person_profile and $cookieless_mode legacy option properties still work, but an option overrides its legacy property. Capture v1 doesn't read $ignore_sent_at or $product_tour_id from properties. Use options; legacy properties may not be supported in future major versions.
PostHog stores each option as its $-prefixed property, such as $process_person_profile, so your insights and filters keep working.
Compression
Compress the body and set Content-Encoding to one of gzip, deflate, br, or zstd. An uncompressed body needs no Content-Encoding. Don't send Content-Encoding: identity: it fails with 415.
Legacy formats such as gzip-js, lz64, and base64 aren't accepted on v1: a Content-Encoding value other than the four above fails with 415, and a body in one of those formats isn't valid JSON, so the request fails with 400. The ?compression= query parameter is ignored.
SDKs support different sets of these formats. Check your SDK's migration guide for which ones it offers.
Limits and validation
Capture v1 checks every request and every event as it arrives. A problem with the request rejects the whole request. A problem with one event drops only that event and returns its result detail.
Field types
Every field below must have the JSON type shown. A required field that's missing or null, or a field with the wrong type, such as a number where a string belongs, rejects the whole request with 400 request_parsing_error, and nothing in it is stored. Send IDs as strings, even when they're numbers: JSON numbers can lose precision.
The response's error_description names the field and what's wrong with it, for example Failed to parse request body: batch[3].distinct_id must be a string, got number. or Failed to parse request body: batch[0].event is missing. If the body isn't valid JSON, it gives the line and column instead. A parse error's description never repeats the data you sent.
| Field | Type |
|---|---|
batch | Array of event objects |
created_at | String (RFC 3339) |
event | String |
uuid | String (UUID) |
distinct_id | String |
timestamp | String (RFC 3339) |
session_id, window_id | String, optional |
properties and options are checked per event: a value that isn't an object drops only that event, with the detail malformed_event_properties or invalid_options. "options": null counts as no options. An unreadable historical_migration counts as false.
PostHog SDKs always send these types. If you change an event in a before_send hook, keep these types.
Request limits
| Limit | Rule | If you exceed it |
|---|---|---|
| Request body | Not empty | 400 empty_body |
| Request body, as sent | 10MB on the analytics endpoint, 20MB on the AI endpoint | 413, nothing stored |
| Request body, after decompression | 50MB on the analytics endpoint, 100MB on the AI endpoint | 413, nothing stored |
| Events per request | No limit beyond the body size | – |
batch | At least one event | 400 empty_batch |
uuid | Present, not empty, and a valid UUID | 400, nothing stored: request_parsing_error if missing or null, missing_event_uuid if empty, invalid_event_uuid if not a UUID |
uuid repeated in one request | Each UUID once | The first event is kept, later copies are dropped and counted in duplicates_dropped |
created_at | Present, RFC 3339 | 400, nothing stored: request_parsing_error if missing or null, invalid_batch if not RFC 3339 |
| Required headers | All present (headers) | 400 missing_required_headers; 401 missing_authorization for Authorization |
Authorization | Bearer <ph_project_token> | 400 invalid_header_value without Bearer; 401 invalid_api_token for a malformed token or a personal API key |
PostHog-Request-Id, PostHog-Attempt, PostHog-Request-Timestamp | A UUID, a whole number from 1, and an RFC 3339 time | 400 invalid_header_value |
Content-Type | application/json | 415 unsupported_content_type |
Content-Encoding | None, or gzip, deflate, br, or zstd (not identity) | 415 unsupported_encoding |
| Header values | Visible ASCII characters only | 400 invalid_header_value |
| Field types | See field types | 400 request_parsing_error, nothing stored |
PostHog-Sdk-Info | <library>/<version>, with a /, up to 200 bytes | Request accepted, but PostHog doesn't fill in $lib and $lib_version from the header. Values in properties are kept. See library name and version. |
Event limits
| Field | Rule | If an event breaks it |
|---|---|---|
event | Not empty, up to 200 bytes | drop (missing_event_name, event_name_too_long) |
distinct_id | Not empty after trimming spaces, up to 200 bytes | drop (missing_distinct_id, distinct_id_too_large) |
timestamp | RFC 3339 | drop (invalid_event_timestamp) |
properties | A JSON object | drop (malformed_event_properties) |
options | A JSON object with readable values | drop (invalid_options) |
| The whole event | Small enough to store, about 1MB | drop (event_too_big). See the 1MB event limit. |
Limits count bytes in UTF-8, not characters. A 100-character distinct ID with non-English characters can be more than 200 bytes.
Some of these rules are stricter than legacy capture:
- Long distinct IDs. Legacy capture shortens a distinct ID over 200 characters and stores the event. Capture v1 drops the event with
distinct_id_too_large. Check that your IDs stay under 200 bytes before you upgrade. - Long event names. Legacy capture has no limit on event name length. Capture v1 drops an event whose name is over 200 bytes with
event_name_too_long. Check your event names before you upgrade. - Distinct ID type. Legacy capture turns a non-string distinct ID, such as a number, into text. Capture v1 rejects the whole request with
400request_parsing_error. PostHog SDKs always send strings. - Event UUIDs. Every event needs a valid UUID of its own. See event UUIDs.
On PostHog Cloud, the AI endpoint accepts AI events up to 8MB each. See capturing large AI events.
The request body limits above are for PostHog Cloud. On a self-hosted instance, both endpoints accept up to 10MB as sent and 50MB after decompression, and AI events are limited to about 900KB each.
Responses
Status codes
| Status | Meaning | Retry? |
|---|---|---|
200 | PostHog read the batch. Check the result for each event. | Only events with result retry |
400 | The whole request is invalid, for example a missing header, bad JSON, an empty batch, or an invalid uuid. Nothing was stored. | No – fix the request |
401 | The project token is missing or malformed, or you used a personal API key. A well-formed token that doesn't match a project still gets 200, with ok for every event, but nothing is stored. | No |
402 | Your project hit a billing limit, so nothing in this request is stored. The response has no per-event results. If only some events in a request are over a product's quota, you get 200 instead, and only those events are dropped. | No – raise or remove the limit |
404 | Nothing serves this path, for example a self-hosted instance that predates capture v1 or a proxy that doesn't forward it | Yes. If it keeps failing, check the host, your proxy, and your instance version. |
408 | The request timed out while PostHog read it | Yes |
413 | The body is over the size limit | No – send smaller requests |
415 | Unsupported Content-Type or Content-Encoding | No |
429 | Too many requests from one source. PostHog's network edge, in front of capture, can send this when a single client sends an unusually high request rate. It's rare. | Yes, after at least the Retry-After time if the response has one. Send fewer, larger requests. |
500, 502, 503, 504 | A temporary problem | Yes |
Errors from capture use this body. error is a stable tag you can match on. A response from a proxy or from PostHog's network edge in front of capture, such as some 404, 405, 413, or 429 responses, may not be JSON, so check the status code first.
Per-event results
A 200 response always has a results object, with one result for every event, keyed by the event's uuid. PostHog SDKs treat a 2xx response without a results object as a failed request and don't resend it.
PostHog writes each key as a lowercase UUID with hyphens, whatever form you sent it in. Compare UUIDs in that form when you match results to your events.
duplicates_dropped appears only when the request repeated that event's UUID. It's the number of later copies PostHog dropped. The result and details belong to the first copy, which PostHog kept. Two UUIDs that differ only in letter case or format count as the same UUID.
| Result | Meaning | What to do |
|---|---|---|
ok | Stored, if your token matches a project (see 401) | Nothing |
warning | Stored, with a change you should know about, named in details | Don't resend. Fix the cause. |
drop | Not stored | Don't resend. Fix the cause named in details. |
retry | Not stored because of a temporary problem | Resend this event (and only this one) |
Result details
details tells you why an event got its result. Common values:
| Detail | Result | Meaning |
|---|---|---|
missing_event_name | drop | event is empty |
event_name_too_long | drop | event is over 200 bytes |
missing_distinct_id | drop | distinct_id is empty |
distinct_id_too_large | drop | distinct_id is over 200 bytes |
invalid_event_timestamp | drop | timestamp isn't RFC 3339 |
malformed_event_properties | drop | properties isn't a JSON object |
invalid_options | drop | options isn't an object, or an option value can't be read |
event_too_big | drop | The event is too large to store |
misrouted_event | drop | A non-AI event was sent to the AI endpoint |
ai_event_too_big | drop | An AI event is over the size limit for the endpoint it was sent to |
person_processing_disabled | ok or warning | Stored without a person profile. The result is ok when the distinct ID is a placeholder like anonymous, and warning when PostHog's rate limiter turned person processing off |
not_persisted | retry | PostHog couldn't store it right now |
When an event is over a product's quota, the result is drop and details names the quota that was exceeded.
This list isn't complete, and PostHog can add new values. Handle an event by its result, and treat a details value you don't know as a label only.
The capture spec in the SDK specs lists how PostHog SDKs handle each result.
On PostHog Cloud, many drops also raise an ingestion warning in your project, so you can find them later.
Retries
Retry when the response is 404, 408, 429, 500, 502, 503, or 504, when the network fails, and for each event whose result is retry. Treat every other response as final.
When you retry:
- Resend only the events that need it. Events with
ok,warning, ordropare final. - Keep the same
PostHog-Request-Idand each event'suuid. - Increase
PostHog-Attemptby one. - Set a new
PostHog-Request-Timestamp. - Wait before each retry, doubling the wait each time, and add some randomness (jitter) so many clients don't retry at once. If the response has a
Retry-Afterheader, wait at least that long. - Turn off automatic retries in your HTTP library, or make sure each of its retries follows these rules. A library retry that resends the old
PostHog-Request-Timestampmakes PostHog shift your events' timestamps by the time it spent retrying.
PostHog SDKs that use v1 do all of this for you. If you use one, don't wrap its capture calls in your own retry logic.
Timestamps and clock skew
PostHog corrects for a wrong client clock using PostHog-Request-Timestamp. It compares that header with the time it received the request, then moves each event's timestamp by the difference. Set disable_skew_correction to skip this correction and keep your timestamps as sent.
An event whose timestamp, after any correction, is more than 23 hours in the future is stored with the time PostHog received it. This also applies when disable_skew_correction is set. See how PostHog computes timestamps.
Examples
The curl example sends PostHog-Request-Timestamp in whole seconds, so skew correction can move the event's timestamp by up to about a second. With GNU date, use %3N for milliseconds. Real clients should send milliseconds.
A request that PostHog stores returns 200 with a result for each event:





