Persons-4 API Reference

Persons-4

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

Endpoints

`GET`
`POST`
`POST`
`GET`
`POST`
`POST`
`POST`
`GET`
`GET`
`GET`

Retrieve 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
project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/projects/:project_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/projects/:project_id/persons/:id/properties_timeline/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/persons/{persons-4_id}/properties_timeline/".format(
        project_id=project_id,
		persons-4_id="<the persons-4 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve 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
project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/projects/:project_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/projects/:project_id/persons/:id/properties_timeline/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/persons/{persons-4_id}/properties_timeline/".format(
        project_id=project_id,
		persons-4_id="<the persons-4 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create 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
project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_id}/persons/{persons-4_id}/split/".format(
        project_id=project_id,
		persons-4_id="<the persons-4 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create 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
project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_id}/persons/{persons-4_id}/split/".format(
        project_id=project_id,
		persons-4_id="<the persons-4 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200 No response body

Create 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
project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

key
string
value

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_id}/persons/{persons-4_id}/update_property/".format(
        project_id=project_id,
		persons-4_id="<the persons-4 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200 No response body

Create 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
project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

key
string
value

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_id}/persons/{persons-4_id}/update_property/".format(
        project_id=project_id,
		persons-4_id="<the persons-4 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve 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

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Retrieve 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

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create 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.

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_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 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.

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_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 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.

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_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 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.

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/projects/:project_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/projects/:project_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/projects/{project_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 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

Path parameters

project_id
string

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/projects/:project_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/projects/:project_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/projects/{project_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": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Create persons bulk delete

Required API key scopes

person:write

Path parameters

project_id
string

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/projects/:project_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/projects/:project_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/projects/{project_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": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Retrieve persons 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

Path parameters

project_id
string

Query parameters

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

Example request

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

Example response

Status 200 No response body

Retrieve persons 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

Path parameters

project_id
string

Query parameters

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

Example request

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

Example response

Status 200 No response body

List all 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

Path parameters

project_id
string

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/projects/:project_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/projects/:project_id/persons/deletion_status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_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"
    }
  ]
}

List all persons deletion status

Required API key scopes

person:read

Path parameters

project_id
string

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/projects/:project_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/projects/:project_id/persons/deletion_status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_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 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.

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Retrieve 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.

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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