Persons API Reference

Persons

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`GET`
`PATCH`
`GET`
`POST`
`GET`
`POST`
`POST`
`GET`
`POST`
`POST`
`POST`
`GET`
`GET`
`GET`
`POST`
`GET`
`GET`

Also available via the PostHog MCP server:
persons-list — List persons

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:read

Query parameters

distinct_id
string
email
string
format
string
One of: "csv""json"
limit
integer
offset
integer
properties
array
search
string

Response

Example request

GET /api/environments/:environment_id/persons
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "next": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "previous": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "count": 400,
  "results": [
    {
      "id": 0,
      "name": "string",
      "distinct_ids": [
        "string"
      ],
      "properties": null,
      "created_at": "2019-08-24T14:15:22Z",
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "last_seen_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve environments persons

Also available via the PostHog MCP server:
persons-retrieve — Get person

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:read

Path parameters

id
string

Query parameters

format
string
One of: "csv""json"

Response

Example request

GET /api/environments/:environment_id/persons/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": null,
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "last_seen_at": "2019-08-24T14:15:22Z"
}

Update environments persons

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:write

Path parameters

id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Response

Example request

PATCH /api/environments/:environment_id/persons/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": null,
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "last_seen_at": "2019-08-24T14:15:22Z"
}

Retrieve environments persons activity

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

activity_log:read

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/:id/activity
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/activity/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/activity/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments persons delete property

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:write

Path parameters

id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

$unset
string

Example request

POST /api/environments/:environment_id/persons/:id/delete_property
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/delete_property/\
	-d $unset="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/delete_property/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"$unset": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments persons properties timeline

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/:id/properties_timeline
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/properties_timeline/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/properties_timeline/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments persons split

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:write

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/:id/split
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/split/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/split/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons update property

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:write

Path parameters

id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

key
string
value

Example request

POST /api/environments/:environment_id/persons/:id/update_property
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/:id/update_property/\
	-d key="string",\
	-d value=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/{person_id}/update_property/".format(
        project_id=project_id,
		person_id="<the person id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments persons all activity

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

activity_log:read

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/activity
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/activity/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments persons batch by distinct ids

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/batch_by_distinct_ids
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/batch_by_distinct_ids/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/batch_by_distinct_ids/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons batch by uuids

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/batch_by_uuids
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/batch_by_uuids/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/batch_by_uuids/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create environments persons bulk delete

This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs. You can pass in a maximum of 1000 IDs per call. Only events captured before the request will be deleted.

Required API key scopes

person:write

Query parameters

format
string
One of: "csv""json"

Request parameters

ids
array
distinct_ids
array
delete_events
boolean
Default: false
delete_recordings
boolean
Default: false
keep_person
boolean
Default: false

Response

Example request

POST /api/environments/:environment_id/persons/bulk_delete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/bulk_delete/\
	-d ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/bulk_delete/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

Example response

Status 202

RESPONSE
{
  "persons_found": 0,
  "persons_deleted": 0,
  "events_queued_for_deletion": true,
  "recordings_queued_for_deletion": true,
  "deletion_errors": [
    {}
  ]
}

Retrieve environments persons cohorts

Also available via the PostHog MCP server:
persons-cohorts-retrieve — Get person cohorts

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Required API key scopes

person:readcohort:read

Query parameters

format
string
One of: "csv""json"
person_id
string

Example request

GET /api/environments/:environment_id/persons/cohorts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/cohorts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/cohorts/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

List all environments persons deletion status

List the status of queued event deletions for persons. When you delete a person with delete_events=true, an async deletion is queued. Use this endpoint to check whether those deletions are still pending or have been completed.

Required API key scopes

person:read

Query parameters

format
string
One of: "csv""json"
limit
integer
offset
integer
person_uuid
string
status
string
One of: "all""completed""pending"

Response

Example request

GET /api/environments/:environment_id/persons/deletion_status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/deletion_status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/deletion_status/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "next": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "previous": "https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100",
  "count": 400,
  "results": [
    {
      "person_uuid": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "status": "string",
      "delete_verified_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve environments persons funnel

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/funnel
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/funnel/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments persons funnel

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:environment_id/persons/funnel
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/funnel/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/persons/funnel/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments persons lifecycle

This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the capture API, the $set and $unset properties, or one of our SDKs.

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/environments/:environment_id/persons/lifecycle
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/lifecycle/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/lifecycle/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve environments persons properties at time

Get person properties as they existed at a specific point in time.

This endpoint reconstructs person properties by querying ClickHouse events for $set and $set_once operations up to the specified timestamp.

Query parameters:

distinct_id: The distinct_id of the person
timestamp: ISO datetime string for the point in time (e.g., "2023-06-15T14:30:00Z")
include_set_once: Whether to handle $set_once operations (default: false)

Required API key scopes

person:read

Query parameters

distinct_id
string
format
string
One of: "csv""json"
include_set_once
boolean
person_id
string
timestamp
string

Response

Example request

GET /api/environments/:environment_id/persons/properties_at_time
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/properties_at_time/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/properties_at_time/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": {
    "property1": "string",
    "property2": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "last_seen_at": "2019-08-24T14:15:22Z",
  "point_in_time_metadata": {
    "queried_timestamp": "string",
    "include_set_once": true,
    "distinct_id_used": "string",
    "person_id_used": "string",
    "query_mode": "string",
    "distinct_ids_queried": [
      "string"
    ],
    "distinct_ids_count": 0
  }
}

Status 400

Status 404

Status 500

Retrieve environments persons properties at time

Get person properties as they existed at a specific point in time.

This endpoint reconstructs person properties by querying ClickHouse events for $set and $set_once operations up to the specified timestamp.

Query parameters:

distinct_id: The distinct_id of the person
timestamp: ISO datetime string for the point in time (e.g., "2023-06-15T14:30:00Z")
include_set_once: Whether to handle $set_once operations (default: false)

Required API key scopes

person:read

Query parameters

distinct_id
string
format
string
One of: "csv""json"
include_set_once
boolean
person_id
string
timestamp
string

Response

Example request

GET /api/environments/:environment_id/persons/properties_at_time
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/persons/properties_at_time/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/persons/properties_at_time/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "distinct_ids": [
    "string"
  ],
  "properties": {
    "property1": "string",
    "property2": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "last_seen_at": "2019-08-24T14:15:22Z",
  "point_in_time_metadata": {
    "queried_timestamp": "string",
    "include_set_once": true,
    "distinct_id_used": "string",
    "person_id_used": "string",
    "query_mode": "string",
    "distinct_ids_queried": [
      "string"
    ],
    "distinct_ids_count": 0
  }
}