: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from dataclasses import dataclass, field, replace
from typing import Literal, Optional
from products.warehouse_sources.sources.sdk import UNVERSIONED_API_VERSION, IncrementalField, IncrementalFieldType
VAPI_BASE_URL = "https://api.vapi.ai"
# Vapi's "v2" is a selective, per-resource scheme, not an account-wide or header-selected
# version: only some resources gained a distinct `/v2/<resource>` route, and the rest keep
# serving the same path and shape under both labels. Of the resources this source reads, only
# phone numbers diverge (see `version_overrides` below). `v1` is the legacy unversioned API
# existing rows are pinned to. See https://docs.vapi.ai/changelog/2025-09-17.
VAPI_VERSION_V1 = UNVERSIONED_API_VERSION
VAPI_VERSION_V2 = "v2"
SUPPORTED_VERSIONS = (VAPI_VERSION_V1, VAPI_VERSION_V2)
DEFAULT_VERSION = VAPI_VERSION_V2
# Vapi caps `limit` at 1000 (default 100). Call/chat objects can be large (full transcripts,
# message arrays, cost breakdowns), so keep pages at 100 rows to bound per-request memory.
DEFAULT_PAGE_LIMIT = 100
# How the endpoint paginates:
# - "created_at_cursor": returns a bare array in createdAt-descending order; the next page is
# requested with `createdAtLt=<oldest createdAt of the previous page>`.
# - "page": returns a `{results, metadata}` envelope with `page`/`sortOrder`/`sortBy` params.
# - "none": returns the full collection in a single unpaginated array.
VapiPaginationStyle = Literal["created_at_cursor", "page", "none"]
def _datetime_incremental_field(name: str) -> IncrementalField:
return {
"label": name,
"type": IncrementalFieldType.DateTime,
"field": name,
"field_type": IncrementalFieldType.DateTime,
}
@dataclass(frozen=True)
class VapiEndpointVersion:
"""Per-version override of an endpoint's request path and pagination style, for a resource
the vendor serves at a different route/shape under a newer API version."""
path: str
pagination: VapiPaginationStyle
@dataclass(frozen=False)
class VapiEndpointConfig:
name: str
path: str
pagination: VapiPaginationStyle
incremental_fields: list[IncrementalField] = field(default_factory=list)
# Stable datetime field used for partitioning. None disables partitioning.
partition_key: Optional[str] = "createdAt"
primary_keys: list[str] = field(default_factory=lambda: ["id"])
should_sync_default: bool = True
# Versions that serve this resource at a different path/pagination than the version-
# independent fields above, keyed by version label. Everything else (incremental fields,
# partitioning, primary keys) is identical across versions for the resources we read.
version_overrides: dict[str, VapiEndpointVersion] = field(default_factory=dict)
VAPI_ENDPOINTS: dict[str, VapiEndpointConfig] = {
# Calls is the flagship stream: transcripts, analysis, ended reasons, durations, and cost
# breakdowns. createdAt is the safe default cursor; updatedAt also has a server-side filter
# (`updatedAtGt`) and re-syncs calls whose analysis/artifacts were attached after the call ended.
"calls": VapiEndpointConfig(
name="calls",
path="/call",
pagination="created_at_cursor",
incremental_fields=[
_datetime_incremental_field("createdAt"),
_datetime_incremental_field("updatedAt"),
],
),
# Assistants/phone numbers/squads/tools are small config tables that mutate in place, so a
# createdAt watermark would go stale immediately; full refresh keeps them correct and cheap.
"assistants": VapiEndpointConfig(
name="assistants",
path="/assistant",
pagination="created_at_cursor",
),
"phone_numbers": VapiEndpointConfig(
name="phone_numbers",
path="/phone-number",
pagination="created_at_cursor",
version_overrides={
# v2 replaces the bare createdAt-descending array at /phone-number with a
# page-numbered {results, metadata} envelope served at /v2/phone-number.
VAPI_VERSION_V2: VapiEndpointVersion(path="/v2/phone-number", pagination="page"),
},
),
"squads": VapiEndpointConfig(
name="squads",
path="/squad",
pagination="created_at_cursor",
),
"tools": VapiEndpointConfig(
name="tools",
path="/tool",
pagination="created_at_cursor",
),
# GET /file takes no pagination params at all — single unpaginated array.
"files": VapiEndpointConfig(
name="files",
path="/file",
pagination="none",
partition_key=None,
),
# Page-based endpoints are requested with sortOrder=ASC&sortBy=createdAt so rows arrive in
# ascending createdAt order. Only createdAt is offered as an incremental field: the API can't
# sort by updatedAt, and an updatedAt watermark over createdAt-ordered pages would checkpoint
# values that later pages can undercut, losing rows on the next sync.
"chats": VapiEndpointConfig(
name="chats",
path="/chat",
pagination="page",
incremental_fields=[_datetime_incremental_field("createdAt")],
),
"sessions": VapiEndpointConfig(
name="sessions",
path="/session",
pagination="page",
incremental_fields=[_datetime_incremental_field("createdAt")],
),
# Run status and itemCounts change until the run ends, and the API can't sort by updatedAt, so
# a createdAt watermark would freeze in-flight runs; the table is small, so full refresh only.
"simulation_runs": VapiEndpointConfig(
name="simulation_runs",
path="/eval/simulation/run",
pagination="page",
),
# Campaigns mutate heavily (status plus per-call counters), so createdAt-incremental would go
# stale immediately; the table is small, so full refresh only.
"campaigns": VapiEndpointConfig(
name="campaigns",
path="/campaign",
pagination="page",
),
}
ENDPOINTS = tuple(VAPI_ENDPOINTS.keys())
def resolve_endpoint(endpoint: str, api_version: str) -> VapiEndpointConfig:
"""Endpoint config for a resolved version pin, swapping in any per-version path/pagination."""
config = VAPI_ENDPOINTS[endpoint]
override = config.version_overrides.get(api_version)
if override is None:
return config
return replace(config, path=override.path, pagination=override.pagination)
INCREMENTAL_FIELDS: dict[str, list[IncrementalField]] = {
name: config.incremental_fields for name, config in VAPI_ENDPOINTS.items()
}