Forward events to PostHog

On this page

If your team already lives in PostHog, forward every accepted event there too and read agent traffic next to the rest. Events from the browser snippet are the exception: they go to PostHog and GA4 only after you turn that on for the project ("Browser snippet" in section 5). Send the project token (phc_…, the public write-only key from your PostHog project settings) and the region your project is in. A token that does not start with phc_ is refused with 400 invalid_field; a personal API key (phx_…) is a secret and is never stored. Changing forwarding, here or in Settings, needs a key with the write scope:

sh
curl -sS -X PUT https://alg.katrinalaszlo.com/v1/traffic/sink \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "'$PROJECT_ID'", "posthog": { "api_key": "phc_…", "region": "us" } }'

Each event arrives in PostHog under its own name, with the properties the event carried plus these, so you can filter by agent in PostHog:

PropertyValue
agentthe agent Track names for that request, as the journey pages show it: ChatGPT-User, PerplexityBot, Chrome, curl, or the host of its Signature-Agent
agent_classthe class Track gives that one request: known_agent, declared_agent_assisted, suspected_automation, human or unknown. Left out if classification failed for that batch
agent_typewhat kind of agent sent it: crawler, assistant, browser_agent or other (Agent types, section 7), or null when agent_class is human or unknown. Left out if classification failed for that batch
paththe request path as stored, such as /docs/quickstart. Left out when none was stored, so a path the event's own properties carried stays
journey_id, journey_sourcethe journey key and where it came from (cookie, header, query, issued, handoff), or null
identity_tier, identity_tier_confidencehow sure Track is who sent it
signature_agentthe Signature-Agent header as sent, or null
session_id, run_id, account_idthe session hint, run hint and account id the event carried, or null
name, sourcethe event name and where it came from (middleware, sdk, log)
agent_traffic_event_id, agent_traffic_project_idthe event and project ids in Track
outcome_nameonly on an event that recorded an outcome: signup, key_created, activation, paid or custom
value, value_minor, currencyonly on an outcome with a value: value in major units (49 for 4900 cents), value_minor as sent (4900), the ISO currency code

The raw User-Agent is not sent: it is long, can identify a person's browser, and agent and agent_class already say what it means. distinct_id is the account id when the event has one, else the session hint, else the event id, and no person profile is created ($process_person_profile is false, and nothing is $set). GeoIP is off ($geoip_disable), because the request comes from Track's server and PostHog would otherwise place every event at the server's location. Events forwarded before 2026-10-24 lack agent, agent_class, path, journey_id, journey_source and the outcome fields, and agent_type was added on 2026-10-24 (UTC): events forwarded before then lack it, and so may events forwarded that day before about 03:30 UTC. Needs the write scope. "posthog": null turns it off. A PostHog failure never rejects an event; the event is stored here either way. Forwarding starts after POST /v1/events has answered, so it never slows the 202 down, and the 202 says nothing about it. To see whether it worked, read GET /v1/traffic/sink (read scope, ?project_id= optional):

sh
curl -sS https://alg.katrinalaszlo.com/v1/traffic/sink \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
json
{
  "project_id": "…",
  "posthog": { "api_key": "phc_oPy…", "region": "us", "last_sent_at": "2026-10-23T18:02:11.000Z", "last_failed_at": null, "last_error": null, "events_sent": 42, "events_failed": 0 },
  "ga4": null
}

Each destination is null when off. The token shows only its first 7 characters. last_error is a short message, such as PostHog: 1 of 1 events failed: PostHog answered 401 for event …, and never contains a token or secret. events_sent and events_failed are totals. The same status shows in Settings under the PostHog and GA4 cards ("Last sent …", or the last error), and POST /v1/install-check adds a forwarding line for each destination that is on.