Using the PostHog API to capture events

Ian Vanagas

Oct 22, 2025

PostHog provides libraries that make it easy to capture events in popular languages. These libraries are basically wrappers around the API. They handle and automate common tasks like capturing pageviews.

Using the API directly allows for any language that can send requests to capture events, or completely customize your implementation. Using the API to capture events directly also gives you a better understanding of PostHog's event-based data structures which is abstracted if you use a library.

Base URL

The base URL of your PostHog depends on the region of your PostHog project:

https://us.i.posthog.com

Capture endpoint

PostHog captures events through /i/v0/e/ endpoint of your project region.

For your PostHog project (if you're authenticated on PostHog), the fill URL is:

Terminal

https://us.i.posthog.com/i/v0/e/

You can also use the /batch endpoint to capture multiple events in one request. We cover this in the batching events section.

Terminal

https://us.i.posthog.com/batch/

Authenticating with the project API key

The first thing needed, like the basic GET request tutorial, is to authenticate ourselves in the API. Unlike in the GET request tutorial, we can use the project API key (the same key you use to initialize a PostHog library). This can be found in your project settings.

The project API key is a write-only key, which works perfectly for the POST-only endpoints we want to access.

Basic event capture request

To capture events, all we need is a project API key, the data we want to send, and a way to send a request. To capture a new event, you need to send a POST request to <ph_client_api_host>/i/v0/e/ (or the /i/v0/e endpoint for your instance) with the project API key, event name, and distinct ID.

# curl
curl -v -L --header "Content-Type: application/json" -d '{
    "api_key": "<ph_project_api_key>",
    "event": "request",
    "distinct_id": "ian@posthog.com"
}' https://us.i.posthog.com/i/v0/e/

Once you've done that, you should see the event in your PostHog project's activity tab.

Adding properties and batching

You can also add arbitrary properties and a timestamp in ISO 8601 format to this request. If you don't add a timestamp, we automatically set it to the current time.

curl -v -L --header "Content-Type: application/json" -d '{
    "api_key": "<ph_project_api_key>",
    "properties": {
            "request_size": "big",
            "api_request": true
        },
    "timestamp": "2022-09-21 09:03:11.913767",
    "distinct_id": "ian@posthog.com",
    "event": "big_request"
}' https://us.i.posthog.com/i/v0/e/

You can also batch these requests together by sending a list of events to the /batch/ endpoint. This is useful for limiting the number of requests you make. Events can be held, then sent as a batch. PostHog SDKs do this automatically, and we use batching to process events.

curl -v -L --header "Content-Type: application/json" -d '{
    "api_key": "<ph_project_api_key>",
    "batch": [
        {
            "event": "batched_event",
            "properties" : {
                                "distinct_id": "ian@posthog.com",
                "number_in_batch": 1
            }
        },
        {
            "event": "batched_event",
            "properties" : {
                                "distinct_id": "ian@posthog.com",
                "number_in_batch": 2
            }
        }
    ]
}' https://us.i.posthog.com/batch/

Identifying and aliasing users

You can also POST $identify events to add more details about those users. The API has no concept of state so the user information is not added as properties unless you send it in a request. It is not automatically created or included in the request like it is in the JavaScript library.

You still send identify events to the /i/v0/e/ endpoint. Use $set to set the person properties you want.

curl -v -L --header "Content-Type: application/json" -d '{
    "api_key": "<ph_project_api_key>",
    "distinct_id": "ian@posthog.com",
    "$set": {
            "email": "ian@posthog.com",
            "is_cool": true
        },
    "event": "$identify"
}' https://us.i.posthog.com/i/v0/e/

Aliasing users

If you have two users you'd like to combine together, you can use a $create_alias event. See more about this in our identifying users documentation.

curl -v -L --header "Content-Type: application/json" -d '{
    "api_key": "<ph_project_api_key>",
    "properties": {
        "distinct_id": "ian@posthog.com",
        "alias": "ian2@posthog.com"
    },
    "event": "$create_alias"
}' https://us.i.posthog.com/i/v0/e/

Capturing errors

Everything is an event in PostHog. Error tracking is no different. You can manually capture errors by sending an $exception event with the following properties:

Property	Description
`$exception_list`	A list of exception objects with detailed information about each error. Each exception can include a `type`, `value`, `mechanism`, `module`, and a `stacktrace` with `frames` and `type`. You can find the expected schema as types for both exception and stack frames in our Rust repo
`$exception_fingerprint`	(Optional) The identifier used to group issues. If not set, a unique hash based on the exception pattern will be generated during ingestion

Here's an example of how to capture an error:

curl -X POST "https://us.i.posthog.com/i/v0/e/" \
     -H "Content-Type: application/json" \
     -d '{
         "api_key": "<ph_project_api_key>",
         "event": "$exception",
         "properties": {
             "distinct_id": "ian@posthog.com",
             "$exception_list": [{
                 "type": "ScriptError",
                 "value": "Command not found: fake_command",
                 "mechanism": {
                     "handled": true,
                     "synthetic": false
                 },
                 "stacktrace": {
                     "type": "raw",
                     "frames": [
                         {
                             "platform": "custom",
                             "lang": "bash",
                             "function": "main",
                             "filename": "basic-exception.sh",
                             "lineno": 15,
                             "colno": 1,
                             "module": "script_execution",
                             "resolved": true,
                             "in_app": true
                         },
                         {
                             "platform": "custom",
                             "lang": "bash",
                             "function": "execute_command",
                             "filename": "utils.sh",
                             "lineno": 42,
                             "colno": 5,
                             "module": "command_handler",
                             "resolved": true,
                             "in_app": true
                         },
                         {
                             "platform": "custom",
                             "lang": "bash",
                             "function": "error_event_bash",
                             "filename": "error_handler.sh",
                             "lineno": 8,
                             "colno": 12,
                             "module": "error_tracking",
                             "resolved": false,
                             "in_app": false
                         }
                     ]
                 }
             }],
             "$exception_fingerprint": <MD5_HASH_OF_EXCEPTION_MESSAGE>
         }
     }'

While possible, we strongly recommend you stick to using our error tracking SDKs instead of manually capturing errors for features like accurate fingerprinting, source-map support, release tracking, and more.

Capturing LLM analytics events

It's also possible to capture LLM analytics events using the API. If you're using a language without SDK support for LLM analytics, you can use the API to capture events.

To capture LLM analytics, you need to capture 4 types of events:

Event type	Event name	Documentation
Generations	`$ai_generation`	What are generations?
Spans	`$ai_span`	What are spans?
Traces	`$ai_trace`	What are traces?
Embeddings	`$ai_embedding`	What are embeddings?

You can find more information in our manual capture guide.