Capture API (v1)

Contents

New capture API

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 captureCapture v1
Endpoints/i/v0/e, /batch, and others/i/v1/analytics/events, /i/v1/ai/events
Project tokenIn the body (api_key)Authorization: Bearer header
Response200 for the whole requestPer-event results, plus clear status codes
uuid, timestamp, distinct_idOptional or inferredRequired on every event
Person processing and other settingsLegacy option properties ($-prefixed properties)An options object on each event
Compressiongzip-js, lz64, base64, and othersgzip, deflate, br, zstd with Content-Encoding

Endpoints

EndpointSend
POST <ph_client_api_host>/i/v1/analytics/eventsAll events except AI events
POST <ph_client_api_host>/i/v1/ai/eventsAI 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 as capture_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.

HeaderRequiredValue
AuthorizationYesBearer <ph_project_token> – your project token. A personal API key (phx_…) is refused.
Content-TypeYesapplication/json
User-AgentYesAny value that identifies your client
PostHog-Sdk-InfoYes<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-IdYesA 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-AttemptYesThe attempt number: 1 for the first try, 2 for the first retry, and so on
PostHog-Request-TimestampYesThe 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-EncodingNogzip, deflate, br, or zstd when the body is compressed

Header values must be plain, visible ASCII characters.

Request body

JSON
{
"created_at": "2026-10-19T12:00:00.250Z",
"batch": [
{
"event": "signed_up",
"uuid": "019a0000-0000-7000-8000-000000000001",
"distinct_id": "user_123",
"timestamp": "2026-10-19T12:00:00.123Z",
"session_id": "019a0000-0000-7000-8000-0000000000a1",
"options": {
"process_person_profile": true
},
"properties": {
"plan": "pro"
}
}
]
}

FieldRequiredDescription
created_atYesWhen you built this batch, in RFC 3339 format
historical_migrationNotrue 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.
batchYesThe events. It can't be empty.

Each event in batch:

FieldRequiredDescription
eventYesThe event name, up to 200 bytes. See limits.
uuidYesA unique ID for this event. Use a UUIDv7. See event UUIDs.
distinct_idYesWho did it, up to 200 bytes. See choosing a distinct ID.
timestampYesWhen 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_idNoThe session ID, as a string. Same as the $session_id property.
window_idNoThe window ID, as a string. Same as the $window_id property.
optionsNoSettings for how PostHog processes this event. See event options.
propertiesNoThe 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.

OptionTypeWhat it doesReplaces
process_person_profileBooleanfalse sends an anonymous event that doesn't create or update a person profile$process_person_profile
cookieless_modeBooleantrue processes the event with cookieless tracking$cookieless_mode
disable_skew_correctionBooleantrue 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_idStringLinks the event to a product tour. You rarely need it$product_tour_id

  • Booleans also accept common forms like "true", "false", 1, and 0. null means "not set".
  • product_tour_id also 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.

FieldType
batchArray of event objects
created_atString (RFC 3339)
eventString
uuidString (UUID)
distinct_idString
timestampString (RFC 3339)
session_id, window_idString, 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

LimitRuleIf you exceed it
Request bodyNot empty400 empty_body
Request body, as sent10MB on the analytics endpoint, 20MB on the AI endpoint413, nothing stored
Request body, after decompression50MB on the analytics endpoint, 100MB on the AI endpoint413, nothing stored
Events per requestNo limit beyond the body size–
batchAt least one event400 empty_batch
uuidPresent, not empty, and a valid UUID400, 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 requestEach UUID onceThe first event is kept, later copies are dropped and counted in duplicates_dropped
created_atPresent, RFC 3339400, nothing stored: request_parsing_error if missing or null, invalid_batch if not RFC 3339
Required headersAll present (headers)400 missing_required_headers; 401 missing_authorization for Authorization
AuthorizationBearer <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-TimestampA UUID, a whole number from 1, and an RFC 3339 time400 invalid_header_value
Content-Typeapplication/json415 unsupported_content_type
Content-EncodingNone, or gzip, deflate, br, or zstd (not identity)415 unsupported_encoding
Header valuesVisible ASCII characters only400 invalid_header_value
Field typesSee field types400 request_parsing_error, nothing stored
PostHog-Sdk-Info<library>/<version>, with a /, up to 200 bytesRequest 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

FieldRuleIf an event breaks it
eventNot empty, up to 200 bytesdrop (missing_event_name, event_name_too_long)
distinct_idNot empty after trimming spaces, up to 200 bytesdrop (missing_distinct_id, distinct_id_too_large)
timestampRFC 3339drop (invalid_event_timestamp)
propertiesA JSON objectdrop (malformed_event_properties)
optionsA JSON object with readable valuesdrop (invalid_options)
The whole eventSmall enough to store, about 1MBdrop (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 400 request_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

StatusMeaningRetry?
200PostHog read the batch. Check the result for each event.Only events with result retry
400The 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
401The 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
402Your 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
404Nothing serves this path, for example a self-hosted instance that predates capture v1 or a proxy that doesn't forward itYes. If it keeps failing, check the host, your proxy, and your instance version.
408The request timed out while PostHog read itYes
413The body is over the size limitNo – send smaller requests
415Unsupported Content-Type or Content-EncodingNo
429Too 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, 504A temporary problemYes

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.

JSON
{
"error": "empty_batch",
"error_description": "request batch is empty",
"error_uri": "https://posthog.com/docs/api"
}

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.

JSON
{
"results": {
"019a0000-0000-7000-8000-000000000001": { "result": "ok" },
"019a0000-0000-7000-8000-000000000002": { "result": "warning", "details": "person_processing_disabled" },
"019a0000-0000-7000-8000-000000000003": { "result": "drop", "details": "invalid_options" },
"019a0000-0000-7000-8000-000000000004": { "result": "retry", "details": "not_persisted" },
"019a0000-0000-7000-8000-000000000005": { "result": "ok", "duplicates_dropped": 2 }
}
}

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.

ResultMeaningWhat to do
okStored, if your token matches a project (see 401)Nothing
warningStored, with a change you should know about, named in detailsDon't resend. Fix the cause.
dropNot storedDon't resend. Fix the cause named in details.
retryNot stored because of a temporary problemResend this event (and only this one)

Result details

details tells you why an event got its result. Common values:

DetailResultMeaning
missing_event_namedropevent is empty
event_name_too_longdropevent is over 200 bytes
missing_distinct_iddropdistinct_id is empty
distinct_id_too_largedropdistinct_id is over 200 bytes
invalid_event_timestampdroptimestamp isn't RFC 3339
malformed_event_propertiesdropproperties isn't a JSON object
invalid_optionsdropoptions isn't an object, or an option value can't be read
event_too_bigdropThe event is too large to store
misrouted_eventdropA non-AI event was sent to the AI endpoint
ai_event_too_bigdropAn AI event is over the size limit for the endpoint it was sent to
person_processing_disabledok or warningStored 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_persistedretryPostHog 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, or drop are final.
  • Keep the same PostHog-Request-Id and each event's uuid.
  • Increase PostHog-Attempt by 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-After header, 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-Timestamp makes 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

curl -i -X POST "https://us.i.posthog.com/i/v1/analytics/events" \
-H "Authorization: Bearer <ph_project_token>" \
-H "Content-Type: application/json" \
-H "User-Agent: my-backend/1.2.0" \
-H "PostHog-Sdk-Info: my-backend/1.2.0" \
-H "PostHog-Request-Id: $(uuidgen)" \
-H "PostHog-Attempt: 1" \
-H "PostHog-Request-Timestamp: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
-d '{
"created_at": "2026-10-19T12:00:00.250Z",
"batch": [
{
"event": "signed_up",
"uuid": "019a0000-0000-7000-8000-000000000001",
"distinct_id": "user_123",
"timestamp": "2026-10-19T12:00:00.123Z",
"options": { "process_person_profile": true },
"properties": { "plan": "pro" }
}
]
}'

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:

JSON
{"results":{"019a0000-0000-7000-8000-000000000001":{"result":"ok"}}}

Still have questions?

Was this page useful?