openapi: 3.0.3 info: title: PostHog actions API version: 1.0.0 description: '' tags: - name: actions paths: /api/projects/{project_id}/actions/: get: operationId: actions_list 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 - $ref: '#/components/parameters/ProjectIdPath' tags: - actions security: - PersonalAPIKeyAuth: - action:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedActionList' text/csv: schema: $ref: '#/components/schemas/PaginatedActionList' description: '' x-explicit-tags: - actions post: operationId: actions_create parameters: - in: query name: format schema: type: string enum: - csv - json - $ref: '#/components/parameters/ProjectIdPath' tags: - actions requestBody: content: application/json: schema: $ref: '#/components/schemas/Action' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Action' multipart/form-data: schema: $ref: '#/components/schemas/Action' security: - PersonalAPIKeyAuth: - action:write responses: '201': content: application/json: schema: $ref: '#/components/schemas/Action' text/csv: schema: $ref: '#/components/schemas/Action' description: '' x-explicit-tags: - actions /api/projects/{project_id}/actions/{id}/: get: operationId: actions_retrieve 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 action. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - actions security: - PersonalAPIKeyAuth: - action:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/Action' text/csv: schema: $ref: '#/components/schemas/Action' description: '' x-explicit-tags: - actions put: operationId: actions_update 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 action. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - actions requestBody: content: application/json: schema: $ref: '#/components/schemas/Action' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Action' multipart/form-data: schema: $ref: '#/components/schemas/Action' security: - PersonalAPIKeyAuth: - action:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/Action' text/csv: schema: $ref: '#/components/schemas/Action' description: '' x-explicit-tags: - actions patch: operationId: actions_partial_update 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 action. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - actions requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedAction' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedAction' multipart/form-data: schema: $ref: '#/components/schemas/PatchedAction' security: - PersonalAPIKeyAuth: - action:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/Action' text/csv: schema: $ref: '#/components/schemas/Action' description: '' x-explicit-tags: - actions delete: operationId: actions_destroy description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true 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 action. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - actions security: - PersonalAPIKeyAuth: - action:write responses: '405': description: No response body x-explicit-tags: - actions /api/projects/{project_id}/actions/{id}/references/: get: operationId: actions_references_list 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 action. required: true - $ref: '#/components/parameters/ProjectIdPath' tags: - actions security: - PersonalAPIKeyAuth: - action:read responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/ActionReference' text/csv: schema: type: array items: $ref: '#/components/schemas/ActionReference' description: '' x-explicit-tags: - actions /api/projects/{project_id}/actions/bulk_update_tags/: post: operationId: actions_bulk_update_tags_create description: 'Bulk update tags on multiple objects. Accepts: - {"ids": [...], "action": "add"|"remove"|"set", "tags": ["tag1", "tag2"]} Actions: - "add": Add tags to existing tags on each object - "remove": Remove specific tags from each object - "set": Replace all tags on each object with the provided list' parameters: - in: query name: format schema: type: string enum: - csv - json - $ref: '#/components/parameters/ProjectIdPath' tags: - actions requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateTagsRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/BulkUpdateTagsRequest' multipart/form-data: schema: $ref: '#/components/schemas/BulkUpdateTagsRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BulkUpdateTagsResponse' text/csv: schema: $ref: '#/components/schemas/BulkUpdateTagsResponse' description: '' x-explicit-tags: - actions components: schemas: BulkUpdateTagsResponse: type: object properties: updated: type: array items: $ref: '#/components/schemas/BulkUpdateTagsItem' skipped: type: array items: $ref: '#/components/schemas/BulkUpdateTagsError' required: - skipped - updated ActionStepMatchingEnum: enum: - contains - regex - exact type: string description: '* `contains` - contains * `regex` - regex * `exact` - exact' RoleAtOrganizationEnum: enum: - engineering - data - product - founder - leadership - marketing - sales - other type: string description: '* `engineering` - Engineering * `data` - Data * `product` - Product Management * `founder` - Founder * `leadership` - Leadership * `marketing` - Marketing * `sales` - Sales / Success * `other` - Other' PatchedAction: type: object description: Serializer mixin that handles tags for objects. properties: id: type: integer readOnly: true name: type: string nullable: true description: Name of the action (must be unique within the project). maxLength: 400 description: type: string description: Human-readable description of what this action represents. tags: type: array items: {} post_to_slack: type: boolean description: Whether to post a notification to Slack when this action is triggered. slack_message_format: type: string description: Custom Slack message format. Supports templates with event properties. maxLength: 1200 steps: type: array items: $ref: '#/components/schemas/ActionStepJSON' description: Action steps defining trigger conditions. Each step matches events by name, properties, URL, or element attributes. Multiple steps are OR-ed together. created_at: type: string format: date-time readOnly: true created_by: allOf: - $ref: '#/components/schemas/UserBasic' readOnly: true deleted: type: boolean is_calculating: type: boolean readOnly: true last_calculated_at: type: string format: date-time team_id: type: integer readOnly: true is_action: type: boolean readOnly: true default: true bytecode_error: type: string readOnly: true nullable: true pinned_at: type: string format: date-time nullable: true description: ISO 8601 timestamp when the action was pinned, or null if not pinned. Set any value to pin, null to unpin. creation_context: type: string nullable: true readOnly: true _create_in_folder: type: string writeOnly: true title: ' create in folder' user_access_level: type: string nullable: true readOnly: true description: The effective access level the user has for this object NullEnum: enum: - null DatePropertyFilter: type: object description: Matches date/datetime values with date-specific operators. properties: key: type: string description: Key of the property you're filtering on. For example `email` or `$current_url`. type: allOf: - $ref: '#/components/schemas/PropertyFilterTypeEnum' default: event description: 'Property type (event, person, session, etc.). * `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' value: type: string description: Date or datetime string in ISO 8601 format (e.g. '2024-01-15' or '2024-01-15T10:30:00Z'). operator: allOf: - $ref: '#/components/schemas/DateOperatorEnum' default: is_date_exact description: 'Date comparison operator. * `is_date_exact` - is_date_exact * `is_date_before` - is_date_before * `is_date_after` - is_date_after' required: - key - value ActionStepJSON: type: object properties: event: type: string nullable: true description: Event name to match (e.g. '$pageview', '$autocapture', or a custom event name). properties: type: array items: $ref: '#/components/schemas/ActionStepPropertyFilter' nullable: true description: Event or person property filters. Each item should have 'key' (string), 'value' (string, number, boolean, or array), optional 'operator' (exact, is_not, is_set, is_not_set, icontains, not_icontains, regex, not_regex, gt, gte, lt, lte), and optional 'type' (event, person). selector: type: string nullable: true description: CSS selector to match the target element (e.g. 'div > button.cta'). selector_regex: type: string nullable: true readOnly: true tag_name: type: string nullable: true description: HTML tag name to match (e.g. "button", "a", "input"). text: type: string nullable: true description: Element text content to match. text_matching: nullable: true description: 'How to match the text value. Defaults to exact. * `contains` - contains * `regex` - regex * `exact` - exact' oneOf: - $ref: '#/components/schemas/ActionStepMatchingEnum' - $ref: '#/components/schemas/NullEnum' href: type: string nullable: true description: Link href attribute to match. href_matching: nullable: true description: 'How to match the href value. Defaults to exact. * `contains` - contains * `regex` - regex * `exact` - exact' oneOf: - $ref: '#/components/schemas/ActionStepMatchingEnum' - $ref: '#/components/schemas/NullEnum' url: type: string nullable: true description: Page URL to match. url_matching: nullable: true description: 'How to match the URL value. Defaults to contains. * `contains` - contains * `regex` - regex * `exact` - exact' oneOf: - $ref: '#/components/schemas/ActionStepMatchingEnum' - $ref: '#/components/schemas/NullEnum' required: - selector_regex UserBasic: type: object properties: id: type: integer readOnly: true uuid: type: string format: uuid readOnly: true distinct_id: type: string nullable: true maxLength: 200 first_name: type: string maxLength: 150 last_name: type: string maxLength: 150 email: type: string format: email title: Email address maxLength: 254 is_email_verified: type: boolean nullable: true hedgehog_config: type: object additionalProperties: true nullable: true readOnly: true role_at_organization: nullable: true oneOf: - $ref: '#/components/schemas/RoleAtOrganizationEnum' - $ref: '#/components/schemas/BlankEnum' - $ref: '#/components/schemas/NullEnum' required: - email - hedgehog_config - id - uuid ActionEnum: enum: - add - remove - set type: string description: '* `add` - add * `remove` - remove * `set` - set' BulkUpdateTagsRequest: type: object properties: ids: type: array items: type: integer description: List of object IDs to update tags on. maxItems: 500 action: allOf: - $ref: '#/components/schemas/ActionEnum' description: '''add'' merges with existing tags, ''remove'' deletes specific tags, ''set'' replaces all tags. * `add` - add * `remove` - remove * `set` - set' tags: type: array items: type: string description: Tag names to add, remove, or set. required: - action - ids - tags ExistenceOperatorEnum: enum: - is_set - is_not_set type: string description: '* `is_set` - is_set * `is_not_set` - is_not_set' ArrayPropertyFilterOperatorEnum: enum: - exact - is_not - in - not_in type: string description: '* `exact` - exact * `is_not` - is_not * `in` - in * `not_in` - not_in' ExistencePropertyFilter: type: object description: Checks whether a property is set or not, without comparing values. properties: key: type: string description: Key of the property you're filtering on. For example `email` or `$current_url`. type: allOf: - $ref: '#/components/schemas/PropertyFilterTypeEnum' default: event description: 'Property type (event, person, session, etc.). * `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' operator: allOf: - $ref: '#/components/schemas/ExistenceOperatorEnum' description: 'Existence check operator. * `is_set` - is_set * `is_not_set` - is_not_set' required: - key - operator ActionStepPropertyFilter: oneOf: - $ref: '#/components/schemas/StringPropertyFilter' - $ref: '#/components/schemas/NumericPropertyFilter' - $ref: '#/components/schemas/ArrayPropertyFilter' - $ref: '#/components/schemas/DatePropertyFilter' - $ref: '#/components/schemas/ExistencePropertyFilter' BulkUpdateTagsItem: type: object properties: id: type: integer tags: type: array items: type: string required: - id - tags NumericPropertyFilter: type: object description: Matches numeric values with comparison operators. properties: key: type: string description: Key of the property you're filtering on. For example `email` or `$current_url`. type: allOf: - $ref: '#/components/schemas/PropertyFilterTypeEnum' default: event description: 'Property type (event, person, session, etc.). * `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' value: type: number format: double description: Numeric value to compare against. operator: allOf: - $ref: '#/components/schemas/NumericPropertyFilterOperatorEnum' default: exact description: 'Numeric comparison operator. * `exact` - exact * `is_not` - is_not * `gt` - gt * `lt` - lt * `gte` - gte * `lte` - lte' required: - key - value NumericPropertyFilterOperatorEnum: enum: - exact - is_not - gt - lt - gte - lte type: string description: '* `exact` - exact * `is_not` - is_not * `gt` - gt * `lt` - lt * `gte` - gte * `lte` - lte' StringPropertyFilter: type: object description: Matches string values with text-oriented operators. properties: key: type: string description: Key of the property you're filtering on. For example `email` or `$current_url`. type: allOf: - $ref: '#/components/schemas/PropertyFilterTypeEnum' default: event description: 'Property type (event, person, session, etc.). * `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' value: type: string description: String value to match against. operator: allOf: - $ref: '#/components/schemas/StringMatchOperatorEnum' default: exact description: 'String comparison operator. * `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains * `regex` - regex * `not_regex` - not_regex' required: - key - value BlankEnum: enum: - '' BulkUpdateTagsError: type: object properties: id: type: integer reason: type: string required: - id - reason ActionReference: type: object properties: type: type: string description: 'Resource type: insight, experiment, cohort, or hog_function' id: type: string description: Resource ID (integer or UUID depending on type) name: type: string description: Resource name url: type: string description: Relative URL to the resource created_at: type: string format: date-time nullable: true description: When the resource was created created_by: allOf: - $ref: '#/components/schemas/UserBasic' nullable: true description: User who created the resource required: - created_at - created_by - id - name - type - url Action: type: object description: Serializer mixin that handles tags for objects. properties: id: type: integer readOnly: true name: type: string nullable: true description: Name of the action (must be unique within the project). maxLength: 400 description: type: string description: Human-readable description of what this action represents. tags: type: array items: {} post_to_slack: type: boolean description: Whether to post a notification to Slack when this action is triggered. slack_message_format: type: string description: Custom Slack message format. Supports templates with event properties. maxLength: 1200 steps: type: array items: $ref: '#/components/schemas/ActionStepJSON' description: Action steps defining trigger conditions. Each step matches events by name, properties, URL, or element attributes. Multiple steps are OR-ed together. created_at: type: string format: date-time readOnly: true created_by: allOf: - $ref: '#/components/schemas/UserBasic' readOnly: true deleted: type: boolean is_calculating: type: boolean readOnly: true last_calculated_at: type: string format: date-time team_id: type: integer readOnly: true is_action: type: boolean readOnly: true default: true bytecode_error: type: string readOnly: true nullable: true pinned_at: type: string format: date-time nullable: true description: ISO 8601 timestamp when the action was pinned, or null if not pinned. Set any value to pin, null to unpin. creation_context: type: string nullable: true readOnly: true _create_in_folder: type: string writeOnly: true title: ' create in folder' user_access_level: type: string nullable: true readOnly: true description: The effective access level the user has for this object required: - bytecode_error - created_at - created_by - creation_context - id - is_action - is_calculating - team_id - user_access_level ArrayPropertyFilter: type: object description: Matches against a list of values (OR semantics for exact/is_not, set membership for in/not_in). properties: key: type: string description: Key of the property you're filtering on. For example `email` or `$current_url`. type: allOf: - $ref: '#/components/schemas/PropertyFilterTypeEnum' default: event description: 'Property type (event, person, session, etc.). * `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' value: type: array items: type: string description: List of values to match. For example `["test@example.com", "ok@example.com"]`. operator: allOf: - $ref: '#/components/schemas/ArrayPropertyFilterOperatorEnum' default: exact description: 'Array comparison operator. * `exact` - exact * `is_not` - is_not * `in` - in * `not_in` - not_in' required: - key - value StringMatchOperatorEnum: enum: - exact - is_not - icontains - not_icontains - regex - not_regex type: string description: '* `exact` - exact * `is_not` - is_not * `icontains` - icontains * `not_icontains` - not_icontains * `regex` - regex * `not_regex` - not_regex' 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' PaginatedActionList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/Action' DateOperatorEnum: enum: - is_date_exact - is_date_before - is_date_after type: string description: '* `is_date_exact` - is_date_exact * `is_date_before` - is_date_before * `is_date_after` - is_date_after' parameters: 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