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 numeric ID and UUID.
        required: true
      - $ref: '#/components/parameters/ProjectIdPath'
      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: ''
      x-explicit-tags:
      - persons
    patch:
      operationId: 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:
      - 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
      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: ''
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/{id}/activity/:
    get:
      operationId: 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:
      - 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
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      security:
      - PersonalAPIKeyAuth:
        - activity_log:read
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/{id}/delete_property/:
    post:
      operationId: 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:
      - 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonDeletePropertyRequest'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - person:write
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/{id}/properties_timeline/:
    get:
      operationId: 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:
      - 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
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/{id}/split/:
    post:
      operationId: 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:
      - 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
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRecord'
      security:
      - PersonalAPIKeyAuth:
        - person:write
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/{id}/update_property/:
    post:
      operationId: 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:
      - 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonUpdatePropertyRequest'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - person:write
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/activity/:
    get:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      security:
      - PersonalAPIKeyAuth:
        - activity_log:read
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/batch_by_distinct_ids/:
    post:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRecord'
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/batch_by_uuids/:
    post:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRecord'
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/bulk_delete/:
    post:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      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: ''
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/cohorts/:
    get:
      operationId: 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:
      - 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
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      security:
      - PersonalAPIKeyAuth:
        - person:read
        - cohort:read
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/deletion_status/:
    get:
      operationId: 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:
      - 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.
      - $ref: '#/components/parameters/ProjectIdPath'
      - 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: ''
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/funnel/:
    get:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
    post:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRecord'
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/funnel/correlation/:
    get:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
    post:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRecord'
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/lifecycle/:
    get:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/properties_at_time/:
    get:
      operationId: 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)
      - 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)
      - $ref: '#/components/parameters/ProjectIdPath'
      - 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: ''
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/reset_person_distinct_id/:
    post:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRecord'
      security:
      - PersonalAPIKeyAuth:
        - person:write
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/trends/:
    get:
      operationId: 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:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - persons
      responses:
        '200':
          description: No response body
      x-explicit-tags:
      - persons
  /api/projects/{project_id}/persons/values/:
    get:
      operationId: 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:
      - 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
      - $ref: '#/components/parameters/ProjectIdPath'
      - 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
      x-explicit-tags:
      - persons
components:
  schemas:
    PersonPropertiesAtTimeMetadata:
      type: object
      description: Serializer for the point-in-time query metadata.
      properties:
        queried_timestamp:
          type: string
          description: The timestamp that was queried in ISO format
        include_set_once:
          type: boolean
          description: Whether $set_once operations were included
        distinct_id_used:
          type: string
          nullable: true
          description: The distinct_id parameter used in the request
        person_id_used:
          type: string
          nullable: true
          description: The person_id parameter used in the request
        query_mode:
          type: string
          description: Whether the query used 'distinct_id' or 'person_id' mode
        distinct_ids_queried:
          type: array
          items:
            type: string
          description: All distinct_ids that were queried for this person
        distinct_ids_count:
          type: integer
          description: Number of distinct_ids associated with this person
      required:
      - distinct_id_used
      - distinct_ids_count
      - distinct_ids_queried
      - include_set_once
      - person_id_used
      - queried_timestamp
      - query_mode
    PaginatedAsyncDeletionStatusList:
      type: object
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100
        count:
          type: integer
          example: 400
        results:
          type: array
          items:
            $ref: '#/components/schemas/AsyncDeletionStatus'
    PropertyItemOperatorEnum:
      enum:
      - exact
      - is_not
      - icontains
      - not_icontains
      - regex
      - not_regex
      - gt
      - lt
      - gte
      - lte
      - is_set
      - is_not_set
      - is_date_exact
      - is_date_after
      - is_date_before
      - in
      - not_in
      type: string
      description: '* `exact` - exact

        * `is_not` - is_not

        * `icontains` - icontains

        * `not_icontains` - not_icontains

        * `regex` - regex

        * `not_regex` - not_regex

        * `gt` - gt

        * `lt` - lt

        * `gte` - gte

        * `lte` - lte

        * `is_set` - is_set

        * `is_not_set` - is_not_set

        * `is_date_exact` - is_date_exact

        * `is_date_after` - is_date_after

        * `is_date_before` - is_date_before

        * `in` - in

        * `not_in` - not_in'
    PatchedPersonRecord:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Numeric person ID.
        name:
          type: string
          readOnly: true
          description: Display name derived from person properties (email, name, or username).
        distinct_ids:
          type: array
          items:
            type: string
          readOnly: true
        properties:
          description: Key-value map of person properties set via $set and $set_once operations.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When this person was first seen (ISO 8601).
        uuid:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier (UUID) for this person.
        last_seen_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Timestamp of the last event from this person, or null.
    NullEnum:
      enum:
      - null
    PersonUpdatePropertyRequest:
      type: object
      properties:
        key:
          type: string
          description: The property key to set.
        value:
          description: The property value. Can be a string, number, boolean, or object.
      required:
      - key
      - value
    Property:
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/PropertyGroupOperator'
          default: AND
          description: "\n You can use a simplified version:\n```json\n{\n    \"properties\": [\n        {\n            \"key\": \"email\",\n            \"value\": \"x@y.com\",\n            \"operator\": \"exact\",\n            \"type\": \"event\"\n        }\n    ]\n}\n```\n\nOr you can create more complicated queries with AND and OR:\n```json\n{\n    \"properties\": {\n        \"type\": \"AND\",\n        \"values\": [\n            {\n                \"type\": \"OR\",\n                \"values\": [\n                    {\"key\": \"email\", ...},\n                    {\"key\": \"email\", ...}\n                ]\n            },\n            {\n                \"type\": \"AND\",\n                \"values\": [\n                    {\"key\": \"email\", ...},\n                    {\"key\": \"email\", ...}\n                ]\n            }\n        ]\n    ]\n}\n```\n\n\n* `AND` - AND\n* `OR` - OR"
        values:
          type: array
          items:
            $ref: '#/components/schemas/PropertyItem'
      required:
      - values
    PersonBulkDeleteResponse:
      type: object
      properties:
        persons_found:
          type: integer
          description: Number of persons matched by the provided IDs or distinct IDs.
        persons_deleted:
          type: integer
          description: Number of person records deleted from the database. 0 if keep_person was true.
        events_queued_for_deletion:
          type: boolean
          description: Whether event deletion was requested for the matched persons. If a deletion was already queued for a person, it will not be duplicated.
        recordings_queued_for_deletion:
          type: boolean
          description: Whether recording deletion was requested for the matched persons. If a deletion was already queued for a person, it will not be duplicated.
        deletion_errors:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Persons that could not be deleted. Each entry contains 'person_uuid'. Contact support if this persists.
      required:
      - events_queued_for_deletion
      - persons_deleted
      - persons_found
      - recordings_queued_for_deletion
    PropertyGroupOperator:
      enum:
      - AND
      - OR
      type: string
    PersonRecord:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Numeric person ID.
        name:
          type: string
          readOnly: true
          description: Display name derived from person properties (email, name, or username).
        distinct_ids:
          type: array
          items:
            type: string
          readOnly: true
        properties:
          description: Key-value map of person properties set via $set and $set_once operations.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When this person was first seen (ISO 8601).
        uuid:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier (UUID) for this person.
        last_seen_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Timestamp of the last event from this person, or null.
      required:
      - created_at
      - distinct_ids
      - id
      - last_seen_at
      - name
      - uuid
    PersonDeletePropertyRequest:
      type: object
      properties:
        $unset:
          type: string
          description: The property key to remove from this person.
      required:
      - $unset
    AsyncDeletionStatus:
      type: object
      properties:
        person_uuid:
          type: string
          description: The UUID of the person whose events are queued for deletion.
        created_at:
          type: string
          format: date-time
          description: When the deletion was requested.
        status:
          type: string
          readOnly: true
          description: 'Current status: ''pending'' or ''completed''.'
        delete_verified_at:
          type: string
          format: date-time
          nullable: true
          description: When the deletion was verified complete. Null if still pending.
      required:
      - created_at
      - delete_verified_at
      - person_uuid
      - status
    PropertyItem:
      type: object
      properties:
        key:
          type: string
          description: Key of the property you're filtering on. For example `email` or `$current_url`
        value:
          oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: array
            items:
              oneOf:
              - type: string
              - type: number
          description: Value of your filter. For example `test@example.com` or `https://example.com/test/`. Can be an array for an OR query, like `["test@example.com","ok@example.com"]`
        operator:
          nullable: true
          default: exact
          oneOf:
          - $ref: '#/components/schemas/PropertyItemOperatorEnum'
          - $ref: '#/components/schemas/BlankEnum'
          - $ref: '#/components/schemas/NullEnum'
        type:
          default: event
          oneOf:
          - $ref: '#/components/schemas/PropertyFilterTypeEnum'
          - $ref: '#/components/schemas/BlankEnum'
      required:
      - key
      - value
    BlankEnum:
      enum:
      - ''
    PersonBulkDeleteRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
          description: A list of PostHog person UUIDs to delete (max 1000).
        distinct_ids:
          type: array
          items:
            type: string
          description: A list of distinct IDs whose associated persons will be deleted (max 1000).
        delete_events:
          type: boolean
          default: false
          description: If true, queue deletion of all events associated with these persons.
        delete_recordings:
          type: boolean
          default: false
          description: If true, queue deletion of all recordings associated with these persons.
        keep_person:
          type: boolean
          default: false
          description: If true, keep the person records but delete their events and recordings.
    PropertyFilterTypeEnum:
      enum:
      - event
      - event_metadata
      - feature
      - person
      - cohort
      - element
      - static-cohort
      - dynamic-cohort
      - precalculated-cohort
      - group
      - recording
      - log_entry
      - behavioral
      - session
      - hogql
      - data_warehouse
      - data_warehouse_person_property
      - error_tracking_issue
      - log
      - log_attribute
      - log_resource_attribute
      - span
      - span_attribute
      - span_resource_attribute
      - revenue_analytics
      - flag
      - workflow_variable
      type: string
      description: '* `event` - event

        * `event_metadata` - event_metadata

        * `feature` - feature

        * `person` - person

        * `cohort` - cohort

        * `element` - element

        * `static-cohort` - static-cohort

        * `dynamic-cohort` - dynamic-cohort

        * `precalculated-cohort` - precalculated-cohort

        * `group` - group

        * `recording` - recording

        * `log_entry` - log_entry

        * `behavioral` - behavioral

        * `session` - session

        * `hogql` - hogql

        * `data_warehouse` - data_warehouse

        * `data_warehouse_person_property` - data_warehouse_person_property

        * `error_tracking_issue` - error_tracking_issue

        * `log` - log

        * `log_attribute` - log_attribute

        * `log_resource_attribute` - log_resource_attribute

        * `span` - span

        * `span_attribute` - span_attribute

        * `span_resource_attribute` - span_resource_attribute

        * `revenue_analytics` - revenue_analytics

        * `flag` - flag

        * `workflow_variable` - workflow_variable'
    PaginatedPersonRecordList:
      type: object
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: https://app.posthog.com/api/projects/{project_id}/accounts/?offset=400&limit=100
        count:
          type: integer
          example: 400
        results:
          type: array
          items:
            $ref: '#/components/schemas/PersonRecord'
    PersonPropertiesAtTimeDebug:
      type: object
      description: Serializer for the debug information (only available to staff users).
      properties:
        query:
          type: string
          description: The ClickHouse query that was executed
        params:
          type: object
          additionalProperties: true
          description: The parameters passed to the query
        events_found:
          type: integer
          description: Number of events found
        events:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Raw events that were used to build the properties
        error:
          type: string
          description: Error message if debug query failed
      required:
      - events
      - events_found
      - params
      - query
    PersonPropertiesAtTimeResponse:
      type: object
      description: Serializer for the point-in-time person properties response.
      properties:
        id:
          type: integer
          description: The person ID
        name:
          type: string
          description: The person's display name
        distinct_ids:
          type: array
          items:
            type: string
          description: All distinct IDs associated with this person
        properties:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: Person properties as they existed at the specified time
        created_at:
          type: string
          format: date-time
          description: When the person was first created
        uuid:
          type: string
          format: uuid
          description: The person's UUID
        last_seen_at:
          type: string
          format: date-time
          nullable: true
          description: When the person was last seen
        point_in_time_metadata:
          allOf:
          - $ref: '#/components/schemas/PersonPropertiesAtTimeMetadata'
          description: Metadata about the point-in-time query
        debug:
          allOf:
          - $ref: '#/components/schemas/PersonPropertiesAtTimeDebug'
          description: Debug information (only available when debug=true and DEBUG=True)
      required:
      - created_at
      - distinct_ids
      - id
      - last_seen_at
      - name
      - point_in_time_metadata
      - properties
      - uuid
  parameters:
    EnvironmentIdPath:
      in: path
      name: environment_id
      required: true
      schema:
        type: string
      description: Deprecated. Use /api/projects/{project_id}/ instead.
    ProjectIdPath:
      in: path
      name: project_id
      required: true
      schema:
        type: string
      description: Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
  securitySchemes:
    PersonalAPIKeyAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: All endpoints
  tags:
  - LLM Analytics
  - actions
  - activity_log
  - activity_logs
  - advanced_activity_logs
  - alerts
  - annotations
  - approval_policies
  - batch_exports
  - cdp
  - change_requests
  - code
  - code-invites
  - cohorts
  - comments
  - conversations
  - core
  - customer_analytics
  - customer_journeys
  - customer_profile_configs
  - dashboard_templates
  - dashboards
  - data_color_themes
  - data_modeling_jobs
  - data_warehouse
  - dataset_items
  - datasets
  - desktop_recordings
  - domains
  - early_access_feature
  - early_access_features
  - elements
  - endpoints
  - environments
  - error_tracking
  - evaluation_runs
  - evaluations
  - event_definitions
  - event_filter
  - event_schemas
  - events
  - experiment_holdouts
  - experiment_saved_metrics
  - experiments
  - exports
  - external_data_schemas
  - external_data_sources
  - feature_flags
  - file_system
  - file_system_shortcut
  - flag_value
  - groups
  - groups_types
  - health_issues
  - heatmap_screenshots
  - heatmaps
  - hog_flows
  - hog_function_templates
  - hog_functions
  - insight_variables
  - insights
  - integrations
  - invites
  - js-snippet
  - legal_documents
  - lineage
  - live_debugger_breakpoints
  - llm_analytics
  - llm_prompts
  - llm_skills
  - logs
  - managed_viewsets
  - max
  - max_tools
  - mcp_server_installations
  - mcp_servers
  - mcp_store
  - mcp_tools
  - members
  - notebooks
  - oauth_applications
  - object_media_previews
  - organizations
  - persisted_folder
  - persons
  - platform_features
  - plugin_configs
  - product_analytics
  - product_tours
  - project_secret_api_keys
  - projects
  - property_definitions
  - proxy_records
  - public_hog_function_templates
  - query
  - replay
  - reverse_proxy
  - role_external_references
  - roles
  - sandbox-environments
  - sandbox_environments
  - saved
  - schema_property_groups
  - sdk_doctor
  - session_group_summaries
  - session_recording_playlists
  - session_recordings
  - session_summaries
  - sessions
  - signals
  - subscriptions
  - surveys
  - taggers
  - task-automations
  - task-runs
  - task_automations
  - tasks
  - uploaded_media
  - user_home_settings
  - user_interviews
  - users
  - visual_review
  - warehouse_dag
  - warehouse_model_paths
  - warehouse_saved_queries
  - warehouse_saved_query_folders
  - warehouse_tables
  - warehouse_view_link
  - warehouse_view_links
  - web_analytics
  - web_experiments
  - web_vitals
  - welcome
  - workflows