openapi: 3.0.3
info:
title: PostHog actions persons API
version: 1.0.0
description: ''
tags:
- name: persons
paths:
/api/environments/{environment_id}/persons/:
get:
operationId: environments_persons_list
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- in: query
name: distinct_id
schema:
type: string
description: Filter list by distinct id.
- in: query
name: email
schema:
type: string
description: Filter persons by email (exact match)
examples:
Email:
value: test@test.com
summary: email
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: query
name: properties
schema:
type: array
items:
$ref: '#/components/schemas/Property'
description: Filter Persons by person properties.
- in: query
name: search
schema:
type: string
description: Search persons, either by email (full text search) or distinct_id (exact match).
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedPersonRecordList'
text/csv:
schema:
$ref: '#/components/schemas/PaginatedPersonRecordList'
description: ''
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/{id}/:
get:
operationId: environments_persons_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both numeric ID and UUID.
required: true
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
text/csv:
schema:
$ref: '#/components/schemas/PersonRecord'
description: ''
deprecated: true
x-explicit-tags:
- persons
put:
operationId: environments_persons_update
description: 'Only for setting properties on the person. "properties" from the request data will be updated via a "$set" event.
This means that only the properties listed will be updated, but other properties won''t be removed nor updated.
If you would like to remove a property use the `delete_property` endpoint.'
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both numeric ID and UUID.
required: true
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
text/csv:
schema:
$ref: '#/components/schemas/PersonRecord'
description: ''
deprecated: true
x-explicit-tags:
- persons
patch:
operationId: environments_persons_partial_update
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both numeric ID and UUID.
required: true
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedPersonRecord'
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
text/csv:
schema:
$ref: '#/components/schemas/PersonRecord'
description: ''
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/{id}/activity/:
get:
operationId: environments_persons_activity_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this person.
required: true
tags:
- persons
security:
- PersonalAPIKeyAuth:
- activity_log:read
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/{id}/delete_property/:
post:
operationId: environments_persons_delete_property_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both numeric ID and UUID.
required: true
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonDeletePropertyRequest'
required: true
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/{id}/properties_timeline/:
get:
operationId: environments_persons_properties_timeline_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this person.
required: true
tags:
- persons
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/{id}/split/:
post:
operationId: environments_persons_split_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this person.
required: true
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/{id}/update_property/:
post:
operationId: environments_persons_update_property_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both numeric ID and UUID.
required: true
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonUpdatePropertyRequest'
required: true
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/activity/:
get:
operationId: environments_persons_all_activity_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
security:
- PersonalAPIKeyAuth:
- activity_log:read
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/batch_by_distinct_ids/:
post:
operationId: environments_persons_batch_by_distinct_ids_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/batch_by_uuids/:
post:
operationId: environments_persons_batch_by_uuids_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/bulk_delete/:
post:
operationId: environments_persons_bulk_delete_create
description: 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.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonBulkDeleteRequest'
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonBulkDeleteResponse'
text/csv:
schema:
$ref: '#/components/schemas/PersonBulkDeleteResponse'
description: ''
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/cohorts/:
get:
operationId: environments_persons_cohorts_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: query
name: person_id
schema:
type: string
description: The person ID or UUID to get cohorts for.
required: true
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
- cohort:read
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/deletion_status/:
get:
operationId: environments_persons_deletion_status_list
description: 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.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: query
name: person_uuid
schema:
type: string
format: uuid
description: Filter by a specific person UUID.
- in: query
name: status
schema:
type: string
enum:
- all
- completed
- pending
description: 'Filter by deletion status: ''pending'', ''completed'', or ''all''.'
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAsyncDeletionStatusList'
text/csv:
schema:
$ref: '#/components/schemas/PaginatedAsyncDeletionStatusList'
description: ''
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/funnel/:
get:
operationId: environments_persons_funnel_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
post:
operationId: environments_persons_funnel_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/funnel/correlation/:
get:
operationId: environments_persons_funnel_correlation_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
post:
operationId: environments_persons_funnel_correlation_create
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/lifecycle/:
get:
operationId: environments_persons_lifecycle_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/properties_at_time/:
get:
operationId: environments_persons_properties_at_time_retrieve
description: '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)
- debug: Whether to include debug information with raw events (default: false)'
parameters:
- in: query
name: debug
schema:
type: boolean
description: 'Whether to include debug information with raw events (only works when DEBUG=True, default: false)'
- in: query
name: distinct_id
schema:
type: string
description: The distinct_id of the person (mutually exclusive with person_id)
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: query
name: include_set_once
schema:
type: boolean
description: 'Whether to handle $set_once operations (default: false)'
- in: query
name: person_id
schema:
type: string
description: The person_id (UUID) to build properties for (mutually exclusive with distinct_id)
- in: query
name: timestamp
schema:
type: string
description: ISO datetime string for the point in time (e.g., '2023-06-15T14:30:00Z')
required: true
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonPropertiesAtTimeResponse'
text/csv:
schema:
$ref: '#/components/schemas/PersonPropertiesAtTimeResponse'
description: ''
'400':
content:
application/json:
schema:
description: Bad request - invalid parameters
text/csv:
schema:
description: Bad request - invalid parameters
description: ''
'404':
content:
application/json:
schema:
description: Person not found
text/csv:
schema:
description: Person not found
description: ''
'500':
content:
application/json:
schema:
description: Internal server error
text/csv:
schema:
description: Internal server error
description: ''
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/reset_person_distinct_id/:
post:
operationId: environments_persons_reset_person_distinct_id_create
description: Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
security:
- PersonalAPIKeyAuth:
- person:write
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/trends/:
get:
operationId: environments_persons_trends_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
tags:
- persons
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/environments/{environment_id}/persons/values/:
get:
operationId: environments_persons_values_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- $ref: '#/components/parameters/EnvironmentIdPath'
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: query
name: key
schema:
type: string
description: The person property key to get values for (e.g., 'email', 'plan', 'role').
required: true
- in: query
name: value
schema:
type: string
description: Optional search string to filter values (case-insensitive substring match).
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
description: No response body
deprecated: true
x-explicit-tags:
- persons
/api/projects/{project_id}/persons/:
get:
operationId: persons_list
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- in: query
name: distinct_id
schema:
type: string
description: Filter list by distinct id.
- in: query
name: email
schema:
type: string
description: Filter persons by email (exact match)
examples:
Email:
value: test@test.com
summary: email
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- $ref: '#/components/parameters/ProjectIdPath'
- in: query
name: properties
schema:
type: array
items:
$ref: '#/components/schemas/Property'
description: Filter Persons by person properties.
- in: query
name: search
schema:
type: string
description: Search persons, either by email (full text search) or distinct_id (exact match).
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedPersonRecordList'
text/csv:
schema:
$ref: '#/components/schemas/PaginatedPersonRecordList'
description: ''
x-explicit-tags:
- persons
/api/projects/{project_id}/persons/{id}/:
get:
operationId: persons_retrieve
description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both numeric ID and UUID.
required: true
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- persons
security:
- PersonalAPIKeyAuth:
- person:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PersonRecord'
text/csv:
schema:
$ref: '#/components/schemas/PersonRecord'
description: ''
x-explicit-tags:
- persons
put:
operationId: persons_update
description: 'Only for setting properties on the person. "properties" from the request data will be updated via a "$set" event.
This means that only the properties listed will be updated, but other properties won''t be removed nor updated.
If you would like to remove a property use the `delete_property` endpoint.'
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: string
description: A unique value identifying this person. Accepts both num
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/posthog/refs/heads/main/openapi/posthog-persons-api-openapi.yml