Persons

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

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.

Endpoints

    GET/api/projects/:project_id/persons/
    GET/api/projects/:project_id/persons/:id/
    PATCH/api/projects/:project_id/persons/:id/
    DELETE/api/projects/:project_id/persons/:id/
    GET/api/projects/:project_id/persons/:id/activity/
    POST/api/projects/:project_id/persons/:id/delete_property/
    GET/api/projects/:project_id/persons/:id/properties_timeline/
    POST/api/projects/:project_id/persons/:id/split/
    POST/api/projects/:project_id/persons/:id/update_property/
    GET/api/projects/:project_id/persons/activity/
    GET/api/projects/:project_id/persons/cohorts/
    GET/api/projects/:project_id/persons/funnel/
    POST/api/projects/:project_id/persons/funnel/
    GET/api/projects/:project_id/persons/funnel/correlation/
    POST/api/projects/:project_id/persons/funnel/correlation/
    GET/api/projects/:project_id/persons/lifecycle/
    GET/api/projects/:project_id/persons/path/
    POST/api/projects/:project_id/persons/path/
    GET/api/projects/:project_id/persons/retention/
    GET/api/projects/:project_id/persons/stickiness/
    GET/api/projects/:project_id/persons/trends/
    GET/api/projects/:project_id/persons/values/

    List all persons

    You can also use the query endpoint to retrieve persons. It enables you to use SQL to query the persons table.

    Required API key scopes

    person:read

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

    • distinct_id
      string

      Filter list by distinct id.

    • email
      string

      Filter persons by email (exact match)

    • format
      string
      One of: "csv""json"
    • limit
      integer

      Number of results to return per page.

    • offset
      integer

      The initial index from which to return the results.

    • properties
      Click to open
      array

      Filter Persons by person properties.

    • search
      string

      Search persons, either by email (full text search) or distinct_id (exact match).

    Response


    Request

    GET /api/projects/:project_id/persons
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/

    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 persons

    Required API key scopes

    person:read

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/:id
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/

    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 persons

    It is better to use the capture API to update person properties.

    This endpoint functionally captures a $set event with a $set property key along with the property values you want to update.

    Required API key scopes

    person:write

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Request parameters

    • properties

    Response


    Request

    PATCH /api/projects/:project_id/persons/:id
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl -X PATCH \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/\
    	-d name="string"

    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"
    }

    Delete persons

    This is the main way to delete data in PostHog.

    To learn more, see our data deletion docs.

    Required API key scopes

    person:write

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

    • delete_events
      boolean

      If true, a task to delete all events associated with this person will be created and queued. The task does not run immediately and instead is batched together and at 5AM UTC every Sunday (controlled by environment variable CLEAR_CLICKHOUSE_REMOVED_DATA_SCHEDULE_CRON)

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

    Request

    DELETE /api/projects/:project_id/persons/:id
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl  -X DELETE \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/

    Response

    Status 204 No response body

    Retrieve persons activity retrieve

    Required API key scopes

    activity_log:read

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/:id/activity
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/activity/

    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"
    }

    Create persons delete property

    It is better to use the capture API to change person properties.

    This endpoint functionally captures a $delete_person_property event with an $unset property key along with the property value you want to delete.

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

    • $unset
      string

      Specify the property key to delete

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

    Request parameters

    • properties

    Response


    Request

    POST /api/projects/: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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/delete_property/\
    	-d name="string"

    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 persons properties timeline

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/properties_timeline/

    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"
    }

    Create persons split

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Request parameters

    • properties

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/split/\
    	-d name="string"

    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"
    }

    Create persons update property

    It is better to use the capture API to update person properties.

    This endpoint functionally captures a $set event with a $set property key along with the property value you want to update.

    Path parameters

    • id
      integer

      A unique integer value identifying this person.

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

      Specify the property key

    • value

      Specify the property value

    Request parameters

    • properties

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/:id/update_property/\
    	-d name="string"

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/activity/

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

    Required API key scopes

    person:readcohort:read

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/cohorts/

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/

    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"
    }

    Create persons funnel

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Request parameters

    • properties

    Response


    Request

    POST /api/projects/: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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/\
    	-d name="string"

    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 persons funnel correlation

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/funnel/correlation
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/correlation/

    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"
    }

    Create persons funnel correlation

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Request parameters

    • properties

    Response


    Request

    POST /api/projects/: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" \
        https://app.posthog.com/api/projects/:project_id/persons/funnel/correlation/\
    	-d name="string"

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/lifecycle
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/lifecycle/

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/path
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/path/

    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"
    }

    Create persons path

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Request parameters

    • properties

    Response


    Request

    POST /api/projects/:project_id/persons/path
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/path/\
    	-d name="string"

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/retention
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/retention/

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/stickiness
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/stickiness/

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

    Path parameters

    • project_id
      string

      Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

    Query parameters

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

    Response


    Request

    GET /api/projects/:project_id/persons/values
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/persons/values/

    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"
    }

    Questions?

    Was this page useful?