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`
`GET`
`GET`
`POST`
`GET`
`POST`
`GET`
`POST`
`GET`
`GET`

List all environments persons

Required API key scopes

person:read

Path parameters

project_id
string

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/:project_id/persons
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/persons/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{project_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"
    }
  ]
}

Retrieve environments persons

Required API key scopes

person:read

Path parameters

id
integer
project_id
string

Query parameters

format
string
One of: "csv""json"

Response

Example request

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

Update environments persons

Required API key scopes

person:write

Path parameters

id
integer
project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Response

Example request

PATCH /api/environments/:project_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/:project_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/{project_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"
}

Retrieve environments persons activity retrieve

Required API key scopes

activity_log:read

Path parameters

id
integer
project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Required API key scopes

person:write

Path parameters

id
integer
project_id
string

Query parameters

$unset
string
format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:project_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/:project_id/persons/:id/delete_property/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/persons/{person_id}/delete_property/".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

Retrieve environments persons properties timeline

Path parameters

id
integer
project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

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/environments/: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/environments/: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/environments/{project_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

Required API key scopes

person:write

Path parameters

id
integer
project_id
string

Query parameters

format
string
One of: "csv""json"
key
string
value

Request parameters

properties

Example request

POST /api/environments/: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/environments/:project_id/persons/:id/update_property/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/persons/{person_id}/update_property/".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

Retrieve environments persons activity

Required API key scopes

activity_log:read

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

delete_events
boolean
Default: false
delete_recordings
boolean
Default: false
distinct_ids
object
format
string
One of: "csv""json"
ids
object
keep_person
boolean
Default: false

Request parameters

properties

Example request

POST /api/environments/: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/environments/:project_id/persons/bulk_delete/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/persons/bulk_delete/".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 cohorts

Required API key scopes

person:readcohort:read

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Retrieve environments persons funnel

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:project_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/:project_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/{project_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 funnel correlation

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create environments persons funnel correlation

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:project_id/persons/funnel/correlation
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/:project_id/persons/funnel/correlation/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/persons/funnel/correlation/".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

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Create environments persons reset person distinct id

Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.

Required API key scopes

person:write

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Request parameters

properties

Example request

POST /api/environments/:project_id/persons/reset_person_distinct_id
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/:project_id/persons/reset_person_distinct_id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/persons/reset_person_distinct_id/".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 stickiness

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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

Example response

Status 200 No response body

Retrieve environments persons trends

Path parameters

project_id
string

Query parameters

format
string
One of: "csv""json"

Example request

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