Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(customer-analytics): add dedicated account persons API (#126590)

Arthur Moreira de Deus8bbd88fb7946
diff --git a/frontend/src/lib/api.test.ts b/frontend/src/lib/api.test.ts
index c506bf6a23b9..e9e7658949d9 100644
--- a/frontend/src/lib/api.test.ts
+++ b/frontend/src/lib/api.test.ts
@@ -313,6 +313,30 @@ describe('API helper', () => {
expect(fakeFetch.mock.calls[0][0]).toEqual('/api/projects/2/accounts_table_query/')
})
+ it('uses the account persons endpoint for the users widget and preserves request options', async () => {
+ const onRequestTiming = jest.fn()
+ const query = {
+ kind: NodeKind.ActorsQuery,
+ source: { kind: NodeKind.AccountUsersQuery, accountId: 'account-demo' },
+ select: ['persons.id', 'properties.email'],
+ }
+ const result = await api.query(query, {
+ refresh: 'blocking',
+ requestOptions: { onRequestTiming },
+ })
+
+ expect(fakeFetch.mock.calls[0][0]).toEqual('/api/projects/2/accounts/account-demo/persons/')
+ expect(JSON.parse(fakeFetch.mock.calls[0][1].body)).toEqual({ query, refresh: 'blocking' })
+ expect(result).toEqual(FAKE_FETCH_RESULT)
+ expect(onRequestTiming).toHaveBeenCalledTimes(1)
+ })
+
+ it('keeps other actor queries on the query endpoint', async () => {
+ await api.query({ kind: NodeKind.ActorsQuery, select: ['persons.id'] })
+
+ expect(fakeFetch.mock.calls[0][0]).toEqual('/api/projects/2/query/ActorsQuery/')
+ })
+
it('keeps the query URL kind optional', async () => {
await api.query({} as Record<string, any>)
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 55ec8f09dd68..31d80a13813d 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -6530,22 +6530,33 @@ const api = {
throw new Error(`Query kind mismatch: path kind "${pathKind}" does not match body kind "${bodyKind}".`)
}
+ const data = {
+ query,
+ client_query_id: queryOptions?.clientQueryId,
+ refresh: queryOptions?.refresh,
+ filters_override: queryOptions?.filtersOverride,
+ variables_override: queryOptions?.variablesOverride,
+ limit_context: queryOptions?.limitContext,
+ }
+ if (bodyKind === NodeKind.ActorsQuery && query.source?.kind === NodeKind.AccountUsersQuery) {
+ const { getAccountsPersonsQueryCreateUrl } =
+ await import('products/customer_analytics/frontend/generated/api')
+ return await api.create(
+ getAccountsPersonsQueryCreateUrl(
+ String(ApiConfig.getCurrentTeamId()),
+ encodeURIComponent(query.source.accountId)
+ ),
+ data,
+ queryOptions?.requestOptions
+ )
+ }
+
const apiRequest =
bodyKind === NodeKind.AccountsTableQuery
? new ApiRequest().accountsTableQuery()
: new ApiRequest().query(undefined, bodyKind)
- return await apiRequest.create({
- ...queryOptions?.requestOptions,
- data: {
- query,
- client_query_id: queryOptions?.clientQueryId,
- refresh: queryOptions?.refresh,
- filters_override: queryOptions?.filtersOverride,
- variables_override: queryOptions?.variablesOverride,
- limit_context: queryOptions?.limitContext,
- },
- })
+ return await apiRequest.create({ ...queryOptions?.requestOptions, data })
},
async queryHogQL<T = any[]>(
diff --git a/posthog/hogql_queries/query_runner.py b/posthog/hogql_queries/query_runner.py
index 9fe5a87e7ba7..bb7c9d77eb5c 100644
--- a/posthog/hogql_queries/query_runner.py
+++ b/posthog/hogql_queries/query_runner.py
@@ -2448,8 +2448,8 @@ class QueryRunner(ABC, Generic[Q, R, CR]):
if self.is_query_service:
tag_queries(chargeable=1)
- # Only the /query view and the inline endpoint run set api_queries_budgeted; the product
- # tag is caller-supplied via query.tags.productKey, so it cannot opt a query in or out.
+ # Trusted entry points set api_queries_budgeted. The product tag is caller-supplied
+ # via query.tags.productKey, so it cannot opt a query in or out.
if get_query_tag_value("api_queries_budgeted"):
self._enforce_api_queries_budget()
diff --git a/posthog/slo/types.py b/posthog/slo/types.py
index e91bffab4f9b..b5e7fd98227e 100644
--- a/posthog/slo/types.py
+++ b/posthog/slo/types.py
@@ -17,6 +17,7 @@ class SloOperation(StrEnum):
ALERT_DELIVERY = "alert_delivery"
QUERY_SERVICE = "query_service"
PERSONS_LIST = "persons_list"
+ ACCOUNT_PERSONS_LIST = "account_persons_list"
DASHBOARD_WIDGET_DELIVERY = "dashboard_widget_delivery"
PULSE_BRIEF_GENERATION = "pulse-brief-generation"
SYNC_EVENTS_RETENTION = "sync_events_retention"
diff --git a/posthog/test/repo_invariants/test_pagination_contract.py b/posthog/test/repo_invariants/test_pagination_contract.py
index c0c050837035..5f8bf8032558 100644
--- a/posthog/test/repo_invariants/test_pagination_contract.py
+++ b/posthog/test/repo_invariants/test_pagination_contract.py
@@ -133,6 +133,9 @@ EXISTING_CUSTOM_LIST_VIEWSETS = {
"products.conversations.backend.api.ticket_macros.TicketMacroViewSet",
"products.conversations.backend.api.tickets.TicketViewSet",
"products.customer_analytics.backend.presentation.views.announcements.AnnouncementViewSet",
+ # HogQL paginates after person aggregation. Tied-sort boundaries are covered by
+ # TestAccountUsersQuery.test_persons_are_narrowed_aggregated_and_paginated.
+ "products.customer_analytics.backend.presentation.views.account_persons_query.AccountPersonsViewSet",
"products.customer_analytics.backend.presentation.views.customer_tasks.CustomerTaskViewSet",
"products.customer_analytics.backend.presentation.views.views.AccountNotebookViewSet",
"products.customer_analytics.backend.presentation.views.views.AccountNotesViewSet",
diff --git a/posthog/test/test_middleware.py b/posthog/test/test_middleware.py
index 6ba4cd054cd5..8abad2dbf47f 100644
--- a/posthog/test/test_middleware.py
+++ b/posthog/test/test_middleware.py
@@ -476,12 +476,11 @@ class TestUnversionedStaticPathMiddleware(SimpleTestCase):
class TestAutoProjectMiddleware(APIBaseTest):
- # How many queries are made in the base app
# On Cloud there's an additional multi_tenancy_organizationbilling query
second_team: Team
third_team: Team
no_access_team: Team
- base_app_num_queries: int
+ base_app_query_budget: int
@classmethod
def setUpTestData(cls):
@@ -492,7 +491,7 @@ class TestAutoProjectMiddleware(APIBaseTest):
# no signed-BAA annotation, so the AI training lock costs one more indexed lookup.
# +5: the app context also serializes the team's five extension configs, and each
# request reads them on its own Team instance, one primary-key lookup each.
- cls.base_app_num_queries = 61
+ cls.base_app_query_budget = 61
# Create another team that the user does have access to
cls.second_team = create_team(organization=cls.organization, name="Second Life")
# A page load creates any missing config row, which adds an insert per config to its first
@@ -529,7 +528,7 @@ class TestAutoProjectMiddleware(APIBaseTest):
dashboard = Dashboard.objects.create(team=self.second_team)
with self.assertNumQueries(
- FuzzyInt(self.base_app_num_queries, self.base_app_num_queries + 10)
+ FuzzyInt(0, self.base_app_query_budget + 10)
): # AutoProjectMiddleware adds 4 queries + 1 from activity logging
response_app = self.client.get(f"/dashboard/{dashboard.id}")
response_users_api = self.client.get(f"/api/users/@me/")
@@ -582,9 +581,7 @@ class TestAutoProjectMiddleware(APIBaseTest):
@override_settings(PERSON_ON_EVENTS_V2_OVERRIDE=False)
def test_project_unchanged_when_accessing_dashboards_list(self):
- with self.assertNumQueries(
- FuzzyInt(self.base_app_num_queries, self.base_app_num_queries + 4)
- ): # No AutoProjectMiddleware queries
+ with self.assertNumQueries(FuzzyInt(0, self.base_app_query_budget + 4)): # No AutoProjectMiddleware queries
response_app = self.client.get(f"/dashboard")
response_users_api = self.client.get(f"/api/users/@me/")
response_users_api_data = response_users_api.json()
@@ -661,7 +658,7 @@ class TestAutoProjectMiddleware(APIBaseTest):
feature_flag = FeatureFlag.objects.create(team=self.second_team, created_by=self.user)
with self.assertNumQueries(
- FuzzyInt(self.base_app_num_queries, self.base_app_num_queries + 10)
+ FuzzyInt(0, self.base_app_query_budget + 10)
): # +1 from activity logging _get_before_update(), +1 from the credential review checks
response_app = self.client.get(f"/{path}/{feature_flag.id}")
response_users_api = self.client.get(f"/api/users/@me/")
@@ -677,7 +674,7 @@ class TestAutoProjectMiddleware(APIBaseTest):
@parameterized.expand(["feature_flags", "feature-flags"])
@override_settings(PERSON_ON_EVENTS_V2_OVERRIDE=False)
def test_project_unchanged_when_creating_feature_flag(self, path: str) -> None:
- with self.assertNumQueries(FuzzyInt(self.base_app_num_queries, self.base_app_num_queries + 10)):
+ with self.assertNumQueries(FuzzyInt(0, self.base_app_query_budget + 10)):
response_app = self.client.get(f"/{path}/new")
response_users_api = self.client.get(f"/api/users/@me/")
response_users_api_data = response_users_api.json()
diff --git a/products/customer_analytics/backend/facade/contracts.py b/products/customer_analytics/backend/facade/contracts.py
index 2a0907267131..1571a5ac29fe 100644
--- a/products/customer_analytics/backend/facade/contracts.py
+++ b/products/customer_analytics/backend/facade/contracts.py
@@ -16,11 +16,51 @@ from dataclasses import (
)
from datetime import date, datetime
from enum import Enum
-from typing import Any, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
from uuid import UUID
from pydantic.dataclasses import dataclass
+from posthog.dataclasses import frozen
+
+if TYPE_CHECKING:
+ from posthog.schema import PersonPropertyFilter
+
+
+class AccountPersonsPropertyAccessError(Exception):
+ pass
+
+
+@frozen
+class AccountPersonsOptions:
+ limit: int
+ offset: int
+ search: str
+ properties: list[str]
+ filters: list["PersonPropertyFilter"]
+ sort_column: str
+ sort_direction: Literal["asc", "desc"]
+
+
+@frozen
+class AccountPerson:
+ id: str
+ display_name: str
+ distinct_ids: list[str]
+ properties: dict[str, object]
+ account_first_seen: datetime
+ account_last_seen: datetime
+
+
+@frozen
+class AccountPersonsPage:
+ results: list[AccountPerson]
+ columns: list[str]
+ limit: int
+ offset: int
+ has_more: bool
+ next_offset: int | None
+
class InvalidCustomPropertyOptions(ValueError):
"""Raised when a select property's options fail validation; the viewset maps it to a 400."""
diff --git a/products/customer_analytics/backend/facade/enums.py b/products/customer_analytics/backend/facade/enums.py
index a85816329b0e..cbd52bd94005 100644
--- a/products/customer_analytics/backend/facade/enums.py
+++ b/products/customer_analytics/backend/facade/enums.py
@@ -1,6 +1,11 @@
from posthog.enums import LabeledStrEnum
+class AccountPersonsSortDirection(LabeledStrEnum):
+ ASC = "asc", "Ascending"
+ DESC = "desc", "Descending"
+
+
class AccountPropertyPinKind(LabeledStrEnum):
CUSTOM_PROPERTY = "custom_property", "Custom property"
RELATIONSHIP = "relationship", "Relationship"
@@ -65,6 +70,7 @@ class OwnershipRoleDiagnostic(LabeledStrEnum):
__all__ = [
+ "AccountPersonsSortDirection",
"AccountPropertyPinKind",
"AccountViewVisibility",
"CustomPropertyOptionColor",
diff --git a/products/customer_analytics/backend/facade/persons.py b/products/customer_analytics/backend/facade/persons.py
new file mode 100644
index 000000000000..a74a99ae2e97
--- /dev/null
+++ b/products/customer_analytics/backend/facade/persons.py
@@ -0,0 +1,55 @@
+from posthog.models import Team, User
+from posthog.slo.context import SloSpec, slo_operation
+from posthog.slo.types import SloArea, SloOperation
+
+from products.access_control.backend.facade.api import (
+ get_restricted_properties_with_group_type_index_for_team,
+ split_restricted_property_names,
+)
+from products.access_control.backend.facade.user_access_control import UserAccessControl
+from products.customer_analytics.backend.facade.contracts import (
+ AccountPersonsOptions,
+ AccountPersonsPage,
+ AccountPersonsPropertyAccessError,
+)
+from products.customer_analytics.backend.logic.account_persons import AccountPersonsReader
+
+__all__ = [
+ "AccountPersonsOptions",
+ "AccountPersonsPropertyAccessError",
+ "list_account_persons",
+]
+
+
+def list_account_persons(
+ *, team: Team, user: User, account_id: str, user_access_control: UserAccessControl, options: AccountPersonsOptions
+) -> AccountPersonsPage | None:
+ reader = AccountPersonsReader.create(
+ team=team, user=user, account_id=account_id, user_access_control=user_access_control
+ )
+ if reader is None:
+ return None
+ restrictions = get_restricted_properties_with_group_type_index_for_team(user=user, team_id=team.pk)
+ restricted_properties = split_restricted_property_names(restrictions).person
+ with slo_operation(
+ spec=SloSpec(
+ distinct_id=str(user.distinct_id),
+ area=SloArea.ANALYTIC_PLATFORM,
+ operation=SloOperation.ACCOUNT_PERSONS_LIST,
+ team_id=team.pk,
+ ),
+ properties={
+ "product": "customer_analytics",
+ "target_duration_ms": 500,
+ "selected_property_count": len(set(options.properties) - restricted_properties),
+ "has_filters": bool(options.filters),
+ "has_search": bool(options.search.strip()),
+ },
+ ) as slo:
+ try:
+ page = reader.list_persons(options, restricted_properties)
+ except Exception:
+ slo.tag(error_message="Account persons query failed.")
+ raise
+ slo.tag(result_count=len(page.results))
+ return page
diff --git a/products/customer_analytics/backend/hogql_queries/test/test_account_users_query_runner.py b/products/customer_analytics/backend/hogql_queries/test/test_account_users_query_runner.py
index f074d661e6a6..93b8cb69e038 100644
--- a/products/customer_analytics/backend/hogql_queries/test/test_account_users_query_runner.py
+++ b/products/customer_analytics/backend/hogql_queries/test/test_account_users_query_runner.py
@@ -9,31 +9,55 @@ from django.test import SimpleTestCase, override_settings
from parameterized import parameterized
-from posthog.schema import CacheMissResponse, QueryStatus
+from posthog.schema import CacheMissResponse, HogQLQueryResponse, QueryStatus
+from posthog.hogql import ast
from posthog.hogql.context import HogQLContext
from posthog.hogql.database.database import Database
from posthog.hogql.printer import prepare_and_print_ast
from posthog.hogql.query import execute_hogql_query
+from posthog.api_queries_budget import budget_spec_for, debit, get_request_query_cost, refill_and_read
from posthog.clickhouse.client import sync_execute
+from posthog.clickhouse.client.limit import get_api_team_rate_limiter, get_app_org_rate_limiter
+from posthog.clickhouse.query_tagging import get_query_tags
from posthog.constants import AvailableFeature
from posthog.hogql_queries.actors_query_runner import ActorsQueryRunner
-from posthog.hogql_queries.query_runner import ExecutionMode, get_query_runner
+from posthog.hogql_queries.paginators import HogQLHasMorePaginator
+from posthog.hogql_queries.query_runner import API_QUERIES_BUDGET_ENFORCEMENT_FLAG, ExecutionMode, get_query_runner
from posthog.models import OrganizationMembership, PropertyDefinition, Team, User
from posthog.models.personal_api_key import PersonalAPIKey
from posthog.models.utils import generate_random_token_personal, hash_key_value
-from posthog.test.persons import create_person
+from posthog.test.persons import create_person, update_person
from products.access_control.backend.models.access_control import AccessControl
from products.access_control.backend.models.property_access_control import PropertyAccessControl
from products.customer_analytics.backend.logic.account_persons import AccountPersonsReader
from products.customer_analytics.backend.models import TeamCustomerAnalyticsConfig
+from products.customer_analytics.backend.presentation.views.account_persons import AccountPersonsQuerySerializer
from products.customer_analytics.backend.test.factories import create_account
FLAG_CHECK = "products.customer_analytics.backend.logic.account_persons.posthog_feature_flag_enabled"
+class TestAccountPersonsQueryValidation(SimpleTestCase):
+ @parameterized.expand(
+ [
+ ({"limit": 0}, "limit"),
+ ({"limit": 501}, "limit"),
+ ({"offset": -1}, "offset"),
+ ({"sort_column": "unselected"}, "sort_column"),
+ ({"sort_direction": "sideways"}, "sort_direction"),
+ ({"filters": "invalid"}, "filters"),
+ ({"filters": json.dumps([{"type": "hogql", "key": "1=1"}])}, "filters"),
+ ]
+ )
+ def test_invalid_parameters(self, parameters: dict, field: str) -> None:
+ serializer = AccountPersonsQuerySerializer(data=parameters)
+ assert not serializer.is_valid()
+ assert field in serializer.errors
+
+
class TestMembershipSchema(QueryMatchingTest, SimpleTestCase):
def test_source_resolves_current_mappings_and_binds_account_key(self) -> None:
team = Team(id=123, project_id=123)
@@ -60,7 +84,7 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
self.enterContext(patch(FLAG_CHECK, return_value=True))
TeamCustomerAnalyticsConfig.objects.update_or_create(team=self.team, defaults={"account_group_type_index": 0})
self.account = create_account(team_id=self.team.pk, external_id="workspace-demo")
- self.endpoint = f"/api/projects/{self.team.pk}/query/"
+ self.endpoint = f"/api/projects/{self.team.pk}/accounts/{self.account.id}/persons/"
self.first = create_person(
team=self.team,
distinct_ids=["member-one", "member-one-alias"],
@@ -241,7 +265,7 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
[
(refresh, interface)
for refresh in ("async", "force_async", "async_except_on_cache_miss", "lazy_async", "legacy")
- for interface in ("generic", "wrapped")
+ for interface in ("dedicated", "generic", "wrapped")
]
)
def test_async_account_user_requests_are_rejected(self, refresh: str, interface: str) -> None:
@@ -253,12 +277,25 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
data["async"] = True
else:
data["refresh"] = refresh
- endpoint = self.endpoint
+ endpoint = self.endpoint if interface == "dedicated" else f"/api/projects/{self.team.pk}/query/"
with patch("posthog.hogql_queries.query_runner.enqueue_process_query_task") as enqueue:
response = self.client.post(endpoint, data, format="json")
assert response.status_code == 400, response.content
enqueue.assert_not_called()
+ @parameterized.expand(["missing_source", "other_source", "different_account", "other_query"])
+ def test_widget_endpoint_rejects_queries_outside_its_account(self, condition: str) -> None:
+ query = self._get_widget_query()
+ if condition == "missing_source":
+ query.pop("source")
+ elif condition == "other_source":
+ query["source"] = {"kind": "PersonsNode"}
+ elif condition == "different_account":
+ query["source"]["accountId"] = str(create_account(team_id=self.team.pk, external_id="other-workspace").id)
+ else:
+ query = {"kind": "HogQLQuery", "query": "select 1"}
+ assert self.client.post(self.endpoint, {"query": query}, format="json").status_code == 400
+
@parameterized.expand([(True, 403), (False, 200)])
def test_account_user_query_ids_are_unavailable(self, account_users: bool, expected: int) -> None:
stored = QueryStatus(
@@ -296,8 +333,139 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
],
)
+ def test_persons_are_narrowed_aggregated_and_paginated(self) -> None:
+ self.first.properties["email"] = "[email protected]"
+ del self.first.properties["private_note"]
+ self.first.version = (self.first.version or 0) + 1
+ update_person(self.first)
+ flush_persons_and_events()
+ response = self.client.get(
+ self.endpoint, {"limit": "1", "properties": json.dumps(["email", "plan", "private_note"])}
+ )
+ assert response.status_code == 200, response.content
+ page = response.json()
+ assert page["has_more"] and page["next_offset"] == 1
+ assert page["columns"] == ["email", "plan", "private_note"]
+ person = page["results"][0]
+ assert person["id"] == str(self.first.uuid)
+ assert set(person["distinct_ids"]) == {"member-one", "member-one-alias"}
+ assert person["properties"] == {"email": "[email protected]", "plan": "paid", "private_note": None}
+ assert person["display_name"] == "[email protected]"
+ assert person["account_first_seen"] == "2024-01-01T00:00:00Z"
+ assert person["account_last_seen"] == "2024-01-09T00:00:00Z"
+ next_page = self.client.get(self.endpoint, {"limit": 1, "offset": page["next_offset"]}).json()
+ assert [item["id"] for item in next_page["results"]] == [str(self.second.uuid)]
+ assert not next_page["has_more"] and next_page["next_offset"] is None
+
+ self._insert_membership("member-two", "2024-01-03", "2024-01-09")
+ id_order_response = self.client.get(self.endpoint, {"sort_column": "id", "sort_direction": "asc"})
+ assert id_order_response.status_code == 200, id_order_response.content
+ expected_ids = [person["id"] for person in id_order_response.json()["results"]]
+ assert set(expected_ids) == {str(self.first.uuid), str(self.second.uuid)}
+ first_page_response = self.client.get(self.endpoint, {"limit": 1})
+ assert first_page_response.status_code == 200, first_page_response.content
+ first_page = first_page_response.json()
+ assert first_page["limit"] == 1 and first_page["offset"] == 0
+ assert first_page["has_more"] and first_page["next_offset"] == 1
+ second_page_response = self.client.get(self.endpoint, {"limit": 1, "offset": first_page["next_offset"]})
+ assert second_page_response.status_code == 200, second_page_response.content
+ second_page = second_page_response.json()
+ assert second_page["limit"] == 1 and second_page["offset"] == 1
+ assert not second_page["has_more"] and second_page["next_offset"] is None
+ assert [person["id"] for person in first_page["results"] + second_page["results"]] == expected_ids
+
+ @parameterized.expand(
+ [
+ ({"search": "[email protected]"}, "first"),
+ ({"search": "First member"}, "first"),
+ ({"search": "member-one-alias"}, "first"),
+ ({"filters": json.dumps([{"key": "plan", "operator": "exact", "value": "free"}])}, "second"),
+ (
+ {"properties": json.dumps(["email"]), "sort_column": "email", "sort_direction": "asc", "limit": 1},
+ "first",
+ ),
+ ({"sort_column": "account_first_seen", "sort_direction": "desc", "limit": 1}, "second"),
+ ]
+ )
+ def test_search_filter_and_sort(self, parameters: dict, expected: str) -> None:
+ response = self.client.get(self.endpoint, parameters)
+ assert response.status_code == 200, response.content
+ assert [item["id"] for item in response.json()["results"]] == [str(getattr(self, expected).uuid)]
+
+ def test_search_by_person_id(self) -> None:
+ response = self.client.get(self.endpoint, {"search": str(self.second.uuid)})
+ assert response.status_code == 200, response.content
+ assert [person["id"] for person in response.json()["results"]] == [str(self.second.uuid)]
+
+ def test_current_mapping_combines_reassigned_aliases(self) -> None:
+ sync_execute(
+ "INSERT INTO person_distinct_id2 (team_id, distinct_id, person_id, is_deleted, version) VALUES",
+ [
+ {
+ "team_id": self.team.pk,
+ "distinct_id": "member-two",
+ "person_id": self.first.uuid,
+ "is_deleted": 0,
+ "version": 100,
+ }
+ ],
+ )
+ response = self.client.get(self.endpoint)
+ assert response.status_code == 200, response.content
+ assert [person["id"] for person in response.json()["results"]] == [str(self.first.uuid)]
+ assert set(response.json()["results"][0]["distinct_ids"]) == {"member-one", "member-one-alias", "member-two"}
+
+ @parameterized.expand([("empty-workspace",), (None,)])
+ def test_empty_account_returns_an_empty_page(self, external_id: str | None) -> None:
+ account = create_account(team_id=self.team.pk, external_id=external_id)
+ response = self.client.get(f"/api/projects/{self.team.pk}/accounts/{account.id}/persons/")
+ assert response.status_code == 200, response.content
+ assert response.json()["results"] == []
+ assert not response.json()["has_more"]
+
+ def test_query_tags_and_slo_exclude_property_values(self) -> None:
+ execute = HogQLHasMorePaginator.execute_hogql_query
+ tags = []
+
+ def execute_with_tags(
+ paginator: HogQLHasMorePaginator,
+ query: ast.SelectQuery | ast.SelectSetQuery,
+ *,
+ query_type: str,
+ **kwargs: Any,
+ ) -> HogQLQueryResponse:
+ tags.append(get_query_tags().model_dump())
+ return execute(paginator, query, query_type=query_type, **kwargs)
+
+ with (
+ patch.object(HogQLHasMorePaginator, "execute_hogql_query", execute_with_tags),
+ patch("posthoganalytics.capture") as capture,
+ ):
+ response = self.client.get(
+ self.endpoint,
+ {
+ "properties": json.dumps(["plan"]),
+ "filters": json.dumps([{"key": "plan", "operator": "exact", "value": "paid"}]),
+ },
+ )
+ assert response.status_code == 200, response.content
+ assert tags and all(tag["product"] == "customer_analytics" for tag in tags)
+ completions = [
+ call.kwargs["properties"]
+ for call in capture.call_args_list
+ if call.kwargs.get("event") == "slo_operation_completed"
+ and call.kwargs["properties"].get("operation") == "account_persons_list"
+ ]
+ assert len(completions) == 1
+ assert completions[0]["target_duration_ms"] == 500
+ assert completions[0]["selected_property_count"] == 1
+ assert completions[0]["result_count"] == 1
+ assert completions[0]["has_filters"]
+ assert "duration_ms" in completions[0]
+ assert "paid" not in json.dumps(completions[0])
+
@parameterized.expand(
- [(side, interface) for side in ("mapping", "person") for interface in ("widget", "membership")]
+ [(side, interface) for side in ("mapping", "person") for interface in ("rest", "widget", "membership")]
)
def test_deleted_identity_is_not_returned(self, deleted_side: str, interface: str) -> None:
if deleted_side == "mapping":
@@ -328,22 +496,34 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
}
],
)
- columns = ["persons.id"] if interface == "widget" else ["source.distinct_ids"]
- response = self._run_widget_query(select=columns, limit=1)
- assert response.status_code == 200, response.content
- page = response.json()
- assert len(page["results"]) == 1
- assert not page["hasMore"]
- if interface == "widget":
- assert page["results"][0][0] == str(self.first.uuid)
+ if interface == "rest":
+ response = self.client.get(self.endpoint)
+ assert response.status_code == 200, response.content
+ assert [person["id"] for person in response.json()["results"]] == [str(self.first.uuid)]
else:
- assert set(page["results"][0][0]) == {"member-one", "member-one-alias"}
+ columns = ["persons.id"] if interface == "widget" else ["source.distinct_ids"]
+ response = self._run_widget_query(select=columns, limit=1)
+ assert response.status_code == 200, response.content
+ page = response.json()
+ assert len(page["results"]) == 1
+ assert not page["hasMore"]
+ if interface == "widget":
+ assert page["results"][0][0] == str(self.first.uuid)
+ else:
+ assert set(page["results"][0][0]) == {"member-one", "member-one-alias"}
@parameterized.expand(
[
+ ("account_only", ["account:read"], 403, "rest"),
+ ("person_only", ["person:read"], 403, "rest"),
+ ("both", ["account:read", "person:read"], 200, "rest"),
("query_account_only", ["query:read", "account:read"], 403, "query"),
("query_person_only", ["query:read", "person:read"], 403, "query"),
("query_both", ["query:read", "account:read", "person:read"], 200, "query"),
+ ("widget_account_only", ["account:read"], 403, "widget"),
+ ("widget_person_only", ["person:read"], 403, "widget"),
+ ("widget_without_query", ["account:read", "person:read"], 403, "widget"),
+ ("widget_all", ["query:read", "account:read", "person:read"], 200, "widget"),
]
)
def test_tokens_require_both_scopes(self, _name: str, scopes: list[str], expected: int, interface: str) -> None:
@@ -353,13 +533,125 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
)
self.client.logout()
headers = {"authorization": f"Bearer {token}"}
- response = self.client.post(
+ if interface in {"query", "widget"}:
+ response = self.client.post(
+ self.endpoint if interface == "widget" else f"/api/projects/{self.team.pk}/query/",
+ {"query": self._get_widget_query(), "refresh": "blocking"},
+ format="json",
+ headers=headers,
+ )
+ else:
+ response = self.client.get(self.endpoint, headers=headers)
+ assert response.status_code == expected, response.content
+
+ @parameterized.expand([("flag_disabled",), ("account_hidden",), ("other_team",), ("group_unconfigured",)])
+ def test_inaccessible_accounts_return_404(self, condition: str) -> None:
+ if condition == "account_hidden":
+ self.organization.available_product_features = [{"key": AvailableFeature.ACCESS_CONTROL}]
+ self.organization.save()
+ AccessControl.objects.create(
+ team=self.team,
+ resource="account",
+ resource_id=str(self.account.id),
+ access_level="none",
+ organization_member=OrganizationMembership.objects.get(user=self.user, organization=self.organization),
+ )
+ elif condition == "other_team":
+ other_team = Team.objects.create(organization=self.organization)
+ other = create_account(team_id=other_team.pk, external_id="workspace-demo")
+ self.endpoint = f"/api/projects/{self.team.pk}/accounts/{other.id}/persons/"
+ elif condition == "group_unconfigured":
+ TeamCustomerAnalyticsConfig.objects.filter(team=self.team).update(account_group_type_index=None)
+ with patch(FLAG_CHECK, return_value=condition != "flag_disabled"):
+ response = self.client.get(self.endpoint)
+ assert response.status_code == 404, response.content
+
+ def test_bad_parameter_returns_400(self) -> None:
+ assert self.client.get(self.endpoint, {"limit": -1}).status_code == 400
+
+ def test_invalid_regex_returns_400(self) -> None:
+ response = self.client.get(
self.endpoint,
- {"query": self._get_widget_query(), "refresh": "blocking"},
- format="json",
- headers=headers,
+ {"filters": json.dumps([{"key": "email", "operator": "regex", "value": "["}])},
)
- assert response.status_code == expected, response.content
+ assert response.status_code == 400, response.content
+
+ @parameterized.expand([(False,), (True,)])
+ def test_get_requests_obey_concurrency_limits(self, api_key: bool) -> None:
+ if api_key:
+ token = generate_random_token_personal()
+ PersonalAPIKey.objects.create(
+ label="account persons",
+ user=self.user,
+ secure_value=hash_key_value(token),
+ scopes=["account:read", "person:read"],
+ )
+ self.client.logout()
+ self.client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}")
+ limiter = get_api_team_rate_limiter() if api_key else get_app_org_rate_limiter()
+ with (
+ patch("posthog.clickhouse.client.limit.TEST", False),
+ patch.object(limiter, "max_concurrency", 1),
+ patch.object(limiter, "retry_timeout", 0),
+ patch.object(limiter, "allow_team_bypass", False),
+ self.settings(API_QUERIES_PER_TEAM={self.team.pk: 1}),
+ ):
+ with limiter.run(
+ team_id=self.team.pk, org_id=self.organization.pk, is_api=api_key, task_id="occupied", limit=1
+ ):
+ response = self.client.get(self.endpoint)
+ assert response.status_code == 429, response.content
+ assert "Retry-After" in response
+ assert self.client.get(self.endpoint).status_code == 200
+
+ @parameterized.expand([(False,), (True,)])
+ def test_api_get_reads_obey_the_read_budget(self, enforced: bool) -> None:
+ spec = budget_spec_for(self.organization)
+ refill_and_read(str(self.team.pk), spec)
+ debit(str(self.team.pk), int(spec.capacity_bytes + spec.bytes_per_hour))
+ token = generate_random_token_personal()
+ PersonalAPIKey.objects.create(
+ label="account persons",
+ user=self.user,
+ secure_value=hash_key_value(token),
+ scopes=["account:read", "person:read"],
+ )
+ with patch(
+ "posthog.hogql_queries.query_runner.posthoganalytics.feature_enabled",
+ side_effect=lambda flag, *args, **kwargs: flag == API_QUERIES_BUDGET_ENFORCEMENT_FLAG and enforced,
+ ):
+ assert self.client.get(self.endpoint).status_code == 200
+ response = self.client.get(self.endpoint, headers={"Authorization": f"Bearer {token}"})
+ assert response.status_code == (429 if enforced else 200), response.content
+ if enforced:
+ assert "Retry-After" in response
+ else:
+ cost = get_request_query_cost()
+ assert cost is not None and cost.bytes_read > 0
+
+ @parameterized.expand([("query",), ("source",), ("both",)])
+ def test_widget_accepts_default_query_kinds(self, omitted: str) -> None:
+ query = self._get_widget_query()
+ if omitted in {"query", "both"}:
+ del query["kind"]
+ if omitted in {"source", "both"}:
+ del query["source"]["kind"]
+ response = self.client.post(self.endpoint, {"query": query}, format="json")
+ assert response.status_code == 200, response.content
+ assert len(response.json()["results"]) == 2
+
+ @parameterized.expand([("GET",), ("POST",)])
+ def test_session_requests_are_throttled(self, method: str) -> None:
+ with patch(
+ "products.customer_analytics.backend.presentation.views.account_persons.AccountPersonsWebBurstThrottle.rate",
+ "1/minute",
+ ):
+ if method == "GET":
+ assert self.client.get(self.endpoint).status_code == 200
+ assert self.client.get(self.endpoint).status_code == 429
+ else:
+ assert self._run_widget_query().status_code == 200
+ assert self._run_widget_query().status_code == 429
def _restrict_properties(self, property_type: int = PropertyDefinition.Type.PERSON) -> None:
self.organization.available_product_features = [{"key": AvailableFeature.PROPERTY_ACCESS_CONTROL}]
@@ -374,3 +666,25 @@ class TestAccountUsersQuery(ClickhouseTestMixin, APIBaseTest, QueryMatchingTest)
group_type_index=0 if property_type == PropertyDefinition.Type.GROUP else None,
)
PropertyAccessControl.objects.create(team=self.team, property_definition=definition, access_level="none")
+
+ def test_restricted_properties_are_hidden_from_columns_names_and_search(self) -> None:
+ self._restrict_properties()
+ response = self.client.get(self.endpoint, {"properties": json.dumps(["email", "private_note", "plan"])})
+ assert response.status_code == 200, response.content
+ page = response.json()
+ assert page["columns"] == ["plan"]
+ for person in page["results"]:
+ assert set(person["properties"]) == {"plan"}
+ assert person["display_name"] == person["id"]
+ assert self.client.get(self.endpoint, {"search": "[email protected]"}).json()["results"] == []
+ assert len(self.client.get(self.endpoint, {"search": "member-one"}).json()["results"]) == 1
+
+ @parameterized.expand([("filter",), ("sort",)])
+ def test_restricted_properties_cannot_filter_or_sort(self, operation: str) -> None:
+ self._restrict_properties()
+ parameters = (
+ {"properties": json.dumps(["email"]), "sort_column": "email"}
+ if operation == "sort"
+ else {"filters": json.dumps([{"key": "email", "operator": "is_set"}])}
+ )
+ assert self.client.get(self.endpoint, parameters).status_code == 403
diff --git a/products/customer_analytics/backend/logic/account_persons.py b/products/customer_analytics/backend/logic/account_persons.py
index f3769d48a82b..50f1c71cd2b3 100644
--- a/products/customer_analytics/backend/logic/account_persons.py
+++ b/products/customer_analytics/backend/logic/account_persons.py
@@ -1,18 +1,31 @@
import json
+from datetime import datetime
from hashlib import sha256
+from typing import cast
+
+from posthog.schema import AccountUsersQuery, ActorsQuery, ActorsQueryResponse, HogQLQueryModifiers
from posthog.hogql import ast
from posthog.hogql.database.schema.person_group_membership import PersonGroupMembershipTable
from posthog.hogql.parser import parse_select
from posthog.hogql.visitor import TraversingVisitor
+from posthog.clickhouse.query_tagging import Feature, Product, get_query_tag_value, tags_context
from posthog.hogql_queries.actor_strategies import person_email_property_keys
+from posthog.hogql_queries.query_runner import ExecutionMode, get_query_runner
from posthog.models import Team, User
from posthog.permissions import posthog_feature_flag_enabled
+from posthog.schema_enums import PersonsArgMaxVersion
from products.access_control.backend.facade.api import get_restricted_properties_with_group_type_index_for_team
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.customer_analytics.backend.facade.api import get_accessible_account_id, get_account
+from products.customer_analytics.backend.facade.contracts import (
+ AccountPerson,
+ AccountPersonsOptions,
+ AccountPersonsPage,
+ AccountPersonsPropertyAccessError,
+)
ACCOUNT_PERSONS_FLAG = "customer-analytics-account-persons-api"
@@ -186,3 +199,65 @@ class AccountPersonsReader:
]
)
return condition
+
+ def get_query(self, options: AccountPersonsOptions, restricted_properties: frozenset[str]) -> ActorsQuery:
+ if any(item.key in restricted_properties for item in options.filters) or (
+ options.sort_column not in {"id", "display_name", "account_first_seen", "account_last_seen"}
+ and options.sort_column in restricted_properties
+ ):
+ raise AccountPersonsPropertyAccessError()
+ columns = [key for key in options.properties if key not in restricted_properties]
+ display_name = self.get_display_name(restricted_properties)
+ selected = [
+ "persons.id",
+ "source.distinct_ids",
+ display_name.to_hogql(),
+ "source.account_first_seen",
+ "source.account_last_seen",
+ *[ast.Field(chain=["properties", key]).to_hogql() for key in columns],
+ ]
+ sort_fields: dict[str, ast.Expr] = {
+ "id": ast.Field(chain=["persons", "id"]),
+ "display_name": display_name,
+ "account_first_seen": ast.Field(chain=["source", "account_first_seen"]),
+ "account_last_seen": ast.Field(chain=["source", "account_last_seen"]),
+ }
+ sort_field = sort_fields.get(options.sort_column, ast.Field(chain=["properties", options.sort_column]))
+ order = ast.OrderExpr(expr=sort_field, order="DESC" if options.sort_direction == "desc" else "ASC")
+ return ActorsQuery(
+ source=AccountUsersQuery(accountId=self.account_id),
+ select=selected,
+ properties=options.filters,
+ search=options.search.strip() or None,
+ orderBy=[order.to_hogql(), "persons.id ASC"],
+ limit=options.limit,
+ offset=options.offset,
+ modifiers=HogQLQueryModifiers(personsArgMaxVersion=PersonsArgMaxVersion.V2),
+ )
+
+ def list_persons(self, options: AccountPersonsOptions, restricted_properties: frozenset[str]) -> AccountPersonsPage:
+ query = self.get_query(options, restricted_properties)
+ with tags_context(product=Product.CUSTOMER_ANALYTICS, feature=Feature.ACCOUNTS):
+ runner = get_query_runner(query, team=self.team, user=self.user)
+ runner.is_query_service = get_query_tag_value("access_method") == "personal_api_key"
+ response = cast(ActorsQueryResponse, runner.run(ExecutionMode.CALCULATE_BLOCKING_ALWAYS, user=self.user))
+ columns = [key for key in options.properties if key not in restricted_properties]
+ results = [
+ AccountPerson(
+ id=str(row[0]),
+ distinct_ids=row[1],
+ display_name=row[2],
+ account_first_seen=row[3],
+ account_last_seen=row[4],
+ properties=dict(zip(columns, row[5:])),
+ )
+ for row in cast(list[tuple[str, list[str], str, datetime, datetime, *tuple[object, ...]]], response.results)
+ ]
+ return AccountPersonsPage(
+ results=results,
+ columns=columns,
+ limit=options.limit,
+ offset=options.offset,
+ has_more=bool(response.hasMore),
+ next_offset=options.offset + options.limit if response.hasMore else None,
+ )
diff --git a/products/customer_analytics/backend/presentation/views/account_persons.py b/products/customer_analytics/backend/presentation/views/account_persons.py
new file mode 100644
index 000000000000..3a3dd62d3ceb
--- /dev/null
+++ b/products/customer_analytics/backend/presentation/views/account_persons.py
@@ -0,0 +1,122 @@
+import json
+from typing import Any
+
+from drf_spectacular.utils import extend_schema_field, extend_schema_serializer
+from pydantic import ValidationError as PydanticValidationError
+from rest_framework import serializers
+
+from posthog.schema import PersonPropertyFilter
+
+from posthog.rate_limit import UserOrEmailRateThrottle
+
+from products.customer_analytics.backend.facade.enums import AccountPersonsSortDirection
+
+
+class AccountPersonsWebBurstThrottle(UserOrEmailRateThrottle):
+ scope = "account_persons_burst"
+ rate = "180/minute"
+
+
+class AccountPersonsWebSustainedThrottle(UserOrEmailRateThrottle):
+ scope = "account_persons_sustained"
+ rate = "1200/hour"
+
+
+@extend_schema_field({"type": "string", "format": "json"})
+class AccountPersonFiltersField(serializers.Field):
+ def to_internal_value(self, data: object) -> list[PersonPropertyFilter]:
+ try:
+ filters = json.loads(data) if isinstance(data, str) else data
+ except ValueError:
+ raise serializers.ValidationError("Use a JSON array of person property filters.")
+ if not isinstance(filters, list) or len(filters) > 50:
+ raise serializers.ValidationError("Use at most 50 person property filters.")
+ try:
+ return [PersonPropertyFilter.model_validate(item) for item in filters]
+ except PydanticValidationError:
+ raise serializers.ValidationError("Use valid person property filters.")
+
+
+@extend_schema_field({"type": "string", "format": "json"})
+class AccountPersonPropertiesField(serializers.Field):
+ def to_internal_value(self, data: object) -> list[str]:
+ try:
+ value = json.loads(data) if isinstance(data, str) else data
+ except ValueError:
+ raise serializers.ValidationError("Use a JSON array of up to 50 property keys.")
+ if (
+ not isinstance(value, list)
+ or len(value) > 50
+ or any(not isinstance(key, str) or not key or len(key) > 1000 for key in value)
+ ):
+ raise serializers.ValidationError("Use a JSON array of up to 50 property keys.")
+ return list(dict.fromkeys(value))
+
+
+class AccountPersonsQuerySerializer(serializers.Serializer):
+ limit = serializers.IntegerField(min_value=1, max_value=500, default=100, help_text="Maximum persons per page.")
+ offset = serializers.IntegerField(min_value=0, default=0, help_text="Number of matching persons to skip.")
+ search = serializers.CharField(
+ max_length=1000,
+ required=False,
+ allow_blank=True,
+ default="",
+ help_text="Search name, email, person ID, or distinct ID.",
+ )
+ properties = AccountPersonPropertiesField(
+ default=list,
+ help_text='JSON array of selected person property keys. Example: ["email", "name"].',
+ )
+ filters = AccountPersonFiltersField(
+ default=list,
+ help_text='JSON array of person property filters with key, operator, value, and type="person". Filters use AND.',
+ )
+ sort_column = serializers.CharField(
+ max_length=1000,
+ default="account_last_seen",
+ help_text="Sort by id, display_name, account_first_seen, account_last_seen, or a selected property key.",
+ )
+ sort_direction = serializers.ChoiceField(
+ choices=AccountPersonsSortDirection.choices, default="desc", help_text="Sort direction. Person ID breaks ties."
+ )
+
+ def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+ if attrs["sort_column"] not in {
+ "id",
+ "display_name",
+ "account_first_seen",
+ "account_last_seen",
+ *attrs["properties"],
+ }:
+ raise serializers.ValidationError({"sort_column": "Select the property before sorting by it."})
+ attrs["properties"] = list(dict.fromkeys(attrs["properties"]))
+ return attrs
+
+
+class AccountPersonSerializer(serializers.Serializer):
+ id = serializers.UUIDField(help_text="Current person ID.")
+ display_name = serializers.CharField(help_text="Display name from visible person properties, or the person ID.")
+ distinct_ids = serializers.ListField(
+ child=serializers.CharField(), help_text="Current membership distinct IDs for person navigation, up to 101."
+ )
+ properties = serializers.DictField(
+ child=serializers.JSONField(allow_null=True), help_text="Selected visible person properties."
+ )
+ account_first_seen = serializers.DateTimeField(
+ help_text="Earliest account activity across current distinct IDs, in UTC."
+ )
+ account_last_seen = serializers.DateTimeField(
+ help_text="Latest account activity across current distinct IDs, in UTC."
+ )
+
+
+@extend_schema_serializer(many=False)
+class AccountPersonsPageSerializer(serializers.Serializer):
+ results = AccountPersonSerializer(many=True, help_text="Matching current persons for this account.")
+ columns = serializers.ListField(
+ child=serializers.CharField(), help_text="Selected visible property keys, in request order."
+ )
+ limit = serializers.IntegerField(help_text="Maximum persons per page.")
+ offset = serializers.IntegerField(help_text="Number of matching persons skipped.")
+ has_more = serializers.BooleanField(help_text="Whether another page exists.")
+ next_offset = serializers.IntegerField(allow_null=True, help_text="Offset of the next page, or null.")
diff --git a/products/customer_analytics/backend/presentation/views/account_persons_query.py b/products/customer_analytics/backend/presentation/views/account_persons_query.py
new file mode 100644
index 000000000000..11ec77902e69
--- /dev/null
+++ b/products/customer_analytics/backend/presentation/views/account_persons_query.py
@@ -0,0 +1,119 @@
+from typing import Any, Literal, cast
+
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import OpenApiParameter, extend_schema
+from pydantic import Field
+from rest_framework import viewsets
+from rest_framework.exceptions import PermissionDenied, ValidationError
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import BaseThrottle
+
+from posthog.schema import AccountUsersQuery, ActorsQuery, ActorsQueryResponse, QueryRequest, RefreshType
+
+from posthog.hogql.errors import ExposedHogQLError
+
+from posthog.api.mixins import PydanticModelMixin
+from posthog.api.query import QueryViewSet, add_query_response_identity_headers
+from posthog.api.routing import TeamAndOrgViewSetMixin
+from posthog.api_queries_budget import reset_request_query_cost
+from posthog.clickhouse.client.limit import ConcurrencyLimitExceeded
+from posthog.clickhouse.query_tagging import get_query_tag_value, tags_context
+from posthog.errors import ExposedCHQueryError
+from posthog.models import User
+
+from products.customer_analytics.backend.facade.persons import (
+ AccountPersonsOptions,
+ AccountPersonsPropertyAccessError,
+ list_account_persons,
+)
+from products.customer_analytics.backend.presentation.views.account_persons import (
+ AccountPersonsPageSerializer,
+ AccountPersonsQuerySerializer,
+ AccountPersonsWebBurstThrottle,
+ AccountPersonsWebSustainedThrottle,
+)
+
+
+class AccountPersonsActorsQuery(ActorsQuery):
+ source: AccountUsersQuery = Field(description="Account membership source for the table.")
+
+
+class AccountPersonsQueryRequest(QueryRequest):
+ query: AccountPersonsActorsQuery = Field(description="Account-user table query to run.")
+ async_: Literal[False] | None = Field(default=None, alias="async")
+ refresh: Literal[RefreshType.BLOCKING, RefreshType.FORCE_BLOCKING] | None = Field(
+ default=RefreshType.BLOCKING,
+ description="Read cached results or calculate synchronously.",
+ )
+
+
+class AccountPersonsViewSet(TeamAndOrgViewSetMixin, PydanticModelMixin, viewsets.ViewSet):
+ scope_object = "account"
+ scope_object_read_actions = ["list", "create"]
+ serializer_class = AccountPersonsPageSerializer
+ pagination_class = None
+
+ check_team_api_queries_concurrency = QueryViewSet.check_team_api_queries_concurrency
+ _raise_concurrency_throttled = QueryViewSet._raise_concurrency_throttled
+ handle_column_ch_error = QueryViewSet.handle_column_ch_error
+ _tag_client_query_id = QueryViewSet._tag_client_query_id
+ _try_format_for_llm = QueryViewSet._try_format_for_llm
+ _validate_query_kind = QueryViewSet._validate_query_kind
+
+ def finalize_response(self, request: Request, response: Response, *args: Any, **kwargs: Any) -> Response:
+ return add_query_response_identity_headers(super().finalize_response(request, response, *args, **kwargs))
+
+ def get_throttles(self) -> list[BaseThrottle]:
+ return [
+ AccountPersonsWebBurstThrottle(),
+ AccountPersonsWebSustainedThrottle(),
+ *QueryViewSet.get_throttles(cast(QueryViewSet, self)),
+ ]
+
+ def dangerously_get_required_scopes(self, _request: Request, _view: object) -> list[str]:
+ if self.action == "create":
+ return ["query:read", "account:read", "person:read"]
+ return ["account:read", "person:read"]
+
+ @extend_schema(
+ operation_id="accounts_persons_retrieve",
+ parameters=[OpenApiParameter("id", OpenApiTypes.UUID, OpenApiParameter.PATH), AccountPersonsQuerySerializer],
+ responses={200: AccountPersonsPageSerializer(many=False)},
+ )
+ def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
+ query = AccountPersonsQuerySerializer(data=request.query_params)
+ query.is_valid(raise_exception=True)
+ try:
+ reset_request_query_cost()
+ with tags_context(api_queries_budgeted=get_query_tag_value("access_method") == "personal_api_key"):
+ page = list_account_persons(
+ team=self.team,
+ user=cast(User, request.user),
+ account_id=self.kwargs["id"],
+ user_access_control=self.user_access_control,
+ options=AccountPersonsOptions(**query.validated_data),
+ )
+ except (ExposedHogQLError, ExposedCHQueryError) as error:
+ raise ValidationError(str(error), getattr(error, "code_name", None)) from error
+ except ConcurrencyLimitExceeded as error:
+ QueryViewSet._raise_concurrency_throttled(cast(QueryViewSet, self), error)
+ except AccountPersonsPropertyAccessError:
+ raise PermissionDenied("You cannot filter or sort by this property.")
+ if page is None:
+ return Response({"detail": "Not found."}, status=404)
+ return Response(AccountPersonsPageSerializer(page).data)
+
+ @extend_schema(
+ operation_id="accounts_persons_query_create",
+ description="Run an account-user table query. Requires query, account, and person read scopes.",
+ parameters=[OpenApiParameter("id", OpenApiTypes.UUID, OpenApiParameter.PATH)],
+ request=AccountPersonsQueryRequest,
+ responses={200: ActorsQueryResponse},
+ )
+ def create(self, request: Request, *args: Any, **kwargs: Any) -> Response:
+ data = self.get_model(request.data, AccountPersonsQueryRequest)
+ if data.query.source.accountId != self.kwargs["id"]:
+ raise ValidationError("The query account must match the account in the URL.")
+ request.data.update(data.model_dump(mode="json", by_alias=True, exclude_none=True))
+ return QueryViewSet.create(cast(QueryViewSet, self), request, *args, **kwargs)
diff --git a/products/customer_analytics/backend/routes.py b/products/customer_analytics/backend/routes.py
index c4ad1a860609..67342d04de31 100644
--- a/products/customer_analytics/backend/routes.py
+++ b/products/customer_analytics/backend/routes.py
@@ -1,6 +1,7 @@
from posthog.api.routing import RouterRegistry
from products.customer_analytics.backend.presentation.views import urls as external_api_urls
+from products.customer_analytics.backend.presentation.views.account_persons_query import AccountPersonsViewSet
from products.customer_analytics.backend.presentation.views.accounts_table_query import AccountsTableQueryViewSet
from products.customer_analytics.backend.presentation.views.announcements import AnnouncementViewSet
from products.customer_analytics.backend.presentation.views.customer_tasks import CustomerTaskViewSet
@@ -32,6 +33,12 @@ api_urlpatterns = external_api_urls.urlpatterns
def register_routes(routers: RouterRegistry) -> None:
+ routers.projects.register(
+ r"accounts/(?P<id>[^/.]+)/persons",
+ AccountPersonsViewSet,
+ "project_account_persons",
+ ["team_id"],
+ )
routers.projects.register(
r"accounts_table_query",
AccountsTableQueryViewSet,
diff --git a/products/customer_analytics/frontend/generated/api.schemas.ts b/products/customer_analytics/frontend/generated/api.schemas.ts
index f2c1be5c124a..f1a412eea625 100644
--- a/products/customer_analytics/frontend/generated/api.schemas.ts
+++ b/products/customer_analytics/frontend/generated/api.schemas.ts
@@ -925,530 +925,199 @@ export interface AccountRelationshipWriteApi {
}
/**
- * Typed account properties: website_domain, external system identifiers (stripe_customer_id, hubspot_deal_id, billing_id, sfdc_id, zendesk_id, slack_channel_id, usage_dashboard_link, metabase_link), and touchpoint matching lists: email_domains (the company's email domains) and known_emails (individual addresses pinned to the account). Defaults to an empty object. Unknown keys are rejected. User assignments live on account relationships, not here.
- * @nullable
- */
-export type PatchedAccountApiProperties = {
- /**
- * Primary company website hostname used for account identity and logo lookup.
- * @nullable
- */
- website_domain?: string | null
- /** Email domains owned by this account's company, used to match inbound touchpoints to the account. */
- email_domains?: string[]
- /** Individual email addresses pinned to this account, matched before the domain fallback. */
- known_emails?: string[]
- /** @nullable */
- stripe_customer_id?: string | null
- /** @nullable */
- hubspot_deal_id?: string | null
- /** @nullable */
- billing_id?: string | null
- /** @nullable */
- sfdc_id?: string | null
- /** @nullable */
- zendesk_id?: string | null
- /** @nullable */
- slack_channel_id?: string | null
- /** @nullable */
- usage_dashboard_link?: string | null
- /** @nullable */
- metabase_link?: string | null
-} | null | null
-
-/**
- * A Customer Analytics account — a logical grouping used to assign customer-success ownership.
+ * Selected visible person properties.
*/
-export interface PatchedAccountApi {
- readonly id?: string
- /**
- * Human-readable name of the account.
- * @maxLength 400
- */
- name?: string
- /**
- * Identifier linking this account to its source customer — the analytics group key (the customer's organization id), used to match billing and external records. Optional.
- * @maxLength 400
- * @nullable
- */
- external_id?: string | null
- /**
- * Typed account properties: website_domain, external system identifiers (stripe_customer_id, hubspot_deal_id, billing_id, sfdc_id, zendesk_id, slack_channel_id, usage_dashboard_link, metabase_link), and touchpoint matching lists: email_domains (the company's email domains) and known_emails (individual addresses pinned to the account). Defaults to an empty object. Unknown keys are rejected. User assignments live on account relationships, not here.
- * @nullable
- */
- properties?: PatchedAccountApiProperties
- /** Tag names attached to the account. Pass a list to replace existing tags. */
- tags?: string[]
- /** Short IDs of the internal notebooks linked to this account, used to persist investigations, call notes, and other free-form context. Empty list if no notebooks have been created for the account. */
- readonly notebooks?: readonly string[]
- /** How often to generate an AI summary of the account's bound Slack channel (daily, weekly, or monthly). Null means summaries are off.
- *
- * * `daily` - daily
- * * `weekly` - weekly
- * * `monthly` - monthly */
- slack_summary_cadence?: SlackSummaryCadenceEnumApi | null
- /**
- * When the account churned. Null means the account has not churned.
- * @nullable
- */
- churned_at?: string | null
- /**
- * When the account was ignored, set by Track Rules or by hand. Null means the account is tracked.
- * @nullable
- */
- ignored_at?: string | null
- readonly created_at?: string
- /** @nullable */
- readonly created_by?: number | null
- /** @nullable */
- readonly updated_at?: string | null
-}
+export type AccountPersonApiProperties = { [key: string]: unknown }
-export interface ConversationMessageSenderApi {
- /** Display name of the message sender. */
- readonly name: string
- /**
- * Email address of the message sender, when available.
- * @nullable
- */
- readonly email: string | null
- /**
- * UUID of the matched PostHog person, when available.
- * @nullable
- */
- readonly person_id: string | null
+export interface AccountPersonApi {
+ /** Current person ID. */
+ id: string
+ /** Display name from visible person properties, or the person ID. */
+ display_name: string
+ /** Current membership distinct IDs for person navigation, up to 101. */
+ distinct_ids: string[]
+ /** Selected visible person properties. */
+ properties: AccountPersonApiProperties
+ /** Earliest account activity across current distinct IDs, in UTC. */
+ account_first_seen: string
+ /** Latest account activity across current distinct IDs, in UTC. */
+ account_last_seen: string
+}
+
+export interface AccountPersonsPageApi {
+ /** Matching current persons for this account. */
+ results: AccountPersonApi[]
+ /** Selected visible property keys, in request order. */
+ columns: string[]
+ /** Maximum persons per page. */
+ limit: number
+ /** Number of matching persons skipped. */
+ offset: number
+ /** Whether another page exists. */
+ has_more: boolean
/**
- * Distinct ID of the sender, when available.
+ * Offset of the next page, or null.
* @nullable
*/
- readonly distinct_id: string | null
+ next_offset: number | null
}
/**
- * * `inbound` - Inbound
- * * `outbound` - Outbound
+ * Read cached results or calculate synchronously.
*/
-export type EmailThreadMessageDirectionEnumApi =
- (typeof EmailThreadMessageDirectionEnumApi)[keyof typeof EmailThreadMessageDirectionEnumApi]
+export type AccountPersonsQueryRequestApiRefresh =
+ | (typeof AccountPersonsQueryRequestApiRefresh)[keyof typeof AccountPersonsQueryRequestApiRefresh]
+ | null
-export const EmailThreadMessageDirectionEnumApi = {
- Inbound: 'inbound',
- Outbound: 'outbound',
+export const AccountPersonsQueryRequestApiRefresh = {
+ Blocking: 'blocking',
+ ForceBlocking: 'force_blocking',
} as const
-export interface ConversationMessageSummaryApi {
- /** Sender of the message. */
- readonly sender: ConversationMessageSenderApi
- /** Timestamp from the message source. */
- readonly sent_at: string
- /** Whether PostHog received or sent the message.
- *
- * * `inbound` - Inbound
- * * `outbound` - Outbound */
- readonly direction: EmailThreadMessageDirectionEnumApi
-}
+export type AccountPersonsQueryRequestApiVariablesOverride = { [key: string]: { [key: string]: unknown } } | null
-/**
- * * `internal` - Internal
- * * `customer` - Customer
- */
-export type EmailThreadParticipantKindEnumApi =
- (typeof EmailThreadParticipantKindEnumApi)[keyof typeof EmailThreadParticipantKindEnumApi]
+export type BreakdownTypeApi = (typeof BreakdownTypeApi)[keyof typeof BreakdownTypeApi]
-export const EmailThreadParticipantKindEnumApi = {
- Internal: 'internal',
- Customer: 'customer',
+export const BreakdownTypeApi = {
+ Cohort: 'cohort',
+ Person: 'person',
+ Event: 'event',
+ EventMetadata: 'event_metadata',
+ Element: 'element',
+ Group: 'group',
+ Session: 'session',
+ Hogql: 'hogql',
+ DataWarehouse: 'data_warehouse',
+ DataWarehousePersonProperty: 'data_warehouse_person_property',
+ RevenueAnalytics: 'revenue_analytics',
} as const
-export interface AccountEmailThreadParticipantApi {
- /** Email address of the thread participant. */
- readonly email: string
- /** Display name from the captured email headers. */
- readonly display_name: string
- /** Whether the participant belongs to the PostHog organization or the customer.
- *
- * * `internal` - Internal
- * * `customer` - Customer */
- readonly kind: EmailThreadParticipantKindEnumApi
- /**
- * UUID of the matched PostHog person for a customer participant, when available.
- * @nullable
- */
- readonly person_id: string | null
-}
+export type MultipleBreakdownTypeApi = (typeof MultipleBreakdownTypeApi)[keyof typeof MultipleBreakdownTypeApi]
-export interface AccountEmailThreadApi {
- /** UUID of the captured email thread. */
- readonly id: string
- /** Email thread subject. */
- readonly subject: string
- /** Plain-text preview of the latest captured message. */
- readonly preview: string
- /**
- * Source timestamp of the first captured message.
- * @nullable
- */
- readonly first_message_at: string | null
- /** Sender, timestamp, and direction of the first captured message, when available. */
- readonly first_message: ConversationMessageSummaryApi | null
- /**
- * Source timestamp of the latest captured message.
- * @nullable
- */
- readonly last_message_at: string | null
- /** Sender, timestamp, and direction of the latest captured message, when available. */
- readonly last_message: ConversationMessageSummaryApi | null
- /** Number of captured messages in the thread. */
- readonly message_count: number
- /** Participants included in the email thread. */
- readonly participants: readonly AccountEmailThreadParticipantApi[]
-}
+export const MultipleBreakdownTypeApi = {
+ Person: 'person',
+ Event: 'event',
+ EventMetadata: 'event_metadata',
+ Element: 'element',
+ Group: 'group',
+ Session: 'session',
+ Hogql: 'hogql',
+ Cohort: 'cohort',
+ RevenueAnalytics: 'revenue_analytics',
+ DataWarehouse: 'data_warehouse',
+ DataWarehousePersonProperty: 'data_warehouse_person_property',
+} as const
-export interface PaginatedAccountEmailThreadListApi {
- count: number
- /** @nullable */
- next?: string | null
- /** @nullable */
- previous?: string | null
- results: AccountEmailThreadApi[]
+export interface BreakdownApi {
+ group_type_index?: number | null
+ histogram_bin_count?: number | null
+ normalize_url?: boolean | null
+ property: string | number
+ type?: MultipleBreakdownTypeApi | null
}
-export interface AccountEmailThreadAddressApi {
- /** Name from the email header. */
- readonly name: string
- /** Email address from the email header. */
- readonly email: string
+export interface BreakdownFilterApi {
+ breakdown?: string | (string | number)[] | number | null
+ breakdown_group_type_index?: number | null
+ breakdown_hide_other_aggregation?: boolean | null
+ breakdown_histogram_bin_count?: number | null
+ breakdown_limit?: number | null
+ breakdown_normalize_url?: boolean | null
+ breakdown_path_cleaning?: boolean | null
+ breakdown_type?: BreakdownTypeApi | null
+ breakdowns?: BreakdownApi[] | null
}
-export interface AccountEmailThreadMessageApi {
- /** UUID of the captured email message. */
- readonly id: string
- /** Timestamp from the source email. */
- readonly sent_at: string
- /** Sender from the email From header. */
- readonly sender: AccountEmailThreadAddressApi
- /** Recipients from the email To header. */
- readonly to_recipients: readonly AccountEmailThreadAddressApi[]
- /** Recipients from the email Cc header. */
- readonly cc_recipients: readonly AccountEmailThreadAddressApi[]
- /** Whether Mailgun authentication verified the sender domain. */
- readonly sender_authenticated: boolean
- /** Whether PostHog received or sent the message.
- *
- * * `inbound` - Inbound
- * * `outbound` - Outbound */
- readonly direction: EmailThreadMessageDirectionEnumApi
- /** Plain-text email content. */
- readonly content: string
+export interface CompareFilterApi {
+ /** Whether to compare the current date range to a previous date range. */
+ compare?: boolean | null
+ /** The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. */
+ compare_to?: string | null
}
-export interface PaginatedAccountEmailThreadMessageListApi {
- count: number
- /** @nullable */
- next?: string | null
- /** @nullable */
- previous?: string | null
- results: AccountEmailThreadMessageApi[]
-}
+export type IntervalTypeApi = (typeof IntervalTypeApi)[keyof typeof IntervalTypeApi]
-/**
- * One attendee of a synced calendar meeting (read-only).
- */
-export interface MeetingParticipantApi {
- /** Email address of the attendee. */
- readonly email: string
- /** Display name from the calendar event; may be empty. */
- readonly display_name: string
- /** The attendee's RSVP: 'needs_action', 'accepted', 'declined', or 'tentative'. */
- readonly response_status: string
- /** Whether this attendee organized the meeting. */
- readonly is_organizer: boolean
- /**
- * UUID of the PostHog person resolved for this attendee, if any.
- * @nullable
- */
- readonly person_id: string | null
-}
-
-/**
- * A calendar meeting synced from a connected employee calendar (read-only).
- */
-export interface MeetingApi {
- /** UUID of the meeting. */
- readonly id: string
- /** Meeting title; may be empty. */
- readonly title: string
- /** Whether the meeting belongs to a recurring series. Account meeting lists include all past occurrences and only the next upcoming, non-canceled occurrence of each series. */
- readonly is_recurring: boolean
- /**
- * Gong call URL matched through the calendar event id; null when no Gong call is available.
- * @nullable
- */
- readonly gong_url: string | null
- /** When the meeting starts. */
- readonly start_time: string
- /**
- * When the meeting ends.
- * @nullable
- */
- readonly end_time: string | null
- /** Email address of the meeting organizer; may be empty. */
- readonly organizer_email: string
- /** Meeting status: 'confirmed', 'tentative', or 'cancelled'. */
- readonly status: string
- /** Attendees of the meeting. */
- readonly participants: readonly MeetingParticipantApi[]
-}
-
-export interface PaginatedMeetingListApi {
- count: number
- /** @nullable */
- next?: string | null
- /** @nullable */
- previous?: string | null
- results: MeetingApi[]
-}
-
-export interface AccountPresenceViewerApi {
- /** PostHog user ID of the teammate viewing this account. */
- readonly user_id: number
- /** Display name of the teammate viewing this account. */
- readonly display_name: string
-}
-
-/**
- * Metadata for one message a channel summary covered — never the message text.
- */
-export interface ChannelSummaryMessageApi {
- /** Display name of the message author. */
- readonly author: string
- /** When the message was sent. */
- readonly sent_at: string
- /** Slack permalink to the message. */
- readonly permalink: string
-}
-
-/**
- * An AI summary of one closed period of the account's bound Slack channel (read-only).
- */
-export interface AccountChannelSummaryApi {
- /** UUID of the summary. */
- readonly id: string
- /** Slack channel the summary covered — kept even if the account is later rebound. */
- readonly slack_channel_id: string
- /** Cadence the summarized period belongs to (daily, weekly, or monthly).
- *
- * * `daily` - daily
- * * `weekly` - weekly
- * * `monthly` - monthly */
- readonly cadence: SlackSummaryCadenceEnumApi
- /** Start of the summarized period (inclusive). */
- readonly period_start: string
- /** End of the summarized period (exclusive). */
- readonly period_end: string
- /** Markdown summary citing the original Slack messages with permalinks. */
- readonly content: string
- /** Number of channel messages the summary covered. */
- readonly message_count: number
- /** The messages the summary covered, in transcript order — metadata only, no message text. */
- readonly messages: readonly ChannelSummaryMessageApi[]
- /** When the summary was generated. */
- readonly generated_at: string
-}
+export const IntervalTypeApi = {
+ Second: 'second',
+ Minute: 'minute',
+ Hour: 'hour',
+ Day: 'day',
+ Week: 'week',
+ Month: 'month',
+ Quarter: 'quarter',
+ Year: 'year',
+} as const
-export interface PaginatedAccountChannelSummaryListApi {
- count: number
- /** @nullable */
- next?: string | null
- /** @nullable */
- previous?: string | null
- results: AccountChannelSummaryApi[]
-}
+export type MetricsFilterOpApi = (typeof MetricsFilterOpApi)[keyof typeof MetricsFilterOpApi]
-/**
- * A support ticket linked to an account, sourced from the conversations product (read-only).
- */
-export interface SupportTicketApi {
- /** UUID of the support ticket. */
- readonly id: string
- /** Human-readable ticket number. */
- readonly ticket_number: number
- /** Current status of the ticket (e.g. 'new', 'open'). */
- readonly status: string
- /**
- * When the most recent message was sent on this ticket.
- * @nullable
- */
- readonly last_message_at: string | null
- /**
- * Truncated preview of the most recent message.
- * @nullable
- */
- readonly last_message_text: string | null
- /** Sender, timestamp, and direction of the latest public message, when available. */
- readonly last_message: ConversationMessageSummaryApi | null
- /** Absolute URL to open this ticket in the app. */
- readonly deep_link: string
- /** When the ticket conversation started. */
- readonly created_at: string
- /** Display name of the customer who started the ticket. */
- readonly started_by: string
- /** Distinct ID of the customer who started the ticket. */
- readonly distinct_id: string
-}
+export const MetricsFilterOpApi = {
+ Eq: 'eq',
+ Neq: 'neq',
+ Regex: 'regex',
+ NotRegex: 'not_regex',
+} as const
-export interface AccountSupportTicketMessageApi {
- /** UUID of the support ticket message. */
- readonly id: string
- /** Plain-text message content. */
- readonly content: string
- /** Display name of the message author. */
- readonly author_name: string
- /** Whether PostHog received or sent the message.
- *
- * * `inbound` - Inbound
- * * `outbound` - Outbound */
- readonly direction: EmailThreadMessageDirectionEnumApi
- /** Whether the message is an internal note hidden from the customer. */
- readonly is_private: boolean
- /** When the message was created. */
- readonly created_at: string
-}
+export type MetricsAttributeScopeApi = (typeof MetricsAttributeScopeApi)[keyof typeof MetricsAttributeScopeApi]
-export interface PaginatedAccountSupportTicketMessageListApi {
- count: number
- /** @nullable */
- next?: string | null
- /** @nullable */
- previous?: string | null
- results: AccountSupportTicketMessageApi[]
-}
+export const MetricsAttributeScopeApi = {
+ Resource: 'resource',
+ Attribute: 'attribute',
+ Auto: 'auto',
+} as const
-export interface AccountPresenceListRequestApi {
- /**
- * Up to 100 account IDs to read presence for.
- * @maxItems 100
- */
- account_ids: string[]
+export interface MetricsQueryFilterApi {
+ key: string
+ op: MetricsFilterOpApi
+ scope?: MetricsAttributeScopeApi | null
+ value: string
}
-export interface AccountPresenceApi {
- /** Customer analytics account ID. */
- readonly account_id: string
- /** People viewing this account. */
- readonly viewers: readonly AccountPresenceViewerApi[]
+export interface MetricsDashboardVariableSelectionApi {
+ all?: boolean | null
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[]
}
-export type AccountsTableQueryRequestApiVariablesOverride = { [key: string]: { [key: string]: unknown } } | null
-
-export type AccountsTableAccountFieldApi =
- (typeof AccountsTableAccountFieldApi)[keyof typeof AccountsTableAccountFieldApi]
+export type MetricsDashboardVariableSourceApi =
+ (typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
-export const AccountsTableAccountFieldApi = {
- Name: 'name',
- ExternalId: 'external_id',
- CreatedAt: 'created_at',
- UpdatedAt: 'updated_at',
- ChurnedAt: 'churned_at',
- IgnoredAt: 'ignored_at',
- StripeCustomerId: 'stripe_customer_id',
- HubspotDealId: 'hubspot_deal_id',
- BillingId: 'billing_id',
- SfdcId: 'sfdc_id',
- ZendeskId: 'zendesk_id',
+export const MetricsDashboardVariableSourceApi = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
} as const
-export interface AccountsTableAccountFieldColumnApi {
- field: AccountsTableAccountFieldApi
- kind?: 'account_field'
+export interface MetricsDashboardVariableApi {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null
+ current?: MetricsDashboardVariableSelectionApi | null
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null
+ includeAll?: boolean | null
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null
+ multi?: boolean | null
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null
+ source: MetricsDashboardVariableSourceApi
}
-export const AccountsTableTagsColumnApiValue = {
- kind: 'tags',
-} as const
-export type AccountsTableTagsColumnApi = typeof AccountsTableTagsColumnApiValue
-
-export const AccountsTableNoteCountColumnApiValue = {
- kind: 'note_count',
-} as const
-export type AccountsTableNoteCountColumnApi = typeof AccountsTableNoteCountColumnApiValue
-
-export interface AccountsTableRelationshipColumnApi {
- /** Team-scoped relationship definition to return for each account. */
- definitionId: string
- kind?: 'relationship'
-}
-
-export interface AccountsTableCustomPropertyColumnApi {
- /** Team-scoped custom property definition to return for each account. */
- definitionId: string
- kind?: 'custom_property'
-}
-
-export type WindowDaysApi = (typeof WindowDaysApi)[keyof typeof WindowDaysApi]
-
-export const WindowDaysApi = {
- Number7: 7,
- Number14: 14,
- Number30: 30,
- Number90: 90,
-} as const
-
-export interface AccountsTableCustomPropertyHistoryColumnApi {
- /** Team-scoped numeric custom property definition whose write history should be returned. */
- definitionId: string
- kind?: 'custom_property_history'
- /** Number of days of history to return. The current value is included even when it is older. */
- windowDays: WindowDaysApi
-}
-
-export type AccountsTableAccountFieldOperatorApi =
- (typeof AccountsTableAccountFieldOperatorApi)[keyof typeof AccountsTableAccountFieldOperatorApi]
-
-export const AccountsTableAccountFieldOperatorApi = {
- Exact: 'exact',
- IsNot: 'is_not',
- Icontains: 'icontains',
- NotIcontains: 'not_icontains',
- IsSet: 'is_set',
- IsNotSet: 'is_not_set',
- IsDateExact: 'is_date_exact',
- IsDateBefore: 'is_date_before',
- IsDateAfter: 'is_date_after',
-} as const
-
-export interface AccountsTableAccountFieldFilterApi {
- field: AccountsTableAccountFieldApi
- kind?: 'account_field'
- operator: AccountsTableAccountFieldOperatorApi
- values?: string[] | null
-}
-
-export type AccountsTableRelationshipOperatorApi =
- (typeof AccountsTableRelationshipOperatorApi)[keyof typeof AccountsTableRelationshipOperatorApi]
-
-export const AccountsTableRelationshipOperatorApi = {
- Exact: 'exact',
- IsNot: 'is_not',
- IsSet: 'is_set',
- IsNotSet: 'is_not_set',
-} as const
-
-export interface AccountsTableRelationshipFilterApi {
- definitionId: string
- kind?: 'relationship'
- operator: AccountsTableRelationshipOperatorApi
- userIds?: number[] | null
-}
-
-export type AccountsTableCustomPropertyOperatorApi =
- (typeof AccountsTableCustomPropertyOperatorApi)[keyof typeof AccountsTableCustomPropertyOperatorApi]
+export type PropertyOperatorApi = (typeof PropertyOperatorApi)[keyof typeof PropertyOperatorApi]
-export const AccountsTableCustomPropertyOperatorApi = {
+export const PropertyOperatorApi = {
Exact: 'exact',
IsNot: 'is_not',
Icontains: 'icontains',
NotIcontains: 'not_icontains',
+ StartsWith: 'starts_with',
+ NotStartsWith: 'not_starts_with',
+ EndsWith: 'ends_with',
+ NotEndsWith: 'not_ends_with',
Regex: 'regex',
NotRegex: 'not_regex',
Gt: 'gt',
@@ -1460,105 +1129,380 @@ export const AccountsTableCustomPropertyOperatorApi = {
IsDateExact: 'is_date_exact',
IsDateBefore: 'is_date_before',
IsDateAfter: 'is_date_after',
+ Between: 'between',
+ NotBetween: 'not_between',
+ Min: 'min',
+ Max: 'max',
+ In: 'in',
+ NotIn: 'not_in',
+ IsCleanedPathExact: 'is_cleaned_path_exact',
+ IsCleanedPathNotExact: 'is_cleaned_path_not_exact',
+ FlagEvaluatesTo: 'flag_evaluates_to',
+ SemverEq: 'semver_eq',
+ SemverNeq: 'semver_neq',
+ SemverGt: 'semver_gt',
+ SemverGte: 'semver_gte',
+ SemverLt: 'semver_lt',
+ SemverLte: 'semver_lte',
+ SemverTilde: 'semver_tilde',
+ SemverCaret: 'semver_caret',
+ SemverWildcard: 'semver_wildcard',
+ IcontainsMulti: 'icontains_multi',
+ NotIcontainsMulti: 'not_icontains_multi',
} as const
-export interface AccountsTableCustomPropertyFilterApi {
- definitionId: string
- kind?: 'custom_property'
- operator: AccountsTableCustomPropertyOperatorApi
- /** Values interpreted according to the custom property definition's display type. */
- values?: (string | number | boolean)[] | null
-}
-
-export interface AccountsTableSearchFilterApi {
- kind?: 'search'
- query: string
+export interface EventPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator?: PropertyOperatorApi | null
+ /** Event properties */
+ type?: 'event'
+ value?: (string | number | boolean)[] | string | number | boolean | null
}
-export interface AccountsTableTagsFilterApi {
- kind?: 'tags'
- /** Match accounts carrying any of these tag names. */
- tagNames: string[]
+export interface PersonPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ /** Person properties */
+ type?: 'person'
+ value?: (string | number | boolean)[] | string | number | boolean | null
}
-export interface AccountsTableAssignedToFilterApi {
- kind?: 'assigned_to'
- /** Match accounts where any listed user actively holds any relationship. */
- userIds: number[]
+export interface PersonMetadataPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ /** Top-level columns on the persons table (e.g. created_at), not properties JSON */
+ type?: 'person_metadata'
+ value?: (string | number | boolean)[] | string | number | boolean | null
}
-export const AccountsTableAssignedFilterApiValue = {
- kind: 'assigned',
-} as const
-export type AccountsTableAssignedFilterApi = typeof AccountsTableAssignedFilterApiValue
+export type Key10Api = (typeof Key10Api)[keyof typeof Key10Api]
-export const AccountsTableUnassignedFilterApiValue = {
- kind: 'unassigned',
+export const Key10Api = {
+ TagName: 'tag_name',
+ Text: 'text',
+ Href: 'href',
+ Selector: 'selector',
} as const
-export type AccountsTableUnassignedFilterApi = typeof AccountsTableUnassignedFilterApiValue
-export interface AccountsTableAccountIdFilterApi {
- accountId: string
- kind?: 'account_id'
+export interface ElementPropertyFilterApi {
+ key: Key10Api
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'element'
+ value?: (string | number | boolean)[] | string | number | boolean | null
}
-export const AccountsTableCountMetricApiValue = {
- kind: 'count',
-} as const
-export type AccountsTableCountMetricApi = typeof AccountsTableCountMetricApiValue
-
-export type AccountsTableAggregationApi = (typeof AccountsTableAggregationApi)[keyof typeof AccountsTableAggregationApi]
-
-export const AccountsTableAggregationApi = {
- Sum: 'sum',
- Avg: 'avg',
- Min: 'min',
- Max: 'max',
- Median: 'median',
-} as const
-
-export interface AccountsTableAggregateMetricApi {
- aggregation: AccountsTableAggregationApi
- column: AccountsTableCustomPropertyColumnApi
- kind?: 'aggregate'
- scale?: number | null
+export interface EventMetadataPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'event_metadata'
+ value?: (string | number | boolean)[] | string | number | boolean | null
}
-export type AccountsTableThresholdOperatorApi =
- (typeof AccountsTableThresholdOperatorApi)[keyof typeof AccountsTableThresholdOperatorApi]
-
-export const AccountsTableThresholdOperatorApi = {
- Gt: 'gt',
- Gte: 'gte',
- Lt: 'lt',
- Lte: 'lte',
- Exact: 'exact',
- IsNot: 'is_not',
-} as const
+export interface SessionPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'session'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
-export interface AccountsTableCountThresholdMetricApi {
- column: AccountsTableCustomPropertyColumnApi
- kind?: 'count_threshold'
- operator: AccountsTableThresholdOperatorApi
+export interface CohortPropertyFilterApi {
+ /** Set by the feature flag API when the cohort is deleted or does not exist. */
+ cohort_deleted?: boolean | null
+ /** Set by the feature flag API when the cohort does not exist, so it cannot be restored. */
+ cohort_missing?: boolean | null
+ cohort_name?: string | null
+ key?: 'id'
+ label?: string | null
+ operator?: PropertyOperatorApi | null
+ type?: 'cohort'
value: number
}
-export type BounceRatePageViewModeApi = (typeof BounceRatePageViewModeApi)[keyof typeof BounceRatePageViewModeApi]
+export type DurationTypeApi = (typeof DurationTypeApi)[keyof typeof DurationTypeApi]
-export const BounceRatePageViewModeApi = {
- CountPageviews: 'count_pageviews',
- UniqUrls: 'uniq_urls',
- UniqPageScreenAutocaptures: 'uniq_page_screen_autocaptures',
+export const DurationTypeApi = {
+ Duration: 'duration',
+ ActiveSeconds: 'active_seconds',
+ InactiveSeconds: 'inactive_seconds',
} as const
-export type FilterLogicalOperatorApi = (typeof FilterLogicalOperatorApi)[keyof typeof FilterLogicalOperatorApi]
+export interface RecordingPropertyFilterApi {
+ key: DurationTypeApi | string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'recording'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
-export const FilterLogicalOperatorApi = {
- And: 'AND',
- Or: 'OR',
-} as const
+export interface LogEntryPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'log_entry'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
-export type CustomBotFieldApi = (typeof CustomBotFieldApi)[keyof typeof CustomBotFieldApi]
+export type GroupPropertyFilterApiGroupKeyNames = { [key: string]: string } | null
+
+export interface GroupPropertyFilterApi {
+ group_key_names?: GroupPropertyFilterApiGroupKeyNames
+ group_type_index?: number | null
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'group'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface FeaturePropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ /** Event property with "$feature/" prepended */
+ type?: 'feature'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface FlagPropertyFilterApi {
+ /** The key should be the flag ID */
+ key: string
+ label?: string | null
+ /** Only flag_evaluates_to operator is allowed for flag dependencies */
+ operator?: 'flag_evaluates_to'
+ /** Feature flag dependency */
+ type?: 'flag'
+ /** The value can be true, false, or a variant name */
+ value: boolean | string
+}
+
+export interface HogQLPropertyFilterApi {
+ key: string
+ label?: string | null
+ type?: 'hogql'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export const EmptyPropertyFilterApiValue = {
+ type: 'empty',
+} as const
+export type EmptyPropertyFilterApi = typeof EmptyPropertyFilterApiValue
+
+export interface DataWarehousePropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'data_warehouse'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface DataWarehousePersonPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'data_warehouse_person_property'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface ErrorTrackingIssueFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'error_tracking_issue'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export type LogPropertyFilterTypeApi = (typeof LogPropertyFilterTypeApi)[keyof typeof LogPropertyFilterTypeApi]
+
+export const LogPropertyFilterTypeApi = {
+ Log: 'log',
+ LogAttribute: 'log_attribute',
+ LogResourceAttribute: 'log_resource_attribute',
+} as const
+
+export interface LogPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type: LogPropertyFilterTypeApi
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface MetricPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'metric_attribute'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export type SpanPropertyFilterTypeApi = (typeof SpanPropertyFilterTypeApi)[keyof typeof SpanPropertyFilterTypeApi]
+
+export const SpanPropertyFilterTypeApi = {
+ Span: 'span',
+ SpanAttribute: 'span_attribute',
+ SpanResourceAttribute: 'span_resource_attribute',
+} as const
+
+export interface SpanPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type: SpanPropertyFilterTypeApi
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface RevenueAnalyticsPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'revenue_analytics'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface AccountCustomPropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ /** Customer analytics account custom property — the key is the property definition id */
+ type?: 'account_custom_property'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export interface WorkflowVariablePropertyFilterApi {
+ key: string
+ label?: string | null
+ operator: PropertyOperatorApi
+ type?: 'workflow_variable'
+ value?: (string | number | boolean)[] | string | number | boolean | null
+}
+
+export type BehavioralEventSourceApi = (typeof BehavioralEventSourceApi)[keyof typeof BehavioralEventSourceApi]
+
+export const BehavioralEventSourceApi = {
+ Events: 'events',
+ Actions: 'actions',
+} as const
+
+export type TimeUnitTypeApi = (typeof TimeUnitTypeApi)[keyof typeof TimeUnitTypeApi]
+
+export const TimeUnitTypeApi = {
+ Day: 'day',
+ Week: 'week',
+ Month: 'month',
+ Year: 'year',
+} as const
+
+export type InlineBehavioralTypeApi = (typeof InlineBehavioralTypeApi)[keyof typeof InlineBehavioralTypeApi]
+
+export const InlineBehavioralTypeApi = {
+ PerformedEvent: 'performed_event',
+ PerformedEventMultiple: 'performed_event_multiple',
+} as const
+
+export interface BehavioralPropertyFilterApi {
+ /** Extra property filters the matching events must satisfy. Deliberately excludes nested behavioral/cohort filters and groups */
+ event_filters?:
+ | (
+ | EventPropertyFilterApi
+ | PersonPropertyFilterApi
+ | ElementPropertyFilterApi
+ | FeaturePropertyFilterApi
+ | HogQLPropertyFilterApi
+ )[]
+ | null
+ event_type: BehavioralEventSourceApi
+ /** Absolute or relative (e.g. -30d) lower date bound — alternative to time_value/time_interval */
+ explicit_datetime?: string | null
+ explicit_datetime_to?: string | null
+ /** Event name, or action id when event_type is 'actions' */
+ key: string
+ label?: string | null
+ /** Match persons who did NOT satisfy the criterion. Not the same as a low count — zero-occurrence persons never match count operators */
+ negation?: boolean | null
+ /** Count comparison for performed_event_multiple, defaults to exact */
+ operator?: PropertyOperatorApi | null
+ /** Count threshold for performed_event_multiple */
+ operator_value?: number | null
+ time_interval?: TimeUnitTypeApi | null
+ /** Relative time window size, paired with time_interval */
+ time_value?: number | null
+ /** Person performed (or didn't perform) an event in a time window. ClickHouse-only — not evaluable by flags or CDP */
+ type?: 'behavioral'
+ value: InlineBehavioralTypeApi
+}
+
+export interface DashboardFilterApi {
+ breakdown_filter?: BreakdownFilterApi | null
+ /** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
+ compareFilter?: CompareFilterApi | null
+ date_from?: string | null
+ date_to?: string | null
+ explicitDate?: boolean | null
+ /** Tri-state test-account override. Null/absent = inherit; true = force on; false = force off. */
+ filterTestAccounts?: boolean | null
+ /** Time granularity forced onto every insight that supports one. Absent/null = inherit. */
+ interval?: IntervalTypeApi | null
+ metricFilters?: MetricsQueryFilterApi[] | null
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariableApi[] | null
+ properties?:
+ | (
+ | EventPropertyFilterApi
+ | PersonPropertyFilterApi
+ | PersonMetadataPropertyFilterApi
+ | ElementPropertyFilterApi
+ | EventMetadataPropertyFilterApi
+ | SessionPropertyFilterApi
+ | CohortPropertyFilterApi
+ | RecordingPropertyFilterApi
+ | LogEntryPropertyFilterApi
+ | GroupPropertyFilterApi
+ | FeaturePropertyFilterApi
+ | FlagPropertyFilterApi
+ | HogQLPropertyFilterApi
+ | EmptyPropertyFilterApi
+ | DataWarehousePropertyFilterApi
+ | DataWarehousePersonPropertyFilterApi
+ | ErrorTrackingIssueFilterApi
+ | LogPropertyFilterApi
+ | MetricPropertyFilterApi
+ | SpanPropertyFilterApi
+ | RevenueAnalyticsPropertyFilterApi
+ | AccountCustomPropertyFilterApi
+ | WorkflowVariablePropertyFilterApi
+ | BehavioralPropertyFilterApi
+ )[]
+ | null
+}
+
+export type LimitContextApi = (typeof LimitContextApi)[keyof typeof LimitContextApi]
+
+export const LimitContextApi = {
+ PosthogAi: 'posthog_ai',
+} as const
+
+export type BounceRatePageViewModeApi = (typeof BounceRatePageViewModeApi)[keyof typeof BounceRatePageViewModeApi]
+
+export const BounceRatePageViewModeApi = {
+ CountPageviews: 'count_pageviews',
+ UniqUrls: 'uniq_urls',
+ UniqPageScreenAutocaptures: 'uniq_page_screen_autocaptures',
+} as const
+
+export type FilterLogicalOperatorApi = (typeof FilterLogicalOperatorApi)[keyof typeof FilterLogicalOperatorApi]
+
+export const FilterLogicalOperatorApi = {
+ And: 'AND',
+ Or: 'OR',
+} as const
+
+export type CustomBotFieldApi = (typeof CustomBotFieldApi)[keyof typeof CustomBotFieldApi]
export const CustomBotFieldApi = {
RawUserAgent: '$raw_user_agent',
@@ -1803,41 +1747,35 @@ export interface HogQLQueryModifiersApi {
webAnalyticsFirstPageviewFilters?: boolean | null
}
-export type AccountsTableCustomPropertyDisplayTypeApi =
- (typeof AccountsTableCustomPropertyDisplayTypeApi)[keyof typeof AccountsTableCustomPropertyDisplayTypeApi]
-
-export const AccountsTableCustomPropertyDisplayTypeApi = {
- Text: 'text',
- Link: 'link',
- Number: 'number',
- Currency: 'currency',
- Percent: 'percent',
- Date: 'date',
- Datetime: 'datetime',
- Boolean: 'boolean',
- Select: 'select',
-} as const
-
-export interface AccountsTableCustomPropertyOptionApi {
- color: string
- id?: string | null
- label: string
-}
-
-export interface AccountsTableCustomPropertySourceApi {
- id: string
-}
-
-export interface AccountsTableCustomPropertyDefinitionApi {
- description?: string | null
- display_type: AccountsTableCustomPropertyDisplayTypeApi
- has_workflow_reference: boolean
- id: string
- is_big_number?: boolean | null
- is_canonical: boolean
- name: string
- options?: AccountsTableCustomPropertyOptionApi[] | null
- source?: AccountsTableCustomPropertySourceApi | null
+export interface PropertyGroupFilterValueApi {
+ type: FilterLogicalOperatorApi
+ values: (
+ | PropertyGroupFilterValueApi
+ | EventPropertyFilterApi
+ | PersonPropertyFilterApi
+ | PersonMetadataPropertyFilterApi
+ | ElementPropertyFilterApi
+ | EventMetadataPropertyFilterApi
+ | SessionPropertyFilterApi
+ | CohortPropertyFilterApi
+ | RecordingPropertyFilterApi
+ | LogEntryPropertyFilterApi
+ | GroupPropertyFilterApi
+ | FeaturePropertyFilterApi
+ | FlagPropertyFilterApi
+ | HogQLPropertyFilterApi
+ | EmptyPropertyFilterApi
+ | DataWarehousePropertyFilterApi
+ | DataWarehousePersonPropertyFilterApi
+ | ErrorTrackingIssueFilterApi
+ | LogPropertyFilterApi
+ | MetricPropertyFilterApi
+ | SpanPropertyFilterApi
+ | RevenueAnalyticsPropertyFilterApi
+ | AccountCustomPropertyFilterApi
+ | WorkflowVariablePropertyFilterApi
+ | BehavioralPropertyFilterApi
+ )[]
}
export interface ClickhouseQueryProgressApi {
@@ -1940,14 +1878,6 @@ export interface QueryStatusApi {
team_id: number
}
-export interface AccountsTableRelationshipDefinitionApi {
- description?: string | null
- id: string
- is_controlled: boolean
- is_single_holder?: boolean | null
- name: string
-}
-
export interface ResolvedDateRangeResponseApi {
date_from: string
date_to: string
@@ -1955,51 +1885,6 @@ export interface ResolvedDateRangeResponseApi {
read_from?: string | null
}
-export interface AccountsTableCustomPropertyHistoryPointApi {
- timestamp: string
- value: number
-}
-
-/**
- * Requested direct Account fields, keyed by their typed field reference.
- */
-export type AccountsTableRowApiAccountFields = { [key: string]: string | null }
-
-/**
- * Current values keyed by requested custom property definition ID.
- */
-export type AccountsTableRowApiCustomProperties = { [key: string]: string | number | boolean | null }
-
-/**
- * Numeric write history keyed by requested custom property definition ID.
- */
-export type AccountsTableRowApiCustomPropertyHistory = { [key: string]: AccountsTableCustomPropertyHistoryPointApi[] }
-
-/**
- * Active assignee user IDs keyed by requested relationship definition ID.
- */
-export type AccountsTableRowApiRelationships = { [key: string]: number[] }
-
-export interface AccountsTableRowApi {
- /** Requested direct Account fields, keyed by their typed field reference. */
- accountFields: AccountsTableRowApiAccountFields
- /** Current values keyed by requested custom property definition ID. */
- customProperties: AccountsTableRowApiCustomProperties
- /** Numeric write history keyed by requested custom property definition ID. */
- customPropertyHistory: AccountsTableRowApiCustomPropertyHistory
- externalId?: string | null
- id: string
- /** Bare hostname the row's logo is rendered from. Null when no source resolved one. */
- logoDomain?: string | null
- name: string
- /** Number of linked internal notes. Omitted when the request does not select the note count. */
- noteCount?: number | null
- /** Active assignee user IDs keyed by requested relationship definition ID. */
- relationships: AccountsTableRowApiRelationships
- /** Sorted tag names. Omitted when the request does not select tags. */
- tags?: string[] | null
-}
-
export interface QueryTimingApi {
/** Key. Shortened to 'k' to save on data. */
k: string
@@ -2046,65 +1931,34 @@ export interface AccessControlFilterWarningApi {
type?: 'access_control'
}
-export interface AccountsTableQueryResponseApi {
- columns?:
- | (
- | AccountsTableAccountFieldColumnApi
- | AccountsTableTagsColumnApi
- | AccountsTableNoteCountColumnApi
- | AccountsTableRelationshipColumnApi
- | AccountsTableCustomPropertyColumnApi
- | AccountsTableCustomPropertyHistoryColumnApi
- )[]
- | null
- customPropertyDefinitions?: AccountsTableCustomPropertyDefinitionApi[] | null
+export interface ActorsQueryResponseApi {
+ columns: unknown[]
/** Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. */
error?: string | null
- hasMore: boolean
+ hasMore?: boolean | null
/** Generated HogQL query. */
- hogql?: string | null
- kind?: 'AccountsTableQuery'
+ hogql: string
limit: number
- /** Aggregated values in the same order as the requested metrics. */
- metricsResults?: (number | null)[] | null
+ missing_actors_count?: number | null
/** Modifiers used when performing the query */
modifiers?: HogQLQueryModifiersApi | null
offset: number
/** Query status indicates whether next to the provided data, a query is still running. */
query_status?: QueryStatusApi | null
- relationshipDefinitions?: AccountsTableRelationshipDefinitionApi[] | null
/** The resolved previous/comparison period date range, when comparing against another period */
resolved_compare_date_range?: ResolvedDateRangeResponseApi | null
/** The date range used for the query */
resolved_date_range?: ResolvedDateRangeResponseApi | null
- results: AccountsTableRowApi[]
+ results: unknown[][]
/** Measured timings for different parts of the query generation process */
timings?: QueryTimingApi[] | null
+ types?: string[] | null
/** Connector-synced data warehouse sources referenced by this query, if any. */
used_data_warehouse_sources?: DataWarehouseSourceUsageApi[] | null
/** Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. */
warnings?: (DataWarehouseSyncWarningApi | AccessControlFilterWarningApi)[] | null
}
-export type AccountsTableSortDirectionApi =
- (typeof AccountsTableSortDirectionApi)[keyof typeof AccountsTableSortDirectionApi]
-
-export const AccountsTableSortDirectionApi = {
- Asc: 'asc',
- Desc: 'desc',
-} as const
-
-export interface AccountsTableSortApi {
- /** A typed column that supports server-side sorting. */
- column:
- | AccountsTableAccountFieldColumnApi
- | AccountsTableTagsColumnApi
- | AccountsTableNoteCountColumnApi
- | AccountsTableRelationshipColumnApi
- | AccountsTableCustomPropertyColumnApi
- direction: AccountsTableSortDirectionApi
-}
-
export interface QueryLogTagsApi {
/** Name of the query, preferably unique. For example web_analytics_vitals */
name?: string | null
@@ -2116,572 +1970,897 @@ export interface QueryLogTagsApi {
scene?: string | null
}
-export interface AccountsTableQueryApi {
- /** Columns to load for each account. Account identity fields are always returned. */
- columns: (
- | AccountsTableAccountFieldColumnApi
- | AccountsTableTagsColumnApi
- | AccountsTableNoteCountColumnApi
- | AccountsTableRelationshipColumnApi
- | AccountsTableCustomPropertyColumnApi
- | AccountsTableCustomPropertyHistoryColumnApi
- )[]
- /** Nonempty property-filter groups are ORed together; filters within each group use AND. Global filters still apply. */
- filterGroups?:
- | (
- | AccountsTableAccountFieldFilterApi
- | AccountsTableRelationshipFilterApi
- | AccountsTableCustomPropertyFilterApi
- )[][]
- | null
- /** Filters are combined with AND. Values within tag and assignment filters use OR. */
- filters?:
+export interface AccountUsersQueryApi {
+ /** ID of the account whose users to list. */
+ accountId: string
+ kind?: 'AccountUsersQuery'
+ /** Modifiers used when performing the query */
+ modifiers?: HogQLQueryModifiersApi | null
+ response?: ActorsQueryResponseApi | null
+ tags?: QueryLogTagsApi | null
+ /** version of the node, used for schema migrations */
+ version?: number | null
+}
+
+export interface AccountPersonsActorsQueryApi {
+ /** Exclude persons matching the team's "internal and test account" filters. Only person-scoped filters (person properties, cohorts) are applied. Event-scoped test account filters have no meaning in a persons query and are ignored. */
+ filterTestAccounts?: boolean | null
+ /** Currently only person filters supported. No filters for querying groups. See `filter_conditions()` in actor_strategies.py. */
+ fixedProperties?:
| (
- | AccountsTableSearchFilterApi
- | AccountsTableTagsFilterApi
- | AccountsTableAssignedToFilterApi
- | AccountsTableAssignedFilterApi
- | AccountsTableUnassignedFilterApi
- | AccountsTableRelationshipFilterApi
- | AccountsTableAccountIdFilterApi
- | AccountsTableAccountFieldFilterApi
- | AccountsTableCustomPropertyFilterApi
+ | PersonPropertyFilterApi
+ | PersonMetadataPropertyFilterApi
+ | CohortPropertyFilterApi
+ | HogQLPropertyFilterApi
+ | EmptyPropertyFilterApi
)[]
| null
- /** Omit missing definitions and custom-property filters incompatible with their current types. */
- ignoreMissingDefinitions?: boolean | null
- /** Include churned accounts. Churned accounts are hidden by default. */
- includeChurned?: boolean | null
- /** Include ignored accounts. Ignored accounts are hidden by default. */
- includeIgnored?: boolean | null
- kind?: 'AccountsTableQuery'
+ kind?: 'ActorsQuery'
limit?: number | null
- /** Aggregates to evaluate against the filtered account set. A metrics query skips row loading. */
- metrics?:
- | (AccountsTableCountMetricApi | AccountsTableAggregateMetricApi | AccountsTableCountThresholdMetricApi)[]
- | null
/** Modifiers used when performing the query */
modifiers?: HogQLQueryModifiersApi | null
offset?: number | null
- response?: AccountsTableQueryResponseApi | null
- sort?: AccountsTableSortApi | null
+ orderBy?: string[] | null
+ /** Currently only person filters supported. No filters for querying groups. See `filter_conditions()` in actor_strategies.py. */
+ properties?:
+ | (
+ | PersonPropertyFilterApi
+ | PersonMetadataPropertyFilterApi
+ | CohortPropertyFilterApi
+ | HogQLPropertyFilterApi
+ | EmptyPropertyFilterApi
+ )[]
+ | PropertyGroupFilterValueApi
+ | null
+ response?: ActorsQueryResponseApi | null
+ search?: string | null
+ select?: string[] | null
+ /** Account membership source for the table. */
+ source: AccountUsersQueryApi
tags?: QueryLogTagsApi | null
- useDefaultColumns?: boolean | null
/** version of the node, used for schema migrations */
version?: number | null
}
-export type BreakdownTypeApi = (typeof BreakdownTypeApi)[keyof typeof BreakdownTypeApi]
-
-export const BreakdownTypeApi = {
- Cohort: 'cohort',
- Person: 'person',
- Event: 'event',
- EventMetadata: 'event_metadata',
- Element: 'element',
- Group: 'group',
- Session: 'session',
- Hogql: 'hogql',
- DataWarehouse: 'data_warehouse',
- DataWarehousePersonProperty: 'data_warehouse_person_property',
- RevenueAnalytics: 'revenue_analytics',
-} as const
+export interface AccountPersonsQueryRequestApi {
+ async?: false | null
+ /** Client provided query ID. Can be used to retrieve the status or cancel the query. */
+ client_query_id?: string | null
+ filters_override?: DashboardFilterApi | null
+ /** Limit context for the query. Only 'posthog_ai' is allowed as a client-provided value. */
+ limit_context?: LimitContextApi | null
+ /** Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name. */
+ name?: string | null
+ /** Account-user table query to run. */
+ query: AccountPersonsActorsQueryApi
+ /** Read cached results or calculate synchronously. */
+ refresh?: AccountPersonsQueryRequestApiRefresh
+ variables_override?: AccountPersonsQueryRequestApiVariablesOverride
+}
-export type MultipleBreakdownTypeApi = (typeof MultipleBreakdownTypeApi)[keyof typeof MultipleBreakdownTypeApi]
+/**
+ * Typed account properties: website_domain, external system identifiers (stripe_customer_id, hubspot_deal_id, billing_id, sfdc_id, zendesk_id, slack_channel_id, usage_dashboard_link, metabase_link), and touchpoint matching lists: email_domains (the company's email domains) and known_emails (individual addresses pinned to the account). Defaults to an empty object. Unknown keys are rejected. User assignments live on account relationships, not here.
+ * @nullable
+ */
+export type PatchedAccountApiProperties = {
+ /**
+ * Primary company website hostname used for account identity and logo lookup.
+ * @nullable
+ */
+ website_domain?: string | null
+ /** Email domains owned by this account's company, used to match inbound touchpoints to the account. */
+ email_domains?: string[]
+ /** Individual email addresses pinned to this account, matched before the domain fallback. */
+ known_emails?: string[]
+ /** @nullable */
+ stripe_customer_id?: string | null
+ /** @nullable */
+ hubspot_deal_id?: string | null
+ /** @nullable */
+ billing_id?: string | null
+ /** @nullable */
+ sfdc_id?: string | null
+ /** @nullable */
+ zendesk_id?: string | null
+ /** @nullable */
+ slack_channel_id?: string | null
+ /** @nullable */
+ usage_dashboard_link?: string | null
+ /** @nullable */
+ metabase_link?: string | null
+} | null | null
-export const MultipleBreakdownTypeApi = {
- Person: 'person',
- Event: 'event',
- EventMetadata: 'event_metadata',
- Element: 'element',
- Group: 'group',
- Session: 'session',
- Hogql: 'hogql',
- Cohort: 'cohort',
- RevenueAnalytics: 'revenue_analytics',
- DataWarehouse: 'data_warehouse',
- DataWarehousePersonProperty: 'data_warehouse_person_property',
+/**
+ * A Customer Analytics account — a logical grouping used to assign customer-success ownership.
+ */
+export interface PatchedAccountApi {
+ readonly id?: string
+ /**
+ * Human-readable name of the account.
+ * @maxLength 400
+ */
+ name?: string
+ /**
+ * Identifier linking this account to its source customer — the analytics group key (the customer's organization id), used to match billing and external records. Optional.
+ * @maxLength 400
+ * @nullable
+ */
+ external_id?: string | null
+ /**
+ * Typed account properties: website_domain, external system identifiers (stripe_customer_id, hubspot_deal_id, billing_id, sfdc_id, zendesk_id, slack_channel_id, usage_dashboard_link, metabase_link), and touchpoint matching lists: email_domains (the company's email domains) and known_emails (individual addresses pinned to the account). Defaults to an empty object. Unknown keys are rejected. User assignments live on account relationships, not here.
+ * @nullable
+ */
+ properties?: PatchedAccountApiProperties
+ /** Tag names attached to the account. Pass a list to replace existing tags. */
+ tags?: string[]
+ /** Short IDs of the internal notebooks linked to this account, used to persist investigations, call notes, and other free-form context. Empty list if no notebooks have been created for the account. */
+ readonly notebooks?: readonly string[]
+ /** How often to generate an AI summary of the account's bound Slack channel (daily, weekly, or monthly). Null means summaries are off.
+ *
+ * * `daily` - daily
+ * * `weekly` - weekly
+ * * `monthly` - monthly */
+ slack_summary_cadence?: SlackSummaryCadenceEnumApi | null
+ /**
+ * When the account churned. Null means the account has not churned.
+ * @nullable
+ */
+ churned_at?: string | null
+ /**
+ * When the account was ignored, set by Track Rules or by hand. Null means the account is tracked.
+ * @nullable
+ */
+ ignored_at?: string | null
+ readonly created_at?: string
+ /** @nullable */
+ readonly created_by?: number | null
+ /** @nullable */
+ readonly updated_at?: string | null
+}
+
+export interface ConversationMessageSenderApi {
+ /** Display name of the message sender. */
+ readonly name: string
+ /**
+ * Email address of the message sender, when available.
+ * @nullable
+ */
+ readonly email: string | null
+ /**
+ * UUID of the matched PostHog person, when available.
+ * @nullable
+ */
+ readonly person_id: string | null
+ /**
+ * Distinct ID of the sender, when available.
+ * @nullable
+ */
+ readonly distinct_id: string | null
+}
+
+/**
+ * * `inbound` - Inbound
+ * * `outbound` - Outbound
+ */
+export type EmailThreadMessageDirectionEnumApi =
+ (typeof EmailThreadMessageDirectionEnumApi)[keyof typeof EmailThreadMessageDirectionEnumApi]
+
+export const EmailThreadMessageDirectionEnumApi = {
+ Inbound: 'inbound',
+ Outbound: 'outbound',
} as const
-export interface BreakdownApi {
- group_type_index?: number | null
- histogram_bin_count?: number | null
- normalize_url?: boolean | null
- property: string | number
- type?: MultipleBreakdownTypeApi | null
+export interface ConversationMessageSummaryApi {
+ /** Sender of the message. */
+ readonly sender: ConversationMessageSenderApi
+ /** Timestamp from the message source. */
+ readonly sent_at: string
+ /** Whether PostHog received or sent the message.
+ *
+ * * `inbound` - Inbound
+ * * `outbound` - Outbound */
+ readonly direction: EmailThreadMessageDirectionEnumApi
+}
+
+/**
+ * * `internal` - Internal
+ * * `customer` - Customer
+ */
+export type EmailThreadParticipantKindEnumApi =
+ (typeof EmailThreadParticipantKindEnumApi)[keyof typeof EmailThreadParticipantKindEnumApi]
+
+export const EmailThreadParticipantKindEnumApi = {
+ Internal: 'internal',
+ Customer: 'customer',
+} as const
+
+export interface AccountEmailThreadParticipantApi {
+ /** Email address of the thread participant. */
+ readonly email: string
+ /** Display name from the captured email headers. */
+ readonly display_name: string
+ /** Whether the participant belongs to the PostHog organization or the customer.
+ *
+ * * `internal` - Internal
+ * * `customer` - Customer */
+ readonly kind: EmailThreadParticipantKindEnumApi
+ /**
+ * UUID of the matched PostHog person for a customer participant, when available.
+ * @nullable
+ */
+ readonly person_id: string | null
+}
+
+export interface AccountEmailThreadApi {
+ /** UUID of the captured email thread. */
+ readonly id: string
+ /** Email thread subject. */
+ readonly subject: string
+ /** Plain-text preview of the latest captured message. */
+ readonly preview: string
+ /**
+ * Source timestamp of the first captured message.
+ * @nullable
+ */
+ readonly first_message_at: string | null
+ /** Sender, timestamp, and direction of the first captured message, when available. */
+ readonly first_message: ConversationMessageSummaryApi | null
+ /**
+ * Source timestamp of the latest captured message.
+ * @nullable
+ */
+ readonly last_message_at: string | null
+ /** Sender, timestamp, and direction of the latest captured message, when available. */
+ readonly last_message: ConversationMessageSummaryApi | null
+ /** Number of captured messages in the thread. */
+ readonly message_count: number
+ /** Participants included in the email thread. */
+ readonly participants: readonly AccountEmailThreadParticipantApi[]
+}
+
+export interface PaginatedAccountEmailThreadListApi {
+ count: number
+ /** @nullable */
+ next?: string | null
+ /** @nullable */
+ previous?: string | null
+ results: AccountEmailThreadApi[]
+}
+
+export interface AccountEmailThreadAddressApi {
+ /** Name from the email header. */
+ readonly name: string
+ /** Email address from the email header. */
+ readonly email: string
+}
+
+export interface AccountEmailThreadMessageApi {
+ /** UUID of the captured email message. */
+ readonly id: string
+ /** Timestamp from the source email. */
+ readonly sent_at: string
+ /** Sender from the email From header. */
+ readonly sender: AccountEmailThreadAddressApi
+ /** Recipients from the email To header. */
+ readonly to_recipients: readonly AccountEmailThreadAddressApi[]
+ /** Recipients from the email Cc header. */
+ readonly cc_recipients: readonly AccountEmailThreadAddressApi[]
+ /** Whether Mailgun authentication verified the sender domain. */
+ readonly sender_authenticated: boolean
+ /** Whether PostHog received or sent the message.
+ *
+ * * `inbound` - Inbound
+ * * `outbound` - Outbound */
+ readonly direction: EmailThreadMessageDirectionEnumApi
+ /** Plain-text email content. */
+ readonly content: string
+}
+
+export interface PaginatedAccountEmailThreadMessageListApi {
+ count: number
+ /** @nullable */
+ next?: string | null
+ /** @nullable */
+ previous?: string | null
+ results: AccountEmailThreadMessageApi[]
+}
+
+/**
+ * One attendee of a synced calendar meeting (read-only).
+ */
+export interface MeetingParticipantApi {
+ /** Email address of the attendee. */
+ readonly email: string
+ /** Display name from the calendar event; may be empty. */
+ readonly display_name: string
+ /** The attendee's RSVP: 'needs_action', 'accepted', 'declined', or 'tentative'. */
+ readonly response_status: string
+ /** Whether this attendee organized the meeting. */
+ readonly is_organizer: boolean
+ /**
+ * UUID of the PostHog person resolved for this attendee, if any.
+ * @nullable
+ */
+ readonly person_id: string | null
+}
+
+/**
+ * A calendar meeting synced from a connected employee calendar (read-only).
+ */
+export interface MeetingApi {
+ /** UUID of the meeting. */
+ readonly id: string
+ /** Meeting title; may be empty. */
+ readonly title: string
+ /** Whether the meeting belongs to a recurring series. Account meeting lists include all past occurrences and only the next upcoming, non-canceled occurrence of each series. */
+ readonly is_recurring: boolean
+ /**
+ * Gong call URL matched through the calendar event id; null when no Gong call is available.
+ * @nullable
+ */
+ readonly gong_url: string | null
+ /** When the meeting starts. */
+ readonly start_time: string
+ /**
+ * When the meeting ends.
+ * @nullable
+ */
+ readonly end_time: string | null
+ /** Email address of the meeting organizer; may be empty. */
+ readonly organizer_email: string
+ /** Meeting status: 'confirmed', 'tentative', or 'cancelled'. */
+ readonly status: string
+ /** Attendees of the meeting. */
+ readonly participants: readonly MeetingParticipantApi[]
+}
+
+export interface PaginatedMeetingListApi {
+ count: number
+ /** @nullable */
+ next?: string | null
+ /** @nullable */
+ previous?: string | null
+ results: MeetingApi[]
+}
+
+export interface AccountPresenceViewerApi {
+ /** PostHog user ID of the teammate viewing this account. */
+ readonly user_id: number
+ /** Display name of the teammate viewing this account. */
+ readonly display_name: string
+}
+
+/**
+ * Metadata for one message a channel summary covered — never the message text.
+ */
+export interface ChannelSummaryMessageApi {
+ /** Display name of the message author. */
+ readonly author: string
+ /** When the message was sent. */
+ readonly sent_at: string
+ /** Slack permalink to the message. */
+ readonly permalink: string
+}
+
+/**
+ * An AI summary of one closed period of the account's bound Slack channel (read-only).
+ */
+export interface AccountChannelSummaryApi {
+ /** UUID of the summary. */
+ readonly id: string
+ /** Slack channel the summary covered — kept even if the account is later rebound. */
+ readonly slack_channel_id: string
+ /** Cadence the summarized period belongs to (daily, weekly, or monthly).
+ *
+ * * `daily` - daily
+ * * `weekly` - weekly
+ * * `monthly` - monthly */
+ readonly cadence: SlackSummaryCadenceEnumApi
+ /** Start of the summarized period (inclusive). */
+ readonly period_start: string
+ /** End of the summarized period (exclusive). */
+ readonly period_end: string
+ /** Markdown summary citing the original Slack messages with permalinks. */
+ readonly content: string
+ /** Number of channel messages the summary covered. */
+ readonly message_count: number
+ /** The messages the summary covered, in transcript order — metadata only, no message text. */
+ readonly messages: readonly ChannelSummaryMessageApi[]
+ /** When the summary was generated. */
+ readonly generated_at: string
+}
+
+export interface PaginatedAccountChannelSummaryListApi {
+ count: number
+ /** @nullable */
+ next?: string | null
+ /** @nullable */
+ previous?: string | null
+ results: AccountChannelSummaryApi[]
+}
+
+/**
+ * A support ticket linked to an account, sourced from the conversations product (read-only).
+ */
+export interface SupportTicketApi {
+ /** UUID of the support ticket. */
+ readonly id: string
+ /** Human-readable ticket number. */
+ readonly ticket_number: number
+ /** Current status of the ticket (e.g. 'new', 'open'). */
+ readonly status: string
+ /**
+ * When the most recent message was sent on this ticket.
+ * @nullable
+ */
+ readonly last_message_at: string | null
+ /**
+ * Truncated preview of the most recent message.
+ * @nullable
+ */
+ readonly last_message_text: string | null
+ /** Sender, timestamp, and direction of the latest public message, when available. */
+ readonly last_message: ConversationMessageSummaryApi | null
+ /** Absolute URL to open this ticket in the app. */
+ readonly deep_link: string
+ /** When the ticket conversation started. */
+ readonly created_at: string
+ /** Display name of the customer who started the ticket. */
+ readonly started_by: string
+ /** Distinct ID of the customer who started the ticket. */
+ readonly distinct_id: string
+}
+
+export interface AccountSupportTicketMessageApi {
+ /** UUID of the support ticket message. */
+ readonly id: string
+ /** Plain-text message content. */
+ readonly content: string
+ /** Display name of the message author. */
+ readonly author_name: string
+ /** Whether PostHog received or sent the message.
+ *
+ * * `inbound` - Inbound
+ * * `outbound` - Outbound */
+ readonly direction: EmailThreadMessageDirectionEnumApi
+ /** Whether the message is an internal note hidden from the customer. */
+ readonly is_private: boolean
+ /** When the message was created. */
+ readonly created_at: string
+}
+
+export interface PaginatedAccountSupportTicketMessageListApi {
+ count: number
+ /** @nullable */
+ next?: string | null
+ /** @nullable */
+ previous?: string | null
+ results: AccountSupportTicketMessageApi[]
}
-export interface BreakdownFilterApi {
- breakdown?: string | (string | number)[] | number | null
- breakdown_group_type_index?: number | null
- breakdown_hide_other_aggregation?: boolean | null
- breakdown_histogram_bin_count?: number | null
- breakdown_limit?: number | null
- breakdown_normalize_url?: boolean | null
- breakdown_path_cleaning?: boolean | null
- breakdown_type?: BreakdownTypeApi | null
- breakdowns?: BreakdownApi[] | null
+export interface AccountPresenceListRequestApi {
+ /**
+ * Up to 100 account IDs to read presence for.
+ * @maxItems 100
+ */
+ account_ids: string[]
}
-export interface CompareFilterApi {
- /** Whether to compare the current date range to a previous date range. */
- compare?: boolean | null
- /** The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. */
- compare_to?: string | null
+export interface AccountPresenceApi {
+ /** Customer analytics account ID. */
+ readonly account_id: string
+ /** People viewing this account. */
+ readonly viewers: readonly AccountPresenceViewerApi[]
}
-export type IntervalTypeApi = (typeof IntervalTypeApi)[keyof typeof IntervalTypeApi]
+export type AccountsTableQueryRequestApiVariablesOverride = { [key: string]: { [key: string]: unknown } } | null
-export const IntervalTypeApi = {
- Second: 'second',
- Minute: 'minute',
- Hour: 'hour',
- Day: 'day',
- Week: 'week',
- Month: 'month',
- Quarter: 'quarter',
- Year: 'year',
+export type AccountsTableAccountFieldApi =
+ (typeof AccountsTableAccountFieldApi)[keyof typeof AccountsTableAccountFieldApi]
+
+export const AccountsTableAccountFieldApi = {
+ Name: 'name',
+ ExternalId: 'external_id',
+ CreatedAt: 'created_at',
+ UpdatedAt: 'updated_at',
+ ChurnedAt: 'churned_at',
+ IgnoredAt: 'ignored_at',
+ StripeCustomerId: 'stripe_customer_id',
+ HubspotDealId: 'hubspot_deal_id',
+ BillingId: 'billing_id',
+ SfdcId: 'sfdc_id',
+ ZendeskId: 'zendesk_id',
} as const
-export type MetricsFilterOpApi = (typeof MetricsFilterOpApi)[keyof typeof MetricsFilterOpApi]
+export interface AccountsTableAccountFieldColumnApi {
+ field: AccountsTableAccountFieldApi
+ kind?: 'account_field'
+}
-export const MetricsFilterOpApi = {
- Eq: 'eq',
- Neq: 'neq',
- Regex: 'regex',
- NotRegex: 'not_regex',
+export const AccountsTableTagsColumnApiValue = {
+ kind: 'tags',
} as const
+export type AccountsTableTagsColumnApi = typeof AccountsTableTagsColumnApiValue
-export type MetricsAttributeScopeApi = (typeof MetricsAttributeScopeApi)[keyof typeof MetricsAttributeScopeApi]
-
-export const MetricsAttributeScopeApi = {
- Resource: 'resource',
- Attribute: 'attribute',
- Auto: 'auto',
+export const AccountsTableNoteCountColumnApiValue = {
+ kind: 'note_count',
} as const
+export type AccountsTableNoteCountColumnApi = typeof AccountsTableNoteCountColumnApiValue
-export interface MetricsQueryFilterApi {
- key: string
- op: MetricsFilterOpApi
- scope?: MetricsAttributeScopeApi | null
- value: string
+export interface AccountsTableRelationshipColumnApi {
+ /** Team-scoped relationship definition to return for each account. */
+ definitionId: string
+ kind?: 'relationship'
}
-export interface MetricsDashboardVariableSelectionApi {
- all?: boolean | null
- /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
- values: string[]
+export interface AccountsTableCustomPropertyColumnApi {
+ /** Team-scoped custom property definition to return for each account. */
+ definitionId: string
+ kind?: 'custom_property'
}
-export type MetricsDashboardVariableSourceApi =
- (typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
+export type WindowDaysApi = (typeof WindowDaysApi)[keyof typeof WindowDaysApi]
-export const MetricsDashboardVariableSourceApi = {
- Custom: 'custom',
- Promql: 'promql',
- Sql: 'sql',
- Textbox: 'textbox',
+export const WindowDaysApi = {
+ Number7: 7,
+ Number14: 14,
+ Number30: 30,
+ Number90: 90,
} as const
-export interface MetricsDashboardVariableApi {
- /** The text that All puts in a PromQL query. `.*` when it is empty. */
- allValue?: string | null
- current?: MetricsDashboardVariableSelectionApi | null
- /** The options when `source` is `custom`. */
- customValues?: string[] | null
- includeAll?: boolean | null
- /** Shown in the dashboard filter bar. The name is shown when it is empty. */
- label?: string | null
- multi?: boolean | null
- /** Letters, digits and underscores. Tiles refer to it as `$name`. */
- name: string
- /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
- query?: string | null
- /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
- regex?: string | null
- source: MetricsDashboardVariableSourceApi
+export interface AccountsTableCustomPropertyHistoryColumnApi {
+ /** Team-scoped numeric custom property definition whose write history should be returned. */
+ definitionId: string
+ kind?: 'custom_property_history'
+ /** Number of days of history to return. The current value is included even when it is older. */
+ windowDays: WindowDaysApi
}
-export type PropertyOperatorApi = (typeof PropertyOperatorApi)[keyof typeof PropertyOperatorApi]
+export type AccountsTableAccountFieldOperatorApi =
+ (typeof AccountsTableAccountFieldOperatorApi)[keyof typeof AccountsTableAccountFieldOperatorApi]
-export const PropertyOperatorApi = {
+export const AccountsTableAccountFieldOperatorApi = {
Exact: 'exact',
IsNot: 'is_not',
Icontains: 'icontains',
NotIcontains: 'not_icontains',
- StartsWith: 'starts_with',
- NotStartsWith: 'not_starts_with',
- EndsWith: 'ends_with',
- NotEndsWith: 'not_ends_with',
- Regex: 'regex',
- NotRegex: 'not_regex',
- Gt: 'gt',
- Gte: 'gte',
- Lt: 'lt',
- Lte: 'lte',
IsSet: 'is_set',
IsNotSet: 'is_not_set',
IsDateExact: 'is_date_exact',
IsDateBefore: 'is_date_before',
IsDateAfter: 'is_date_after',
- Between: 'between',
- NotBetween: 'not_between',
- Min: 'min',
- Max: 'max',
- In: 'in',
- NotIn: 'not_in',
- IsCleanedPathExact: 'is_cleaned_path_exact',
- IsCleanedPathNotExact: 'is_cleaned_path_not_exact',
- FlagEvaluatesTo: 'flag_evaluates_to',
- SemverEq: 'semver_eq',
- SemverNeq: 'semver_neq',
- SemverGt: 'semver_gt',
- SemverGte: 'semver_gte',
- SemverLt: 'semver_lt',
- SemverLte: 'semver_lte',
- SemverTilde: 'semver_tilde',
- SemverCaret: 'semver_caret',
- SemverWildcard: 'semver_wildcard',
- IcontainsMulti: 'icontains_multi',
- NotIcontainsMulti: 'not_icontains_multi',
-} as const
-
-export interface EventPropertyFilterApi {
- key: string
- label?: string | null
- operator?: PropertyOperatorApi | null
- /** Event properties */
- type?: 'event'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
-
-export interface PersonPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- /** Person properties */
- type?: 'person'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
-
-export interface PersonMetadataPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- /** Top-level columns on the persons table (e.g. created_at), not properties JSON */
- type?: 'person_metadata'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
-
-export type Key10Api = (typeof Key10Api)[keyof typeof Key10Api]
-
-export const Key10Api = {
- TagName: 'tag_name',
- Text: 'text',
- Href: 'href',
- Selector: 'selector',
-} as const
-
-export interface ElementPropertyFilterApi {
- key: Key10Api
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'element'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
-
-export interface EventMetadataPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'event_metadata'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
-
-export interface SessionPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'session'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
-
-export interface CohortPropertyFilterApi {
- /** Set by the feature flag API when the cohort is deleted or does not exist. */
- cohort_deleted?: boolean | null
- /** Set by the feature flag API when the cohort does not exist, so it cannot be restored. */
- cohort_missing?: boolean | null
- cohort_name?: string | null
- key?: 'id'
- label?: string | null
- operator?: PropertyOperatorApi | null
- type?: 'cohort'
- value: number
+} as const
+
+export interface AccountsTableAccountFieldFilterApi {
+ field: AccountsTableAccountFieldApi
+ kind?: 'account_field'
+ operator: AccountsTableAccountFieldOperatorApi
+ values?: string[] | null
}
-export type DurationTypeApi = (typeof DurationTypeApi)[keyof typeof DurationTypeApi]
+export type AccountsTableRelationshipOperatorApi =
+ (typeof AccountsTableRelationshipOperatorApi)[keyof typeof AccountsTableRelationshipOperatorApi]
-export const DurationTypeApi = {
- Duration: 'duration',
- ActiveSeconds: 'active_seconds',
- InactiveSeconds: 'inactive_seconds',
+export const AccountsTableRelationshipOperatorApi = {
+ Exact: 'exact',
+ IsNot: 'is_not',
+ IsSet: 'is_set',
+ IsNotSet: 'is_not_set',
} as const
-export interface RecordingPropertyFilterApi {
- key: DurationTypeApi | string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'recording'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableRelationshipFilterApi {
+ definitionId: string
+ kind?: 'relationship'
+ operator: AccountsTableRelationshipOperatorApi
+ userIds?: number[] | null
}
-export interface LogEntryPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'log_entry'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
+export type AccountsTableCustomPropertyOperatorApi =
+ (typeof AccountsTableCustomPropertyOperatorApi)[keyof typeof AccountsTableCustomPropertyOperatorApi]
-export type GroupPropertyFilterApiGroupKeyNames = { [key: string]: string } | null
+export const AccountsTableCustomPropertyOperatorApi = {
+ Exact: 'exact',
+ IsNot: 'is_not',
+ Icontains: 'icontains',
+ NotIcontains: 'not_icontains',
+ Regex: 'regex',
+ NotRegex: 'not_regex',
+ Gt: 'gt',
+ Gte: 'gte',
+ Lt: 'lt',
+ Lte: 'lte',
+ IsSet: 'is_set',
+ IsNotSet: 'is_not_set',
+ IsDateExact: 'is_date_exact',
+ IsDateBefore: 'is_date_before',
+ IsDateAfter: 'is_date_after',
+} as const
-export interface GroupPropertyFilterApi {
- group_key_names?: GroupPropertyFilterApiGroupKeyNames
- group_type_index?: number | null
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'group'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableCustomPropertyFilterApi {
+ definitionId: string
+ kind?: 'custom_property'
+ operator: AccountsTableCustomPropertyOperatorApi
+ /** Values interpreted according to the custom property definition's display type. */
+ values?: (string | number | boolean)[] | null
}
-export interface FeaturePropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- /** Event property with "$feature/" prepended */
- type?: 'feature'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableSearchFilterApi {
+ kind?: 'search'
+ query: string
}
-export interface FlagPropertyFilterApi {
- /** The key should be the flag ID */
- key: string
- label?: string | null
- /** Only flag_evaluates_to operator is allowed for flag dependencies */
- operator?: 'flag_evaluates_to'
- /** Feature flag dependency */
- type?: 'flag'
- /** The value can be true, false, or a variant name */
- value: boolean | string
+export interface AccountsTableTagsFilterApi {
+ kind?: 'tags'
+ /** Match accounts carrying any of these tag names. */
+ tagNames: string[]
}
-export interface HogQLPropertyFilterApi {
- key: string
- label?: string | null
- type?: 'hogql'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableAssignedToFilterApi {
+ kind?: 'assigned_to'
+ /** Match accounts where any listed user actively holds any relationship. */
+ userIds: number[]
}
-export const EmptyPropertyFilterApiValue = {
- type: 'empty',
+export const AccountsTableAssignedFilterApiValue = {
+ kind: 'assigned',
} as const
-export type EmptyPropertyFilterApi = typeof EmptyPropertyFilterApiValue
+export type AccountsTableAssignedFilterApi = typeof AccountsTableAssignedFilterApiValue
-export interface DataWarehousePropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'data_warehouse'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
+export const AccountsTableUnassignedFilterApiValue = {
+ kind: 'unassigned',
+} as const
+export type AccountsTableUnassignedFilterApi = typeof AccountsTableUnassignedFilterApiValue
-export interface DataWarehousePersonPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'data_warehouse_person_property'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableAccountIdFilterApi {
+ accountId: string
+ kind?: 'account_id'
}
-export interface ErrorTrackingIssueFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'error_tracking_issue'
- value?: (string | number | boolean)[] | string | number | boolean | null
-}
+export const AccountsTableCountMetricApiValue = {
+ kind: 'count',
+} as const
+export type AccountsTableCountMetricApi = typeof AccountsTableCountMetricApiValue
-export type LogPropertyFilterTypeApi = (typeof LogPropertyFilterTypeApi)[keyof typeof LogPropertyFilterTypeApi]
+export type AccountsTableAggregationApi = (typeof AccountsTableAggregationApi)[keyof typeof AccountsTableAggregationApi]
-export const LogPropertyFilterTypeApi = {
- Log: 'log',
- LogAttribute: 'log_attribute',
- LogResourceAttribute: 'log_resource_attribute',
+export const AccountsTableAggregationApi = {
+ Sum: 'sum',
+ Avg: 'avg',
+ Min: 'min',
+ Max: 'max',
+ Median: 'median',
} as const
-export interface LogPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type: LogPropertyFilterTypeApi
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableAggregateMetricApi {
+ aggregation: AccountsTableAggregationApi
+ column: AccountsTableCustomPropertyColumnApi
+ kind?: 'aggregate'
+ scale?: number | null
}
-export interface MetricPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'metric_attribute'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export type AccountsTableThresholdOperatorApi =
+ (typeof AccountsTableThresholdOperatorApi)[keyof typeof AccountsTableThresholdOperatorApi]
+
+export const AccountsTableThresholdOperatorApi = {
+ Gt: 'gt',
+ Gte: 'gte',
+ Lt: 'lt',
+ Lte: 'lte',
+ Exact: 'exact',
+ IsNot: 'is_not',
+} as const
+
+export interface AccountsTableCountThresholdMetricApi {
+ column: AccountsTableCustomPropertyColumnApi
+ kind?: 'count_threshold'
+ operator: AccountsTableThresholdOperatorApi
+ value: number
}
-export type SpanPropertyFilterTypeApi = (typeof SpanPropertyFilterTypeApi)[keyof typeof SpanPropertyFilterTypeApi]
+export type AccountsTableCustomPropertyDisplayTypeApi =
+ (typeof AccountsTableCustomPropertyDisplayTypeApi)[keyof typeof AccountsTableCustomPropertyDisplayTypeApi]
-export const SpanPropertyFilterTypeApi = {
- Span: 'span',
- SpanAttribute: 'span_attribute',
- SpanResourceAttribute: 'span_resource_attribute',
+export const AccountsTableCustomPropertyDisplayTypeApi = {
+ Text: 'text',
+ Link: 'link',
+ Number: 'number',
+ Currency: 'currency',
+ Percent: 'percent',
+ Date: 'date',
+ Datetime: 'datetime',
+ Boolean: 'boolean',
+ Select: 'select',
} as const
-export interface SpanPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type: SpanPropertyFilterTypeApi
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableCustomPropertyOptionApi {
+ color: string
+ id?: string | null
+ label: string
}
-export interface RevenueAnalyticsPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'revenue_analytics'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableCustomPropertySourceApi {
+ id: string
}
-export interface AccountCustomPropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- /** Customer analytics account custom property — the key is the property definition id */
- type?: 'account_custom_property'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableCustomPropertyDefinitionApi {
+ description?: string | null
+ display_type: AccountsTableCustomPropertyDisplayTypeApi
+ has_workflow_reference: boolean
+ id: string
+ is_big_number?: boolean | null
+ is_canonical: boolean
+ name: string
+ options?: AccountsTableCustomPropertyOptionApi[] | null
+ source?: AccountsTableCustomPropertySourceApi | null
}
-export interface WorkflowVariablePropertyFilterApi {
- key: string
- label?: string | null
- operator: PropertyOperatorApi
- type?: 'workflow_variable'
- value?: (string | number | boolean)[] | string | number | boolean | null
+export interface AccountsTableRelationshipDefinitionApi {
+ description?: string | null
+ id: string
+ is_controlled: boolean
+ is_single_holder?: boolean | null
+ name: string
}
-export type BehavioralEventSourceApi = (typeof BehavioralEventSourceApi)[keyof typeof BehavioralEventSourceApi]
+export interface AccountsTableCustomPropertyHistoryPointApi {
+ timestamp: string
+ value: number
+}
-export const BehavioralEventSourceApi = {
- Events: 'events',
- Actions: 'actions',
-} as const
+/**
+ * Requested direct Account fields, keyed by their typed field reference.
+ */
+export type AccountsTableRowApiAccountFields = { [key: string]: string | null }
-export type TimeUnitTypeApi = (typeof TimeUnitTypeApi)[keyof typeof TimeUnitTypeApi]
+/**
+ * Current values keyed by requested custom property definition ID.
+ */
+export type AccountsTableRowApiCustomProperties = { [key: string]: string | number | boolean | null }
-export const TimeUnitTypeApi = {
- Day: 'day',
- Week: 'week',
- Month: 'month',
- Year: 'year',
-} as const
+/**
+ * Numeric write history keyed by requested custom property definition ID.
+ */
+export type AccountsTableRowApiCustomPropertyHistory = { [key: string]: AccountsTableCustomPropertyHistoryPointApi[] }
-export type InlineBehavioralTypeApi = (typeof InlineBehavioralTypeApi)[keyof typeof InlineBehavioralTypeApi]
+/**
+ * Active assignee user IDs keyed by requested relationship definition ID.
+ */
+export type AccountsTableRowApiRelationships = { [key: string]: number[] }
-export const InlineBehavioralTypeApi = {
- PerformedEvent: 'performed_event',
- PerformedEventMultiple: 'performed_event_multiple',
-} as const
+export interface AccountsTableRowApi {
+ /** Requested direct Account fields, keyed by their typed field reference. */
+ accountFields: AccountsTableRowApiAccountFields
+ /** Current values keyed by requested custom property definition ID. */
+ customProperties: AccountsTableRowApiCustomProperties
+ /** Numeric write history keyed by requested custom property definition ID. */
+ customPropertyHistory: AccountsTableRowApiCustomPropertyHistory
+ externalId?: string | null
+ id: string
+ /** Bare hostname the row's logo is rendered from. Null when no source resolved one. */
+ logoDomain?: string | null
+ name: string
+ /** Number of linked internal notes. Omitted when the request does not select the note count. */
+ noteCount?: number | null
+ /** Active assignee user IDs keyed by requested relationship definition ID. */
+ relationships: AccountsTableRowApiRelationships
+ /** Sorted tag names. Omitted when the request does not select tags. */
+ tags?: string[] | null
+}
-export interface BehavioralPropertyFilterApi {
- /** Extra property filters the matching events must satisfy. Deliberately excludes nested behavioral/cohort filters and groups */
- event_filters?:
+export interface AccountsTableQueryResponseApi {
+ columns?:
| (
- | EventPropertyFilterApi
- | PersonPropertyFilterApi
- | ElementPropertyFilterApi
- | FeaturePropertyFilterApi
- | HogQLPropertyFilterApi
+ | AccountsTableAccountFieldColumnApi
+ | AccountsTableTagsColumnApi
+ | AccountsTableNoteCountColumnApi
+ | AccountsTableRelationshipColumnApi
+ | AccountsTableCustomPropertyColumnApi
+ | AccountsTableCustomPropertyHistoryColumnApi
)[]
| null
- event_type: BehavioralEventSourceApi
- /** Absolute or relative (e.g. -30d) lower date bound — alternative to time_value/time_interval */
- explicit_datetime?: string | null
- explicit_datetime_to?: string | null
- /** Event name, or action id when event_type is 'actions' */
- key: string
- label?: string | null
- /** Match persons who did NOT satisfy the criterion. Not the same as a low count — zero-occurrence persons never match count operators */
- negation?: boolean | null
- /** Count comparison for performed_event_multiple, defaults to exact */
- operator?: PropertyOperatorApi | null
- /** Count threshold for performed_event_multiple */
- operator_value?: number | null
- time_interval?: TimeUnitTypeApi | null
- /** Relative time window size, paired with time_interval */
- time_value?: number | null
- /** Person performed (or didn't perform) an event in a time window. ClickHouse-only — not evaluable by flags or CDP */
- type?: 'behavioral'
- value: InlineBehavioralTypeApi
+ customPropertyDefinitions?: AccountsTableCustomPropertyDefinitionApi[] | null
+ /** Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. */
+ error?: string | null
+ hasMore: boolean
+ /** Generated HogQL query. */
+ hogql?: string | null
+ kind?: 'AccountsTableQuery'
+ limit: number
+ /** Aggregated values in the same order as the requested metrics. */
+ metricsResults?: (number | null)[] | null
+ /** Modifiers used when performing the query */
+ modifiers?: HogQLQueryModifiersApi | null
+ offset: number
+ /** Query status indicates whether next to the provided data, a query is still running. */
+ query_status?: QueryStatusApi | null
+ relationshipDefinitions?: AccountsTableRelationshipDefinitionApi[] | null
+ /** The resolved previous/comparison period date range, when comparing against another period */
+ resolved_compare_date_range?: ResolvedDateRangeResponseApi | null
+ /** The date range used for the query */
+ resolved_date_range?: ResolvedDateRangeResponseApi | null
+ results: AccountsTableRowApi[]
+ /** Measured timings for different parts of the query generation process */
+ timings?: QueryTimingApi[] | null
+ /** Connector-synced data warehouse sources referenced by this query, if any. */
+ used_data_warehouse_sources?: DataWarehouseSourceUsageApi[] | null
+ /** Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. */
+ warnings?: (DataWarehouseSyncWarningApi | AccessControlFilterWarningApi)[] | null
}
-export interface DashboardFilterApi {
- breakdown_filter?: BreakdownFilterApi | null
- /** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
- compareFilter?: CompareFilterApi | null
- date_from?: string | null
- date_to?: string | null
- explicitDate?: boolean | null
- /** Tri-state test-account override. Null/absent = inherit; true = force on; false = force off. */
- filterTestAccounts?: boolean | null
- /** Time granularity forced onto every insight that supports one. Absent/null = inherit. */
- interval?: IntervalTypeApi | null
- metricFilters?: MetricsQueryFilterApi[] | null
- /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
- metricVariables?: MetricsDashboardVariableApi[] | null
- properties?:
+export type AccountsTableSortDirectionApi =
+ (typeof AccountsTableSortDirectionApi)[keyof typeof AccountsTableSortDirectionApi]
+
+export const AccountsTableSortDirectionApi = {
+ Asc: 'asc',
+ Desc: 'desc',
+} as const
+
+export interface AccountsTableSortApi {
+ /** A typed column that supports server-side sorting. */
+ column:
+ | AccountsTableAccountFieldColumnApi
+ | AccountsTableTagsColumnApi
+ | AccountsTableNoteCountColumnApi
+ | AccountsTableRelationshipColumnApi
+ | AccountsTableCustomPropertyColumnApi
+ direction: AccountsTableSortDirectionApi
+}
+
+export interface AccountsTableQueryApi {
+ /** Columns to load for each account. Account identity fields are always returned. */
+ columns: (
+ | AccountsTableAccountFieldColumnApi
+ | AccountsTableTagsColumnApi
+ | AccountsTableNoteCountColumnApi
+ | AccountsTableRelationshipColumnApi
+ | AccountsTableCustomPropertyColumnApi
+ | AccountsTableCustomPropertyHistoryColumnApi
+ )[]
+ /** Nonempty property-filter groups are ORed together; filters within each group use AND. Global filters still apply. */
+ filterGroups?:
| (
- | EventPropertyFilterApi
- | PersonPropertyFilterApi
- | PersonMetadataPropertyFilterApi
- | ElementPropertyFilterApi
- | EventMetadataPropertyFilterApi
- | SessionPropertyFilterApi
- | CohortPropertyFilterApi
- | RecordingPropertyFilterApi
- | LogEntryPropertyFilterApi
- | GroupPropertyFilterApi
- | FeaturePropertyFilterApi
- | FlagPropertyFilterApi
- | HogQLPropertyFilterApi
- | EmptyPropertyFilterApi
- | DataWarehousePropertyFilterApi
- | DataWarehousePersonPropertyFilterApi
- | ErrorTrackingIssueFilterApi
- | LogPropertyFilterApi
- | MetricPropertyFilterApi
- | SpanPropertyFilterApi
- | RevenueAnalyticsPropertyFilterApi
- | AccountCustomPropertyFilterApi
- | WorkflowVariablePropertyFilterApi
- | BehavioralPropertyFilterApi
+ | AccountsTableAccountFieldFilterApi
+ | AccountsTableRelationshipFilterApi
+ | AccountsTableCustomPropertyFilterApi
+ )[][]
+ | null
+ /** Filters are combined with AND. Values within tag and assignment filters use OR. */
+ filters?:
+ | (
+ | AccountsTableSearchFilterApi
+ | AccountsTableTagsFilterApi
+ | AccountsTableAssignedToFilterApi
+ | AccountsTableAssignedFilterApi
+ | AccountsTableUnassignedFilterApi
+ | AccountsTableRelationshipFilterApi
+ | AccountsTableAccountIdFilterApi
+ | AccountsTableAccountFieldFilterApi
+ | AccountsTableCustomPropertyFilterApi
)[]
| null
+ /** Omit missing definitions and custom-property filters incompatible with their current types. */
+ ignoreMissingDefinitions?: boolean | null
+ /** Include churned accounts. Churned accounts are hidden by default. */
+ includeChurned?: boolean | null
+ /** Include ignored accounts. Ignored accounts are hidden by default. */
+ includeIgnored?: boolean | null
+ kind?: 'AccountsTableQuery'
+ limit?: number | null
+ /** Aggregates to evaluate against the filtered account set. A metrics query skips row loading. */
+ metrics?:
+ | (AccountsTableCountMetricApi | AccountsTableAggregateMetricApi | AccountsTableCountThresholdMetricApi)[]
+ | null
+ /** Modifiers used when performing the query */
+ modifiers?: HogQLQueryModifiersApi | null
+ offset?: number | null
+ response?: AccountsTableQueryResponseApi | null
+ sort?: AccountsTableSortApi | null
+ tags?: QueryLogTagsApi | null
+ useDefaultColumns?: boolean | null
+ /** version of the node, used for schema migrations */
+ version?: number | null
}
-export type LimitContextApi = (typeof LimitContextApi)[keyof typeof LimitContextApi]
-
-export const LimitContextApi = {
- PosthogAi: 'posthog_ai',
-} as const
-
export type RefreshTypeApi = (typeof RefreshTypeApi)[keyof typeof RefreshTypeApi]
export const RefreshTypeApi = {
@@ -5020,6 +5199,55 @@ export type AccountsRelationshipsListParams = {
include_history?: boolean
}
+export type AccountsPersonsRetrieveParams = {
+ /**
+ * JSON array of person property filters with key, operator, value, and type="person". Filters use AND.
+ */
+ filters?: string
+ /**
+ * Maximum persons per page.
+ * @minimum 1
+ * @maximum 500
+ */
+ limit?: number
+ /**
+ * Number of matching persons to skip.
+ * @minimum 0
+ */
+ offset?: number
+ /**
+ * JSON array of selected person property keys. Example: ["email", "name"].
+ */
+ properties?: string
+ /**
+ * Search name, email, person ID, or distinct ID.
+ * @maxLength 1000
+ */
+ search?: string
+ /**
+ * Sort by id, display_name, account_first_seen, account_last_seen, or a selected property key.
+ * @minLength 1
+ * @maxLength 1000
+ */
+ sort_column?: string
+ /**
+ * Sort direction. Person ID breaks ties.
+ *
+ * * `asc` - Ascending
+ * * `desc` - Descending
+ * @minLength 1
+ */
+ sort_direction?: AccountsPersonsRetrieveSortDirection
+}
+
+export type AccountsPersonsRetrieveSortDirection =
+ (typeof AccountsPersonsRetrieveSortDirection)[keyof typeof AccountsPersonsRetrieveSortDirection]
+
+export const AccountsPersonsRetrieveSortDirection = {
+ Asc: 'asc',
+ Desc: 'desc',
+} as const
+
export type AccountsEmailThreadsListParams = {
/**
* Number of results to return per page.
diff --git a/products/customer_analytics/frontend/generated/api.ts b/products/customer_analytics/frontend/generated/api.ts
index 99e1e42e46cb..84b7467b1ad3 100644
--- a/products/customer_analytics/frontend/generated/api.ts
+++ b/products/customer_analytics/frontend/generated/api.ts
@@ -12,6 +12,8 @@ import type {
AccountApi,
AccountNotebookApi,
AccountNotesListParams,
+ AccountPersonsPageApi,
+ AccountPersonsQueryRequestApi,
AccountPresenceApi,
AccountPresenceListRequestApi,
AccountPresenceViewerApi,
@@ -34,11 +36,13 @@ import type {
AccountsListParams,
AccountsMeetingsListParams,
AccountsNotebooksListParams,
+ AccountsPersonsRetrieveParams,
AccountsRelationshipsListParams,
AccountsSummariesListParams,
AccountsSupportTicketMessagesListParams,
AccountsTableQueryRequestApi,
AccountsTableQueryResponseApi,
+ ActorsQueryResponseApi,
AnnouncementApi,
AnnouncementChannelApi,
AnnouncementsListParams,
@@ -814,6 +818,59 @@ export const accountsRelationshipsEndCreate = async (
})
}
+export const getAccountsPersonsRetrieveUrl = (
+ projectId: string,
+ id: string,
+ params?: AccountsPersonsRetrieveParams
+) => {
+ const normalizedParams = new URLSearchParams()
+
+ Object.entries(params || {}).forEach(([key, value]) => {
+ if (value !== undefined) {
+ normalizedParams.append(key, value === null ? 'null' : String(value))
+ }
+ })
+
+ const stringifiedParams = normalizedParams.toString()
+
+ return stringifiedParams.length > 0
+ ? `/api/projects/${projectId}/accounts/${id}/persons/?${stringifiedParams}`
+ : `/api/projects/${projectId}/accounts/${id}/persons/`
+}
+
+export const accountsPersonsRetrieve = async (
+ projectId: string,
+ id: string,
+ params?: AccountsPersonsRetrieveParams,
+ options?: RequestInit
+): Promise<AccountPersonsPageApi> => {
+ return apiMutator<AccountPersonsPageApi>(getAccountsPersonsRetrieveUrl(projectId, id, params), {
+ ...options,
+ method: 'GET',
+ })
+}
+
+export const getAccountsPersonsQueryCreateUrl = (projectId: string, id: string) => {
+ return `/api/projects/${projectId}/accounts/${id}/persons/`
+}
+
+/**
+ * Run an account-user table query. Requires query, account, and person read scopes.
+ */
+export const accountsPersonsQueryCreate = async (
+ projectId: string,
+ id: string,
+ accountPersonsQueryRequestApi: AccountPersonsQueryRequestApi,
+ options?: RequestInit
+): Promise<ActorsQueryResponseApi> => {
+ return apiMutator<ActorsQueryResponseApi>(getAccountsPersonsQueryCreateUrl(projectId, id), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(accountPersonsQueryRequestApi),
+ })
+}
+
export const getAccountsRetrieveUrl = (projectId: string, id: string) => {
return `/api/projects/${projectId}/accounts/${id}/`
}
diff --git a/products/customer_analytics/frontend/generated/api.zod.ts b/products/customer_analytics/frontend/generated/api.zod.ts
index 090976d63852..9c712b5a554e 100644
--- a/products/customer_analytics/frontend/generated/api.zod.ts
+++ b/products/customer_analytics/frontend/generated/api.zod.ts
@@ -432,6 +432,13 @@ export const AccountsRelationshipsCreateBody = /* @__PURE__ */ zod
})
.describe('Input for assigning a user to an account relationship.')
+/**
+ * Run an account-user table query. Requires query, account, and person read scopes.
+ */
+export const AccountsPersonsQueryCreateBody = /* @__PURE__ */ zod
+ .record(zod.string(), zod.unknown())
+ .describe('Deep\/recursive schema (opaque in Zod — use TypeScript types for full shape)')
+
export const accountsUpdateBodyNameMax = 400
export const accountsUpdateBodyExternalIdMax = 400
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 3488427ab783..0f3a66401d14 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -2486,260 +2486,68 @@ export namespace Schemas {
readonly last_modified_by: UserBasic;
}
- export interface AccountPresenceViewer {
- /** PostHog user ID of the teammate viewing this account. */
- readonly user_id: number;
- /** Display name of the teammate viewing this account. */
- readonly display_name: string;
- }
-
- export interface AccountPresence {
- /** Customer analytics account ID. */
- readonly account_id: string;
- /** People viewing this account. */
- readonly viewers: readonly AccountPresenceViewer[];
- }
-
- export interface AccountPresenceListRequest {
- /**
- * Up to 100 account IDs to read presence for.
- * @maxItems 100
- */
- account_ids: string[];
- }
-
- /**
- * * `custom_property` - Custom property
- * * `relationship` - Relationship
- * * `account_field` - Account field
- */
- export type AccountPropertyPinKindEnum = typeof AccountPropertyPinKindEnum[keyof typeof AccountPropertyPinKindEnum];
-
-
- export const AccountPropertyPinKindEnum = {
- CustomProperty: 'custom_property',
- Relationship: 'relationship',
- AccountField: 'account_field',
- } as const;
-
/**
- * A team-defined account relationship type (CSM, Onboarding manager, ...).
+ * Selected visible person properties.
*/
- export interface AccountRelationshipDefinition {
- /** Relationship definition UUID. */
- readonly id: string;
- /**
- * Human-readable name of the relationship. Unique within the team.
- * @maxLength 400
- */
- name: string;
- /**
- * What this relationship means, e.g. 'The customer success manager responsible for this account'.
- * @nullable
- */
- description?: string | null;
- /** Whether only one user can hold this relationship per account at a time, e.g. a single CSM per account. */
- is_single_holder?: boolean;
- /** Whether customer analytics can take control of this relationship per account. Rows under a controlled relationship can't be deleted. On an account where control has started, only a person can change the relationship and an empty relationship is a deliberate decision. Set by project operators, not through this API. */
- readonly is_controlled: boolean;
- }
+ export type AccountPersonProperties = {[key: string]: unknown};
- /**
- * * `human` - Human
- * * `workflow` - Workflow
- * * `ai` - AI
- * * `salesforce_claim` - Salesforce claim
- * * `migration` - Migration
- */
- export type AccountRelationshipSourceEnum = typeof AccountRelationshipSourceEnum[keyof typeof AccountRelationshipSourceEnum];
-
-
- export const AccountRelationshipSourceEnum = {
- Human: 'human',
- Workflow: 'workflow',
- Ai: 'ai',
- SalesforceClaim: 'salesforce_claim',
- Migration: 'migration',
- } as const;
-
- /**
- * One assignment of a user to an account relationship, with its effective range.
- */
- export interface AccountRelationship {
- /** Unique id of this assignment row. */
- readonly id: string;
- /** The relationship type this assignment belongs to. */
- readonly definition: AccountRelationshipDefinition;
- /** The assigned user; null when their account was deleted. */
- readonly user: AccountAssignment | null;
- /** When this assignment became effective. */
- readonly started_at: string;
- /**
- * When this assignment ended; null while it is active.
- * @nullable
- */
- readonly ended_at: string | null;
- /** Which kind of writer made this assignment; null on rows older than provenance tracking.
- *
- * * `human` - Human
- * * `workflow` - Workflow
- * * `ai` - AI
- * * `salesforce_claim` - Salesforce claim
- * * `migration` - Migration */
- readonly source: AccountRelationshipSourceEnum | null;
- }
-
- /**
- * Input for assigning a user to an account relationship.
- */
- export interface AccountRelationshipWrite {
- /** Id of the relationship definition to assign. */
- definition: string;
- /** PostHog user id of the assignee. Must be a member of the account's organization. */
- user: number;
- }
-
- export interface AccountSupportTicketMessage {
- /** UUID of the support ticket message. */
- readonly id: string;
- /** Plain-text message content. */
- readonly content: string;
- /** Display name of the message author. */
- readonly author_name: string;
- /** Whether PostHog received or sent the message.
- *
- * * `inbound` - Inbound
- * * `outbound` - Outbound */
- readonly direction: EmailThreadMessageDirectionEnum;
- /** Whether the message is an internal note hidden from the customer. */
- readonly is_private: boolean;
- /** When the message was created. */
- readonly created_at: string;
- }
-
- /**
- * * `account_field` - account_field
- * * `custom_property` - custom_property
- */
- export type AccountTrackRuleFieldKindEnum = typeof AccountTrackRuleFieldKindEnum[keyof typeof AccountTrackRuleFieldKindEnum];
-
-
- export const AccountTrackRuleFieldKindEnum = {
- AccountField: 'account_field',
- CustomProperty: 'custom_property',
- } as const;
-
- /**
- * * `name` - name
- * * `external_id` - external_id
- * * `created_at` - created_at
- * * `updated_at` - updated_at
- * * `churned_at` - churned_at
- * * `ignored_at` - ignored_at
- * * `stripe_customer_id` - stripe_customer_id
- * * `hubspot_deal_id` - hubspot_deal_id
- * * `billing_id` - billing_id
- * * `sfdc_id` - sfdc_id
- * * `zendesk_id` - zendesk_id
- */
- export type AccountTrackRuleFieldFieldEnum = typeof AccountTrackRuleFieldFieldEnum[keyof typeof AccountTrackRuleFieldFieldEnum];
-
-
- export const AccountTrackRuleFieldFieldEnum = {
- Name: 'name',
- ExternalId: 'external_id',
- CreatedAt: 'created_at',
- UpdatedAt: 'updated_at',
- ChurnedAt: 'churned_at',
- IgnoredAt: 'ignored_at',
- StripeCustomerId: 'stripe_customer_id',
- HubspotDealId: 'hubspot_deal_id',
- BillingId: 'billing_id',
- SfdcId: 'sfdc_id',
- ZendeskId: 'zendesk_id',
- } as const;
-
- export interface AccountTrackRuleField {
- kind: AccountTrackRuleFieldKindEnum;
- field?: AccountTrackRuleFieldFieldEnum | null;
- /** @nullable */
- definition_id?: string | null;
- }
-
- export interface AccountTrackRuleCondition {
- field: AccountTrackRuleField;
- operator: string;
- values?: unknown[];
- }
-
- export interface AccountTrackRuleGroup {
- conditions: AccountTrackRuleCondition[];
+ export interface AccountPerson {
+ /** Current person ID. */
+ id: string;
+ /** Display name from visible person properties, or the person ID. */
+ display_name: string;
+ /** Current membership distinct IDs for person navigation, up to 101. */
+ distinct_ids: string[];
+ /** Selected visible person properties. */
+ properties: AccountPersonProperties;
+ /** Earliest account activity across current distinct IDs, in UTC. */
+ account_first_seen: string;
+ /** Latest account activity across current distinct IDs, in UTC. */
+ account_last_seen: string;
}
- export type AccountTrackRuleSampleRuleValues = { [key: string]: unknown };
-
- export interface AccountTrackRuleSample {
- readonly id: string;
- readonly name: string;
- /** @nullable */
- readonly external_id: string | null;
- readonly rule_values: AccountTrackRuleSampleRuleValues;
+ export interface PersonPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ /** Person properties */
+ type?: 'person';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
}
- export interface AccountTrackRulePreview {
- config_version: number;
- eligible_active: number;
- skipped_churned: number;
- tracked: number;
- ignored: number;
- newly_ignored: number;
- restored: number;
- readonly tracked_samples: readonly AccountTrackRuleSample[];
- readonly ignored_samples: readonly AccountTrackRuleSample[];
- validation_errors?: string[];
+ export interface PersonMetadataPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ /** Top-level columns on the persons table (e.g. created_at), not properties JSON */
+ type?: 'person_metadata';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
}
- export interface AccountTrackRuleRunRequest {
- idempotency_key: string;
- confirmed: boolean;
+ export interface CohortPropertyFilter {
+ /** Set by the feature flag API when the cohort is deleted or does not exist. */
+ cohort_deleted?: boolean | null;
+ /** Set by the feature flag API when the cohort does not exist, so it cannot be restored. */
+ cohort_missing?: boolean | null;
+ cohort_name?: string | null;
+ key?: 'id';
+ label?: string | null;
+ operator?: PropertyOperator | null;
+ type?: 'cohort';
+ value: number;
}
- export interface AccountTrackRuleRunView {
- readonly id: string;
- /** @minimum 0 */
- readonly config_version: number;
- readonly trigger: string;
- readonly status: string;
- /** @minimum 0 */
- readonly eligible_active: number;
- /** @minimum 0 */
- readonly skipped_churned: number;
- /** @minimum 0 */
- readonly tracked: number;
- /** @minimum 0 */
- readonly ignored: number;
- /** @minimum 0 */
- readonly newly_ignored: number;
- /** @minimum 0 */
- readonly restored: number;
- /** @nullable */
- readonly started_at: string | null;
- /** @nullable */
- readonly finished_at: string | null;
- /** @nullable */
- readonly error: string | null;
- /** @nullable */
- readonly created_by: number | null;
- readonly created_at: string;
+ export interface HogQLPropertyFilter {
+ key: string;
+ label?: string | null;
+ type?: 'hogql';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
}
- export interface AccountTrackRulesConfig {
- schema_version: number;
- /** @minimum 0 */
- version: number;
- enabled: boolean;
- groups: AccountTrackRuleGroup[];
- }
+ export const EmptyPropertyFilterValue = {
+ type: 'empty',
+ } as const;
+ export type EmptyPropertyFilter = typeof EmptyPropertyFilterValue;
export type BounceRatePageViewMode = typeof BounceRatePageViewMode[keyof typeof BounceRatePageViewMode];
@@ -3017,6 +2825,244 @@ export namespace Schemas {
webAnalyticsFirstPageviewFilters?: boolean | null;
}
+ export interface EventPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator?: PropertyOperator | null;
+ /** Event properties */
+ type?: 'event';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export type Key10 = typeof Key10[keyof typeof Key10];
+
+
+ export const Key10 = {
+ TagName: 'tag_name',
+ Text: 'text',
+ Href: 'href',
+ Selector: 'selector',
+ } as const;
+
+ export interface ElementPropertyFilter {
+ key: Key10;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'element';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface EventMetadataPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'event_metadata';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface SessionPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'session';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export type DurationType = typeof DurationType[keyof typeof DurationType];
+
+
+ export const DurationType = {
+ Duration: 'duration',
+ ActiveSeconds: 'active_seconds',
+ InactiveSeconds: 'inactive_seconds',
+ } as const;
+
+ export interface RecordingPropertyFilter {
+ key: DurationType | string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'recording';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface LogEntryPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'log_entry';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export type GroupPropertyFilterGroupKeyNames = {[key: string]: string} | null;
+
+ export interface GroupPropertyFilter {
+ group_key_names?: GroupPropertyFilterGroupKeyNames;
+ group_type_index?: number | null;
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'group';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface FeaturePropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ /** Event property with "$feature/" prepended */
+ type?: 'feature';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface FlagPropertyFilter {
+ /** The key should be the flag ID */
+ key: string;
+ label?: string | null;
+ /** Only flag_evaluates_to operator is allowed for flag dependencies */
+ operator?: 'flag_evaluates_to';
+ /** Feature flag dependency */
+ type?: 'flag';
+ /** The value can be true, false, or a variant name */
+ value: boolean | string;
+ }
+
+ export interface DataWarehousePropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'data_warehouse';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface DataWarehousePersonPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'data_warehouse_person_property';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface ErrorTrackingIssueFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'error_tracking_issue';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export type LogPropertyFilterType = typeof LogPropertyFilterType[keyof typeof LogPropertyFilterType];
+
+
+ export const LogPropertyFilterType = {
+ Log: 'log',
+ LogAttribute: 'log_attribute',
+ LogResourceAttribute: 'log_resource_attribute',
+ } as const;
+
+ export interface LogPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type: LogPropertyFilterType;
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface MetricPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'metric_attribute';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export type SpanPropertyFilterType = typeof SpanPropertyFilterType[keyof typeof SpanPropertyFilterType];
+
+
+ export const SpanPropertyFilterType = {
+ Span: 'span',
+ SpanAttribute: 'span_attribute',
+ SpanResourceAttribute: 'span_resource_attribute',
+ } as const;
+
+ export interface SpanPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type: SpanPropertyFilterType;
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface RevenueAnalyticsPropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'revenue_analytics';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export interface WorkflowVariablePropertyFilter {
+ key: string;
+ label?: string | null;
+ operator: PropertyOperator;
+ type?: 'workflow_variable';
+ value?: (string | number | boolean)[] | string | number | boolean | null;
+ }
+
+ export type BehavioralEventSource = typeof BehavioralEventSource[keyof typeof BehavioralEventSource];
+
+
+ export const BehavioralEventSource = {
+ Events: 'events',
+ Actions: 'actions',
+ } as const;
+
+ export type TimeUnitType = typeof TimeUnitType[keyof typeof TimeUnitType];
+
+
+ export const TimeUnitType = {
+ Day: 'day',
+ Week: 'week',
+ Month: 'month',
+ Year: 'year',
+ } as const;
+
+ export type InlineBehavioralType = typeof InlineBehavioralType[keyof typeof InlineBehavioralType];
+
+
+ export const InlineBehavioralType = {
+ PerformedEvent: 'performed_event',
+ PerformedEventMultiple: 'performed_event_multiple',
+ } as const;
+
+ export interface BehavioralPropertyFilter {
+ /** Extra property filters the matching events must satisfy. Deliberately excludes nested behavioral/cohort filters and groups */
+ event_filters?: (EventPropertyFilter | PersonPropertyFilter | ElementPropertyFilter | FeaturePropertyFilter | HogQLPropertyFilter)[] | null;
+ event_type: BehavioralEventSource;
+ /** Absolute or relative (e.g. -30d) lower date bound — alternative to time_value/time_interval */
+ explicit_datetime?: string | null;
+ explicit_datetime_to?: string | null;
+ /** Event name, or action id when event_type is 'actions' */
+ key: string;
+ label?: string | null;
+ /** Match persons who did NOT satisfy the criterion. Not the same as a low count — zero-occurrence persons never match count operators */
+ negation?: boolean | null;
+ /** Count comparison for performed_event_multiple, defaults to exact */
+ operator?: PropertyOperator | null;
+ /** Count threshold for performed_event_multiple */
+ operator_value?: number | null;
+ time_interval?: TimeUnitType | null;
+ /** Relative time window size, paired with time_interval */
+ time_value?: number | null;
+ /** Person performed (or didn't perform) an event in a time window. ClickHouse-only — not evaluable by flags or CDP */
+ type?: 'behavioral';
+ value: InlineBehavioralType;
+ }
+
+ export interface PropertyGroupFilterValue {
+ type: FilterLogicalOperator;
+ values: (PropertyGroupFilterValue | EventPropertyFilter | PersonPropertyFilter | PersonMetadataPropertyFilter | ElementPropertyFilter | EventMetadataPropertyFilter | SessionPropertyFilter | CohortPropertyFilter | RecordingPropertyFilter | LogEntryPropertyFilter | GroupPropertyFilter | FeaturePropertyFilter | FlagPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter | DataWarehousePropertyFilter | DataWarehousePersonPropertyFilter | ErrorTrackingIssueFilter | LogPropertyFilter | MetricPropertyFilter | SpanPropertyFilter | RevenueAnalyticsPropertyFilter | AccountCustomPropertyFilter | WorkflowVariablePropertyFilter | BehavioralPropertyFilter)[];
+ }
+
export interface ClickhouseQueryProgress {
active_cpu_time: number;
bytes_read: number;
@@ -3214,6 +3260,491 @@ export namespace Schemas {
version?: number | null;
}
+ export interface AccountPersonsActorsQuery {
+ /** Exclude persons matching the team's "internal and test account" filters. Only person-scoped filters (person properties, cohorts) are applied. Event-scoped test account filters have no meaning in a persons query and are ignored. */
+ filterTestAccounts?: boolean | null;
+ /** Currently only person filters supported. No filters for querying groups. See `filter_conditions()` in actor_strategies.py. */
+ fixedProperties?: (PersonPropertyFilter | PersonMetadataPropertyFilter | CohortPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter)[] | null;
+ kind?: 'ActorsQuery';
+ limit?: number | null;
+ /** Modifiers used when performing the query */
+ modifiers?: HogQLQueryModifiers | null;
+ offset?: number | null;
+ orderBy?: string[] | null;
+ /** Currently only person filters supported. No filters for querying groups. See `filter_conditions()` in actor_strategies.py. */
+ properties?: (PersonPropertyFilter | PersonMetadataPropertyFilter | CohortPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter)[] | PropertyGroupFilterValue | null;
+ response?: ActorsQueryResponse | null;
+ search?: string | null;
+ select?: string[] | null;
+ /** Account membership source for the table. */
+ source: AccountUsersQuery;
+ tags?: QueryLogTags | null;
+ /** version of the node, used for schema migrations */
+ version?: number | null;
+ }
+
+ export interface AccountPersonsPage {
+ /** Matching current persons for this account. */
+ results: AccountPerson[];
+ /** Selected visible property keys, in request order. */
+ columns: string[];
+ /** Maximum persons per page. */
+ limit: number;
+ /** Number of matching persons skipped. */
+ offset: number;
+ /** Whether another page exists. */
+ has_more: boolean;
+ /**
+ * Offset of the next page, or null.
+ * @nullable
+ */
+ next_offset: number | null;
+ }
+
+ /**
+ * Read cached results or calculate synchronously.
+ */
+ export type AccountPersonsQueryRequestRefresh = typeof AccountPersonsQueryRequestRefresh[keyof typeof AccountPersonsQueryRequestRefresh] | null;
+
+
+ export const AccountPersonsQueryRequestRefresh = {
+ Blocking: 'blocking',
+ ForceBlocking: 'force_blocking',
+ } as const;
+
+ export type AccountPersonsQueryRequestVariablesOverride = {[key: string]: { [key: string]: unknown }} | null;
+
+ export type BreakdownType = typeof BreakdownType[keyof typeof BreakdownType];
+
+
+ export const BreakdownType = {
+ Cohort: 'cohort',
+ Person: 'person',
+ Event: 'event',
+ EventMetadata: 'event_metadata',
+ Element: 'element',
+ Group: 'group',
+ Session: 'session',
+ Hogql: 'hogql',
+ DataWarehouse: 'data_warehouse',
+ DataWarehousePersonProperty: 'data_warehouse_person_property',
+ RevenueAnalytics: 'revenue_analytics',
+ } as const;
+
+ export type MultipleBreakdownType = typeof MultipleBreakdownType[keyof typeof MultipleBreakdownType];
+
+
+ export const MultipleBreakdownType = {
+ Person: 'person',
+ Event: 'event',
+ EventMetadata: 'event_metadata',
+ Element: 'element',
+ Group: 'group',
+ Session: 'session',
+ Hogql: 'hogql',
+ Cohort: 'cohort',
+ RevenueAnalytics: 'revenue_analytics',
+ DataWarehouse: 'data_warehouse',
+ DataWarehousePersonProperty: 'data_warehouse_person_property',
+ } as const;
+
+ export interface Breakdown {
+ group_type_index?: number | null;
+ histogram_bin_count?: number | null;
+ normalize_url?: boolean | null;
+ property: string | number;
+ type?: MultipleBreakdownType | null;
+ }
+
+ export interface BreakdownFilter {
+ breakdown?: string | (string | number)[] | number | null;
+ breakdown_group_type_index?: number | null;
+ breakdown_hide_other_aggregation?: boolean | null;
+ breakdown_histogram_bin_count?: number | null;
+ breakdown_limit?: number | null;
+ breakdown_normalize_url?: boolean | null;
+ breakdown_path_cleaning?: boolean | null;
+ breakdown_type?: BreakdownType | null;
+ breakdowns?: Breakdown[] | null;
+ }
+
+ export interface CompareFilter {
+ /** Whether to compare the current date range to a previous date range. */
+ compare?: boolean | null;
+ /** The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. */
+ compare_to?: string | null;
+ }
+
+ export type IntervalType = typeof IntervalType[keyof typeof IntervalType];
+
+
+ export const IntervalType = {
+ Second: 'second',
+ Minute: 'minute',
+ Hour: 'hour',
+ Day: 'day',
+ Week: 'week',
+ Month: 'month',
+ Quarter: 'quarter',
+ Year: 'year',
+ } as const;
+
+ export type MetricsFilterOp = typeof MetricsFilterOp[keyof typeof MetricsFilterOp];
+
+
+ export const MetricsFilterOp = {
+ Eq: 'eq',
+ Neq: 'neq',
+ Regex: 'regex',
+ NotRegex: 'not_regex',
+ } as const;
+
+ export type MetricsAttributeScope = typeof MetricsAttributeScope[keyof typeof MetricsAttributeScope];
+
+
+ export const MetricsAttributeScope = {
+ Resource: 'resource',
+ Attribute: 'attribute',
+ Auto: 'auto',
+ } as const;
+
+ export interface MetricsQueryFilter {
+ key: string;
+ op: MetricsFilterOp;
+ scope?: MetricsAttributeScope | null;
+ value: string;
+ }
+
+ export interface MetricsDashboardVariableSelection {
+ all?: boolean | null;
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[];
+ }
+
+ export type MetricsDashboardVariableSource = typeof MetricsDashboardVariableSource[keyof typeof MetricsDashboardVariableSource];
+
+
+ export const MetricsDashboardVariableSource = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
+ } as const;
+
+ export interface MetricsDashboardVariable {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null;
+ current?: MetricsDashboardVariableSelection | null;
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null;
+ includeAll?: boolean | null;
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null;
+ multi?: boolean | null;
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string;
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null;
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null;
+ source: MetricsDashboardVariableSource;
+ }
+
+ export interface DashboardFilter {
+ breakdown_filter?: BreakdownFilter | null;
+ /** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
+ compareFilter?: CompareFilter | null;
+ date_from?: string | null;
+ date_to?: string | null;
+ explicitDate?: boolean | null;
+ /** Tri-state test-account override. Null/absent = inherit; true = force on; false = force off. */
+ filterTestAccounts?: boolean | null;
+ /** Time granularity forced onto every insight that supports one. Absent/null = inherit. */
+ interval?: IntervalType | null;
+ metricFilters?: MetricsQueryFilter[] | null;
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariable[] | null;
+ properties?: (EventPropertyFilter | PersonPropertyFilter | PersonMetadataPropertyFilter | ElementPropertyFilter | EventMetadataPropertyFilter | SessionPropertyFilter | CohortPropertyFilter | RecordingPropertyFilter | LogEntryPropertyFilter | GroupPropertyFilter | FeaturePropertyFilter | FlagPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter | DataWarehousePropertyFilter | DataWarehousePersonPropertyFilter | ErrorTrackingIssueFilter | LogPropertyFilter | MetricPropertyFilter | SpanPropertyFilter | RevenueAnalyticsPropertyFilter | AccountCustomPropertyFilter | WorkflowVariablePropertyFilter | BehavioralPropertyFilter)[] | null;
+ }
+
+ export type LimitContext = typeof LimitContext[keyof typeof LimitContext];
+
+
+ export const LimitContext = {
+ PosthogAi: 'posthog_ai',
+ } as const;
+
+ export interface AccountPersonsQueryRequest {
+ async?: false | null;
+ /** Client provided query ID. Can be used to retrieve the status or cancel the query. */
+ client_query_id?: string | null;
+ filters_override?: DashboardFilter | null;
+ /** Limit context for the query. Only 'posthog_ai' is allowed as a client-provided value. */
+ limit_context?: LimitContext | null;
+ /** Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name. */
+ name?: string | null;
+ /** Account-user table query to run. */
+ query: AccountPersonsActorsQuery;
+ /** Read cached results or calculate synchronously. */
+ refresh?: AccountPersonsQueryRequestRefresh;
+ variables_override?: AccountPersonsQueryRequestVariablesOverride;
+ }
+
+ export interface AccountPresenceViewer {
+ /** PostHog user ID of the teammate viewing this account. */
+ readonly user_id: number;
+ /** Display name of the teammate viewing this account. */
+ readonly display_name: string;
+ }
+
+ export interface AccountPresence {
+ /** Customer analytics account ID. */
+ readonly account_id: string;
+ /** People viewing this account. */
+ readonly viewers: readonly AccountPresenceViewer[];
+ }
+
+ export interface AccountPresenceListRequest {
+ /**
+ * Up to 100 account IDs to read presence for.
+ * @maxItems 100
+ */
+ account_ids: string[];
+ }
+
+ /**
+ * * `custom_property` - Custom property
+ * * `relationship` - Relationship
+ * * `account_field` - Account field
+ */
+ export type AccountPropertyPinKindEnum = typeof AccountPropertyPinKindEnum[keyof typeof AccountPropertyPinKindEnum];
+
+
+ export const AccountPropertyPinKindEnum = {
+ CustomProperty: 'custom_property',
+ Relationship: 'relationship',
+ AccountField: 'account_field',
+ } as const;
+
+ /**
+ * A team-defined account relationship type (CSM, Onboarding manager, ...).
+ */
+ export interface AccountRelationshipDefinition {
+ /** Relationship definition UUID. */
+ readonly id: string;
+ /**
+ * Human-readable name of the relationship. Unique within the team.
+ * @maxLength 400
+ */
+ name: string;
+ /**
+ * What this relationship means, e.g. 'The customer success manager responsible for this account'.
+ * @nullable
+ */
+ description?: string | null;
+ /** Whether only one user can hold this relationship per account at a time, e.g. a single CSM per account. */
+ is_single_holder?: boolean;
+ /** Whether customer analytics can take control of this relationship per account. Rows under a controlled relationship can't be deleted. On an account where control has started, only a person can change the relationship and an empty relationship is a deliberate decision. Set by project operators, not through this API. */
+ readonly is_controlled: boolean;
+ }
+
+ /**
+ * * `human` - Human
+ * * `workflow` - Workflow
+ * * `ai` - AI
+ * * `salesforce_claim` - Salesforce claim
+ * * `migration` - Migration
+ */
+ export type AccountRelationshipSourceEnum = typeof AccountRelationshipSourceEnum[keyof typeof AccountRelationshipSourceEnum];
+
+
+ export const AccountRelationshipSourceEnum = {
+ Human: 'human',
+ Workflow: 'workflow',
+ Ai: 'ai',
+ SalesforceClaim: 'salesforce_claim',
+ Migration: 'migration',
+ } as const;
+
+ /**
+ * One assignment of a user to an account relationship, with its effective range.
+ */
+ export interface AccountRelationship {
+ /** Unique id of this assignment row. */
+ readonly id: string;
+ /** The relationship type this assignment belongs to. */
+ readonly definition: AccountRelationshipDefinition;
+ /** The assigned user; null when their account was deleted. */
+ readonly user: AccountAssignment | null;
+ /** When this assignment became effective. */
+ readonly started_at: string;
+ /**
+ * When this assignment ended; null while it is active.
+ * @nullable
+ */
+ readonly ended_at: string | null;
+ /** Which kind of writer made this assignment; null on rows older than provenance tracking.
+ *
+ * * `human` - Human
+ * * `workflow` - Workflow
+ * * `ai` - AI
+ * * `salesforce_claim` - Salesforce claim
+ * * `migration` - Migration */
+ readonly source: AccountRelationshipSourceEnum | null;
+ }
+
+ /**
+ * Input for assigning a user to an account relationship.
+ */
+ export interface AccountRelationshipWrite {
+ /** Id of the relationship definition to assign. */
+ definition: string;
+ /** PostHog user id of the assignee. Must be a member of the account's organization. */
+ user: number;
+ }
+
+ export interface AccountSupportTicketMessage {
+ /** UUID of the support ticket message. */
+ readonly id: string;
+ /** Plain-text message content. */
+ readonly content: string;
+ /** Display name of the message author. */
+ readonly author_name: string;
+ /** Whether PostHog received or sent the message.
+ *
+ * * `inbound` - Inbound
+ * * `outbound` - Outbound */
+ readonly direction: EmailThreadMessageDirectionEnum;
+ /** Whether the message is an internal note hidden from the customer. */
+ readonly is_private: boolean;
+ /** When the message was created. */
+ readonly created_at: string;
+ }
+
+ /**
+ * * `account_field` - account_field
+ * * `custom_property` - custom_property
+ */
+ export type AccountTrackRuleFieldKindEnum = typeof AccountTrackRuleFieldKindEnum[keyof typeof AccountTrackRuleFieldKindEnum];
+
+
+ export const AccountTrackRuleFieldKindEnum = {
+ AccountField: 'account_field',
+ CustomProperty: 'custom_property',
+ } as const;
+
+ /**
+ * * `name` - name
+ * * `external_id` - external_id
+ * * `created_at` - created_at
+ * * `updated_at` - updated_at
+ * * `churned_at` - churned_at
+ * * `ignored_at` - ignored_at
+ * * `stripe_customer_id` - stripe_customer_id
+ * * `hubspot_deal_id` - hubspot_deal_id
+ * * `billing_id` - billing_id
+ * * `sfdc_id` - sfdc_id
+ * * `zendesk_id` - zendesk_id
+ */
+ export type AccountTrackRuleFieldFieldEnum = typeof AccountTrackRuleFieldFieldEnum[keyof typeof AccountTrackRuleFieldFieldEnum];
+
+
+ export const AccountTrackRuleFieldFieldEnum = {
+ Name: 'name',
+ ExternalId: 'external_id',
+ CreatedAt: 'created_at',
+ UpdatedAt: 'updated_at',
+ ChurnedAt: 'churned_at',
+ IgnoredAt: 'ignored_at',
+ StripeCustomerId: 'stripe_customer_id',
+ HubspotDealId: 'hubspot_deal_id',
+ BillingId: 'billing_id',
+ SfdcId: 'sfdc_id',
+ ZendeskId: 'zendesk_id',
+ } as const;
+
+ export interface AccountTrackRuleField {
+ kind: AccountTrackRuleFieldKindEnum;
+ field?: AccountTrackRuleFieldFieldEnum | null;
+ /** @nullable */
+ definition_id?: string | null;
+ }
+
+ export interface AccountTrackRuleCondition {
+ field: AccountTrackRuleField;
+ operator: string;
+ values?: unknown[];
+ }
+
+ export interface AccountTrackRuleGroup {
+ conditions: AccountTrackRuleCondition[];
+ }
+
+ export type AccountTrackRuleSampleRuleValues = { [key: string]: unknown };
+
+ export interface AccountTrackRuleSample {
+ readonly id: string;
+ readonly name: string;
+ /** @nullable */
+ readonly external_id: string | null;
+ readonly rule_values: AccountTrackRuleSampleRuleValues;
+ }
+
+ export interface AccountTrackRulePreview {
+ config_version: number;
+ eligible_active: number;
+ skipped_churned: number;
+ tracked: number;
+ ignored: number;
+ newly_ignored: number;
+ restored: number;
+ readonly tracked_samples: readonly AccountTrackRuleSample[];
+ readonly ignored_samples: readonly AccountTrackRuleSample[];
+ validation_errors?: string[];
+ }
+
+ export interface AccountTrackRuleRunRequest {
+ idempotency_key: string;
+ confirmed: boolean;
+ }
+
+ export interface AccountTrackRuleRunView {
+ readonly id: string;
+ /** @minimum 0 */
+ readonly config_version: number;
+ readonly trigger: string;
+ readonly status: string;
+ /** @minimum 0 */
+ readonly eligible_active: number;
+ /** @minimum 0 */
+ readonly skipped_churned: number;
+ /** @minimum 0 */
+ readonly tracked: number;
+ /** @minimum 0 */
+ readonly ignored: number;
+ /** @minimum 0 */
+ readonly newly_ignored: number;
+ /** @minimum 0 */
+ readonly restored: number;
+ /** @nullable */
+ readonly started_at: string | null;
+ /** @nullable */
+ readonly finished_at: string | null;
+ /** @nullable */
+ readonly error: string | null;
+ /** @nullable */
+ readonly created_by: number | null;
+ readonly created_at: string;
+ }
+
+ export interface AccountTrackRulesConfig {
+ schema_version: number;
+ /** @minimum 0 */
+ version: number;
+ enabled: boolean;
+ groups: AccountTrackRuleGroup[];
+ }
+
/**
* * `private` - Personal
* * `team` - Team
@@ -3773,442 +4304,6 @@ export namespace Schemas {
export type AccountsTableQueryRequestVariablesOverride = {[key: string]: { [key: string]: unknown }} | null;
- export type BreakdownType = typeof BreakdownType[keyof typeof BreakdownType];
-
-
- export const BreakdownType = {
- Cohort: 'cohort',
- Person: 'person',
- Event: 'event',
- EventMetadata: 'event_metadata',
- Element: 'element',
- Group: 'group',
- Session: 'session',
- Hogql: 'hogql',
- DataWarehouse: 'data_warehouse',
- DataWarehousePersonProperty: 'data_warehouse_person_property',
- RevenueAnalytics: 'revenue_analytics',
- } as const;
-
- export type MultipleBreakdownType = typeof MultipleBreakdownType[keyof typeof MultipleBreakdownType];
-
-
- export const MultipleBreakdownType = {
- Person: 'person',
- Event: 'event',
- EventMetadata: 'event_metadata',
- Element: 'element',
- Group: 'group',
- Session: 'session',
- Hogql: 'hogql',
- Cohort: 'cohort',
- RevenueAnalytics: 'revenue_analytics',
- DataWarehouse: 'data_warehouse',
- DataWarehousePersonProperty: 'data_warehouse_person_property',
- } as const;
-
- export interface Breakdown {
- group_type_index?: number | null;
- histogram_bin_count?: number | null;
- normalize_url?: boolean | null;
- property: string | number;
- type?: MultipleBreakdownType | null;
- }
-
- export interface BreakdownFilter {
- breakdown?: string | (string | number)[] | number | null;
- breakdown_group_type_index?: number | null;
- breakdown_hide_other_aggregation?: boolean | null;
- breakdown_histogram_bin_count?: number | null;
- breakdown_limit?: number | null;
- breakdown_normalize_url?: boolean | null;
- breakdown_path_cleaning?: boolean | null;
- breakdown_type?: BreakdownType | null;
- breakdowns?: Breakdown[] | null;
- }
-
- export interface CompareFilter {
- /** Whether to compare the current date range to a previous date range. */
- compare?: boolean | null;
- /** The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. */
- compare_to?: string | null;
- }
-
- export type IntervalType = typeof IntervalType[keyof typeof IntervalType];
-
-
- export const IntervalType = {
- Second: 'second',
- Minute: 'minute',
- Hour: 'hour',
- Day: 'day',
- Week: 'week',
- Month: 'month',
- Quarter: 'quarter',
- Year: 'year',
- } as const;
-
- export type MetricsFilterOp = typeof MetricsFilterOp[keyof typeof MetricsFilterOp];
-
-
- export const MetricsFilterOp = {
- Eq: 'eq',
- Neq: 'neq',
- Regex: 'regex',
- NotRegex: 'not_regex',
- } as const;
-
- export type MetricsAttributeScope = typeof MetricsAttributeScope[keyof typeof MetricsAttributeScope];
-
-
- export const MetricsAttributeScope = {
- Resource: 'resource',
- Attribute: 'attribute',
- Auto: 'auto',
- } as const;
-
- export interface MetricsQueryFilter {
- key: string;
- op: MetricsFilterOp;
- scope?: MetricsAttributeScope | null;
- value: string;
- }
-
- export interface MetricsDashboardVariableSelection {
- all?: boolean | null;
- /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
- values: string[];
- }
-
- export type MetricsDashboardVariableSource = typeof MetricsDashboardVariableSource[keyof typeof MetricsDashboardVariableSource];
-
-
- export const MetricsDashboardVariableSource = {
- Custom: 'custom',
- Promql: 'promql',
- Sql: 'sql',
- Textbox: 'textbox',
- } as const;
-
- export interface MetricsDashboardVariable {
- /** The text that All puts in a PromQL query. `.*` when it is empty. */
- allValue?: string | null;
- current?: MetricsDashboardVariableSelection | null;
- /** The options when `source` is `custom`. */
- customValues?: string[] | null;
- includeAll?: boolean | null;
- /** Shown in the dashboard filter bar. The name is shown when it is empty. */
- label?: string | null;
- multi?: boolean | null;
- /** Letters, digits and underscores. Tiles refer to it as `$name`. */
- name: string;
- /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
- query?: string | null;
- /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
- regex?: string | null;
- source: MetricsDashboardVariableSource;
- }
-
- export interface EventPropertyFilter {
- key: string;
- label?: string | null;
- operator?: PropertyOperator | null;
- /** Event properties */
- type?: 'event';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface PersonPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- /** Person properties */
- type?: 'person';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface PersonMetadataPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- /** Top-level columns on the persons table (e.g. created_at), not properties JSON */
- type?: 'person_metadata';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export type Key10 = typeof Key10[keyof typeof Key10];
-
-
- export const Key10 = {
- TagName: 'tag_name',
- Text: 'text',
- Href: 'href',
- Selector: 'selector',
- } as const;
-
- export interface ElementPropertyFilter {
- key: Key10;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'element';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface EventMetadataPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'event_metadata';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface SessionPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'session';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface CohortPropertyFilter {
- /** Set by the feature flag API when the cohort is deleted or does not exist. */
- cohort_deleted?: boolean | null;
- /** Set by the feature flag API when the cohort does not exist, so it cannot be restored. */
- cohort_missing?: boolean | null;
- cohort_name?: string | null;
- key?: 'id';
- label?: string | null;
- operator?: PropertyOperator | null;
- type?: 'cohort';
- value: number;
- }
-
- export type DurationType = typeof DurationType[keyof typeof DurationType];
-
-
- export const DurationType = {
- Duration: 'duration',
- ActiveSeconds: 'active_seconds',
- InactiveSeconds: 'inactive_seconds',
- } as const;
-
- export interface RecordingPropertyFilter {
- key: DurationType | string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'recording';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface LogEntryPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'log_entry';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export type GroupPropertyFilterGroupKeyNames = {[key: string]: string} | null;
-
- export interface GroupPropertyFilter {
- group_key_names?: GroupPropertyFilterGroupKeyNames;
- group_type_index?: number | null;
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'group';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface FeaturePropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- /** Event property with "$feature/" prepended */
- type?: 'feature';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface FlagPropertyFilter {
- /** The key should be the flag ID */
- key: string;
- label?: string | null;
- /** Only flag_evaluates_to operator is allowed for flag dependencies */
- operator?: 'flag_evaluates_to';
- /** Feature flag dependency */
- type?: 'flag';
- /** The value can be true, false, or a variant name */
- value: boolean | string;
- }
-
- export interface HogQLPropertyFilter {
- key: string;
- label?: string | null;
- type?: 'hogql';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export const EmptyPropertyFilterValue = {
- type: 'empty',
- } as const;
- export type EmptyPropertyFilter = typeof EmptyPropertyFilterValue;
-
- export interface DataWarehousePropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'data_warehouse';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface DataWarehousePersonPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'data_warehouse_person_property';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface ErrorTrackingIssueFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'error_tracking_issue';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export type LogPropertyFilterType = typeof LogPropertyFilterType[keyof typeof LogPropertyFilterType];
-
-
- export const LogPropertyFilterType = {
- Log: 'log',
- LogAttribute: 'log_attribute',
- LogResourceAttribute: 'log_resource_attribute',
- } as const;
-
- export interface LogPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type: LogPropertyFilterType;
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface MetricPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'metric_attribute';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export type SpanPropertyFilterType = typeof SpanPropertyFilterType[keyof typeof SpanPropertyFilterType];
-
-
- export const SpanPropertyFilterType = {
- Span: 'span',
- SpanAttribute: 'span_attribute',
- SpanResourceAttribute: 'span_resource_attribute',
- } as const;
-
- export interface SpanPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type: SpanPropertyFilterType;
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface RevenueAnalyticsPropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'revenue_analytics';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export interface WorkflowVariablePropertyFilter {
- key: string;
- label?: string | null;
- operator: PropertyOperator;
- type?: 'workflow_variable';
- value?: (string | number | boolean)[] | string | number | boolean | null;
- }
-
- export type BehavioralEventSource = typeof BehavioralEventSource[keyof typeof BehavioralEventSource];
-
-
- export const BehavioralEventSource = {
- Events: 'events',
- Actions: 'actions',
- } as const;
-
- export type TimeUnitType = typeof TimeUnitType[keyof typeof TimeUnitType];
-
-
- export const TimeUnitType = {
- Day: 'day',
- Week: 'week',
- Month: 'month',
- Year: 'year',
- } as const;
-
- export type InlineBehavioralType = typeof InlineBehavioralType[keyof typeof InlineBehavioralType];
-
-
- export const InlineBehavioralType = {
- PerformedEvent: 'performed_event',
- PerformedEventMultiple: 'performed_event_multiple',
- } as const;
-
- export interface BehavioralPropertyFilter {
- /** Extra property filters the matching events must satisfy. Deliberately excludes nested behavioral/cohort filters and groups */
- event_filters?: (EventPropertyFilter | PersonPropertyFilter | ElementPropertyFilter | FeaturePropertyFilter | HogQLPropertyFilter)[] | null;
- event_type: BehavioralEventSource;
- /** Absolute or relative (e.g. -30d) lower date bound — alternative to time_value/time_interval */
- explicit_datetime?: string | null;
- explicit_datetime_to?: string | null;
- /** Event name, or action id when event_type is 'actions' */
- key: string;
- label?: string | null;
- /** Match persons who did NOT satisfy the criterion. Not the same as a low count — zero-occurrence persons never match count operators */
- negation?: boolean | null;
- /** Count comparison for performed_event_multiple, defaults to exact */
- operator?: PropertyOperator | null;
- /** Count threshold for performed_event_multiple */
- operator_value?: number | null;
- time_interval?: TimeUnitType | null;
- /** Relative time window size, paired with time_interval */
- time_value?: number | null;
- /** Person performed (or didn't perform) an event in a time window. ClickHouse-only — not evaluable by flags or CDP */
- type?: 'behavioral';
- value: InlineBehavioralType;
- }
-
- export interface DashboardFilter {
- breakdown_filter?: BreakdownFilter | null;
- /** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
- compareFilter?: CompareFilter | null;
- date_from?: string | null;
- date_to?: string | null;
- explicitDate?: boolean | null;
- /** Tri-state test-account override. Null/absent = inherit; true = force on; false = force off. */
- filterTestAccounts?: boolean | null;
- /** Time granularity forced onto every insight that supports one. Absent/null = inherit. */
- interval?: IntervalType | null;
- metricFilters?: MetricsQueryFilter[] | null;
- /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
- metricVariables?: MetricsDashboardVariable[] | null;
- properties?: (EventPropertyFilter | PersonPropertyFilter | PersonMetadataPropertyFilter | ElementPropertyFilter | EventMetadataPropertyFilter | SessionPropertyFilter | CohortPropertyFilter | RecordingPropertyFilter | LogEntryPropertyFilter | GroupPropertyFilter | FeaturePropertyFilter | FlagPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter | DataWarehousePropertyFilter | DataWarehousePersonPropertyFilter | ErrorTrackingIssueFilter | LogPropertyFilter | MetricPropertyFilter | SpanPropertyFilter | RevenueAnalyticsPropertyFilter | AccountCustomPropertyFilter | WorkflowVariablePropertyFilter | BehavioralPropertyFilter)[] | null;
- }
-
- export type LimitContext = typeof LimitContext[keyof typeof LimitContext];
-
-
- export const LimitContext = {
- PosthogAi: 'posthog_ai',
- } as const;
-
export type RefreshType = typeof RefreshType[keyof typeof RefreshType];
@@ -5991,11 +6086,6 @@ export namespace Schemas {
version?: number | null;
}
- export interface PropertyGroupFilterValue {
- type: FilterLogicalOperator;
- values: (PropertyGroupFilterValue | EventPropertyFilter | PersonPropertyFilter | PersonMetadataPropertyFilter | ElementPropertyFilter | EventMetadataPropertyFilter | SessionPropertyFilter | CohortPropertyFilter | RecordingPropertyFilter | LogEntryPropertyFilter | GroupPropertyFilter | FeaturePropertyFilter | FlagPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter | DataWarehousePropertyFilter | DataWarehousePersonPropertyFilter | ErrorTrackingIssueFilter | LogPropertyFilter | MetricPropertyFilter | SpanPropertyFilter | RevenueAnalyticsPropertyFilter | AccountCustomPropertyFilter | WorkflowVariablePropertyFilter | BehavioralPropertyFilter)[];
- }
-
export type Compare = typeof Compare[keyof typeof Compare];
@@ -119117,6 +119207,55 @@ export namespace Schemas {
include_history?: boolean;
};
+ export type AccountsPersonsRetrieveParams = {
+ /**
+ * JSON array of person property filters with key, operator, value, and type="person". Filters use AND.
+ */
+ filters?: string;
+ /**
+ * Maximum persons per page.
+ * @minimum 1
+ * @maximum 500
+ */
+ limit?: number;
+ /**
+ * Number of matching persons to skip.
+ * @minimum 0
+ */
+ offset?: number;
+ /**
+ * JSON array of selected person property keys. Example: ["email", "name"].
+ */
+ properties?: string;
+ /**
+ * Search name, email, person ID, or distinct ID.
+ * @maxLength 1000
+ */
+ search?: string;
+ /**
+ * Sort by id, display_name, account_first_seen, account_last_seen, or a selected property key.
+ * @minLength 1
+ * @maxLength 1000
+ */
+ sort_column?: string;
+ /**
+ * Sort direction. Person ID breaks ties.
+ *
+ * * `asc` - Ascending
+ * * `desc` - Descending
+ * @minLength 1
+ */
+ sort_direction?: AccountsPersonsRetrieveSortDirection;
+ };
+
+ export type AccountsPersonsRetrieveSortDirection = typeof AccountsPersonsRetrieveSortDirection[keyof typeof AccountsPersonsRetrieveSortDirection];
+
+
+ export const AccountsPersonsRetrieveSortDirection = {
+ Asc: 'asc',
+ Desc: 'desc',
+ } as const;
+
export type AccountsEmailThreadsListParams = {
/**
* Number of results to return per page.