: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
feat(data-warehouse): add end users and batches tables to openrouter (#119533)
Tom Owerse983bca37e5b
diff --git a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt b/posthog/test/repo_invariants/dataclass_frozen_baseline.txtindex e116d6595741..88664ab9a903 100644--- a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt+++ b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt@@ -838,8 +838,6 @@1 products/warehouse_sources/backend/temporal/data_imports/sources/openaq/settings.py1 products/warehouse_sources/backend/temporal/data_imports/sources/openfda/openfda.py1 products/warehouse_sources/backend/temporal/data_imports/sources/openfda/settings.py-1 products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/openrouter.py-1 products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/settings.py1 products/warehouse_sources/backend/temporal/data_imports/sources/openweather/settings.py1 products/warehouse_sources/backend/temporal/data_imports/sources/opinion_stage/opinion_stage.py1 products/warehouse_sources/backend/temporal/data_imports/sources/opinion_stage/settings.pydiff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.mdindex 2a835f579fdc..3d0af8b625fc 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md@@ -8837,6 +8837,8 @@ Diffed against: <https://openrouter.ai/docs/llms.txt>- [ ] `app rankings (top apps by token usage)` — token usage leaderboard by app (medium)- [ ] `daily rankings (daily token totals for top 50 models)` — daily model-level token time series (medium)- [ ] `workspace budgets` — per-workspace spend limits, needed to compare spend against budget (low)+- [x] `/end-users` — registered end-user tracking IDs, the lookup for the `user` field on inference requests and API keys (medium)+- [x] `/batches` — asynchronous batch inference jobs with status, request counts, usage and cost (medium)Note: No public OpenAPI JSON is reachable (openrouter.ai/docs/openapi.json 404s); the operation inventory was read from the official Go SDK reference pages linked from llms.txt. Generations endpoints were excluded because they require a known generation ID and cannot be bulk-listed. Guardrails, presets, BYOK, files and observability destinations excluded as config.diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/canonical_descriptions.pyindex 746c6c58b721..471b2850d046 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/canonical_descriptions.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/canonical_descriptions.py@@ -127,4 +127,34 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {"updated_at": "ISO 8601 timestamp of when the workspace was last updated.",},},+ "end_users": {+ "description": "End-user tracking IDs registered under the OpenRouter organization, including deactivated registrations.",+ "docs_url": "https://openrouter.ai/docs/api/api-reference/end-users/list-registered-end-users",+ "columns": {+ "user": "Immutable, case-sensitive tracking ID supplied as `user` on inference requests or as `external.user` on API keys.",+ "is_active": "Whether this registration is active. This is not an inference authorization decision.",+ "created_at": "ISO 8601 timestamp of when the registration was created.",+ "updated_at": "ISO 8601 timestamp of the last registration lifecycle update.",+ },+ },+ "batches": {+ "description": "Asynchronous batch inference jobs in the workspace of the API key, with status, request counts, and usage. Results are not included.",+ "docs_url": "https://openrouter.ai/docs/batch-quickstart",+ "columns": {+ "id": "Unique identifier for the batch.",+ "object": "Object type, always 'batch'.",+ "endpoint": "Inference endpoint the batch requests run against, e.g. '/v1/chat/completions'.",+ "model": "Model the batch requests run on.",+ "completion_window": "Requested completion window for the batch, e.g. '24h'.",+ "status": "Batch status: validating, in_progress, finalizing, completed, failed, expired, cancelling, or cancelled.",+ "created_at": "Unix timestamp of when the batch was created.",+ "finalized_at": "Unix timestamp of when the batch reached a terminal status, or null.",+ "expires_at": "Unix timestamp after which the assigned provider no longer completes unfinished requests, or null when the provider documents no hard expiry.",+ "provider": "Provider OpenRouter assigned to run the batch.",+ "request_counts": "Total, completed, and failed request counts for the batch.",+ "usage": "Aggregated token usage and cost for the batch.",+ "error": "Error details for a failed batch, or null.",+ "results": "Always null in list responses.",+ },+ },}diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/openrouter.py b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/openrouter.pyindex 84c5f5b8710f..1f87fbdf00c7 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/openrouter.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/openrouter.py@@ -19,19 +19,25 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.openrouterOPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"REQUEST_TIMEOUT = 60-MAX_OFFSET_PAGES = 10_000+MAX_PAGES = 10_000class OpenRouterRetryableError(Exception):pass+class OpenRouterPageCapError(Exception):+ pass++[email protected](frozen=False)class OpenRouterResumeConfig:# Offset already fetched for offset-paginated endpoints (api_keys/organization_members/workspaces).offset: int | None = None# Last fully-synced UTC day (YYYY-MM-DD) for the /activity day-by-day pull.date: str | None = None+ # `after` cursor of the next page for cursor-paginated endpoints (batches).+ after: str | None = Nonedef _headers(api_key: str) -> dict[str, str]:@@ -175,8 +181,8 @@ def _get_offset_rows(offset = resume.offset if resume is not None and resume.offset else 0# Hard cap as a runaway guard in case an endpoint ignores `offset` and re-serves the same page.- for _ in range(MAX_OFFSET_PAGES):- params: dict[str, Any] = {"offset": offset}+ for _ in range(MAX_PAGES):+ params: dict[str, Any] = {**config.params, "offset": offset}if config.pagination == "offset_limit":params["limit"] = config.page_size@@ -197,7 +203,39 @@ def _get_offset_rows(# Save AFTER yielding so a crash re-yields the last page (merge dedupes on the primary key).resumable_source_manager.save_state(OpenRouterResumeConfig(offset=offset))else:- logger.warning(f"OpenRouter: hit the {MAX_OFFSET_PAGES}-page cap for {config.name}; stopping pagination")+ logger.warning(f"OpenRouter: hit the {MAX_PAGES}-page cap for {config.name}; stopping pagination")+++def _get_cursor_rows(+ session: requests.Session,+ headers: dict[str, str],+ logger: FilteringBoundLogger,+ resumable_source_manager: ResumableSourceManager[OpenRouterResumeConfig],+ config: OpenRouterEndpointConfig,+) -> Iterator[list[dict[str, Any]]]:+ resume = resumable_source_manager.load_state() if resumable_source_manager.can_resume() else None+ after = resume.after if resume is not None else None++ for _ in range(MAX_PAGES):+ params: dict[str, Any] = {**config.params, "limit": config.page_size}+ if after:+ params["after"] = after++ data = _fetch(session, _build_url(config.path, params), headers, logger)+ rows = data.get("data") or []+ next_after = data.get("last_id") if data.get("has_more") else None++ if rows and next_after:+ resumable_source_manager.save_state(OpenRouterResumeConfig(after=next_after))+ if rows:+ yield rows++ if not rows or not next_after:+ break+ after = next_after+ else:+ # A full refresh that stops here would replace the table without the older rows.+ raise OpenRouterPageCapError(f"OpenRouter: hit the {MAX_PAGES}-page cap for {config.name} with pages left")def _get_single_rows(@@ -240,6 +278,8 @@ def get_rows(should_use_incremental_field,db_incremental_field_last_value,)+ elif config.pagination == "cursor":+ yield from _get_cursor_rows(session, headers, logger, resumable_source_manager, config)elif config.pagination is not None:yield from _get_offset_rows(session, headers, logger, resumable_source_manager, config)else:@@ -268,8 +308,8 @@ def openrouter_source(),primary_keys=config.primary_keys,# /activity yields days oldest-first and offset pages advance forward, so the watermark- # checkpoints safely after each batch.- sort_mode="asc",+ # checkpoints safely after each batch. /batches is newest-first.+ sort_mode=config.sort_mode,partition_count=1,partition_size=1,partition_mode="datetime" if config.partition_key else None,diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/settings.pyindex 524cde64aadc..a8ac38a9a9cc 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/settings.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/settings.py@@ -7,16 +7,19 @@ from products.warehouse_sources.backend.types import IncrementalField, Increment# through this endpoint, so both the first sync and every incremental sync are bounded to this window.ACTIVITY_RETENTION_DAYS = 30-PaginationMode = Literal["offset", "offset_limit"]+PaginationMode = Literal["offset", "offset_limit", "cursor"]-@dataclass+@dataclass(frozen=True)class OpenRouterEndpointConfig:name: strpath: str# Management endpoints (activity/api_keys/credits/organization_members/workspaces) require an# OpenRouter management key; the models/providers catalogs are public and read with any valid key.requires_management_key: bool+ # Batches are scoped to the workspace of the calling key, which an account-level management key+ # doesn't have, so they can only be read with a regular inference key.+ requires_inference_key: bool = False# Table-wide unique key. None for the /credits singleton (a single balance snapshot, full-refresh# replace, so there's nothing to merge on).primary_keys: Optional[list[str]] = field(default_factory=lambda: ["id"])@@ -26,8 +29,12 @@ class OpenRouterEndpointConfig:# Offset-based pagination style, or None for a single unpaginated request.# "offset" -> only an `offset` query param (e.g. /keys)# "offset_limit" -> `offset` + `limit` query params (e.g. /organization/members, /workspaces)+ # "cursor" -> `after` set to the previous page's `last_id` while `has_more` (e.g. /batches)pagination: Optional[PaginationMode] = Nonepage_size: int = 100+ # Fixed query params sent on every page.+ params: dict[str, str] = field(default_factory=dict)+ sort_mode: Literal["asc", "desc"] = "asc"# `data` is a single object rather than a list of rows (e.g. /credits).is_singleton: bool = False# Day-by-day pull driven by the ?date= filter (only /activity). See openrouter.py.@@ -97,6 +104,31 @@ OPENROUTER_ENDPOINTS: dict[str, OpenRouterEndpointConfig] = {primary_keys=["id"],pagination="offset_limit",),+ "end_users": OpenRouterEndpointConfig(+ name="end_users",+ path="/end-users",+ requires_management_key=True,+ primary_keys=["user"],+ partition_key="created_at",+ pagination="offset_limit",+ # Deactivated registrations are hidden by default; include them so a full refresh keeps their+ # rows with is_active=false instead of dropping them.+ params={"include_inactive": "true"},+ ),+ "batches": OpenRouterEndpointConfig(+ name="batches",+ path="/batches",+ requires_management_key=False,+ requires_inference_key=True,+ primary_keys=["id"],+ partition_key="created_at",+ pagination="cursor",+ # The list is newest-first only. Full refresh, because a batch's status, request counts and+ # usage keep changing after it's created.+ sort_mode="desc",+ # The source is usually connected with a management key, which can't read this table.+ should_sync_default=False,+ ),}ENDPOINTS = tuple(OPENROUTER_ENDPOINTS.keys())diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/source.pyindex a0f5c895e036..78cb18b119b7 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/source.py@@ -32,8 +32,13 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.openrouterfrom products.warehouse_sources.backend.types import ExternalDataSourceType_MANAGEMENT_KEY_REQUIRED = (- "Requires an OpenRouter management API key. This key is a regular inference key, which can only "- "read the models and providers catalogs."+ "Requires an OpenRouter management API key. This key is a regular inference key, which can read only "+ "the models, providers, and batches tables."+)++_INFERENCE_KEY_REQUIRED = (+ "Requires a regular OpenRouter API key. Batches belong to the workspace of the key that reads them, "+ "and a management key isn't tied to a workspace.")# The organization members and workspaces endpoints resolve only when the management key's account@@ -71,7 +76,9 @@ class OpenRouterSource(ResumableSource[OpenRouterSourceConfig, OpenRouterResumeCreleaseStatus=ReleaseStatus.BETA,caption="""Enter your OpenRouter API key to pull your OpenRouter usage and account data into the PostHog Data warehouse.-Use a **management API key** (create one under [Settings -> Management Keys](https://openrouter.ai/settings/keys)) so the activity, API keys, credits, organization members, and workspaces tables can sync. A regular inference key can only read the models and providers catalogs.""",+Use a **management API key** (create one under [Settings -> Management Keys](https://openrouter.ai/settings/keys)) so the activity, API keys, credits, end users, organization members, and workspaces tables can sync. A regular inference key can read only the models, providers, and batches tables.++A management key can't read batches. To sync them, connect a second OpenRouter source with a regular API key.""",iconPath="/static/services/openrouter.png",docsUrl="https://posthog.com/docs/cdp/sources/openrouter",keywords=["llm", "ai gateway", "usage", "inference"],@@ -122,6 +129,8 @@ Use a **management API key** (create one under [Settings -> Management Keys](httdef _description(endpoint: str) -> str | None:if endpoint == "activity":return "Daily usage rollups; only the last 30 completed UTC days are available"+ if endpoint == "batches":+ return "Batch jobs in the API key's workspace; needs a regular API key, not a management key"return Nonedef _build_schema(endpoint: str) -> SourceSchema:@@ -162,6 +171,8 @@ Use a **management API key** (create one under [Settings -> Management Keys](httendpoint = OPENROUTER_ENDPOINTS.get(schema_name)if endpoint is not None and endpoint.requires_management_key and not info.get("is_management_key"):return False, f"The '{schema_name}' table requires an OpenRouter management API key."+ if endpoint is not None and endpoint.requires_inference_key and info.get("is_management_key"):+ return False, f"The '{schema_name}' table requires a regular OpenRouter API key, not a management key."return True, None@@ -181,6 +192,8 @@ Use a **management API key** (create one under [Settings -> Management Keys](httendpoint = OPENROUTER_ENDPOINTS.get(name)if endpoint is not None and endpoint.requires_management_key and not is_management_key:result[name] = _MANAGEMENT_KEY_REQUIRED+ elif endpoint is not None and endpoint.requires_inference_key and is_management_key:+ result[name] = _INFERENCE_KEY_REQUIREDelse:result[name] = Nonereturn resultdiff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter.py b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter.pyindex 7d85fb548088..4ed6683ec41a 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter.py@@ -146,11 +146,57 @@ class TestOffsetPagination:# State saved after the first full page, not after the short page.assert result.saved_states == [OpenRouterResumeConfig(offset=100)]- def test_offset_limit_endpoints_send_limit(self):- result = _driver().run("organization_members", [ScriptedResponse(json={"data": []})])+ @pytest.mark.parametrize(+ "endpoint,include_inactive",+ [("organization_members", [None]), ("end_users", ["true"])],+ )+ def test_offset_limit_endpoints_send_limit(self, endpoint, include_inactive):+ result = _driver().run(endpoint, [ScriptedResponse(json={"data": []})])assert result.raised is Noneassert result.params("limit") == ["100"]+ assert result.params("include_inactive") == include_inactive+++class TestCursorPagination:+ def test_batches_follow_last_id_until_has_more_is_false(self):+ page1 = [{"id": "b3"}, {"id": "b2"}]+ page2 = [{"id": "b1"}]+ result = _driver().run(+ "batches",+ [+ ScriptedResponse(json={"data": page1, "has_more": True, "last_id": "b2"}),+ ScriptedResponse(json={"data": page2, "has_more": False, "last_id": "b1"}),+ ],+ )++ assert result.raised is None+ assert result.items == [page1, page2]+ assert result.params("after") == [None, "b2"]+ assert result.params("limit") == ["100", "100"]+ assert result.saved_states == [OpenRouterResumeConfig(after="b2")]++ def test_batches_fail_when_page_cap_leaves_pages_unread(self):+ with mock.patch.object(openrouter, "MAX_PAGES", 2):+ result = _driver().run(+ "batches",+ [+ ScriptedResponse(json={"data": [{"id": "b3"}], "has_more": True, "last_id": "b3"}),+ ScriptedResponse(json={"data": [{"id": "b2"}], "has_more": True, "last_id": "b2"}),+ ],+ )++ assert isinstance(result.raised, openrouter.OpenRouterPageCapError)++ def test_batches_resume_from_saved_cursor(self):+ result = _driver().run(+ "batches",+ [ScriptedResponse(json={"data": [{"id": "b1"}], "has_more": False, "last_id": "b1"})],+ resume_state=OpenRouterResumeConfig(after="b2"),+ )++ assert result.raised is None+ assert result.params("after") == ["b2"]class TestSingleAndSingleton:diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter_source.pyindex 3f240f8cb6f4..0d8b84663cd8 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter_source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/openrouter/tests/test_openrouter_source.py@@ -9,7 +9,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_from products.warehouse_sources.backend.temporal.data_imports.sources.openrouter import source as source_modulefrom products.warehouse_sources.backend.temporal.data_imports.sources.openrouter.source import OpenRouterSource-MANAGEMENT_ENDPOINTS = ["activity", "api_keys", "credits", "organization_members", "workspaces"]+MANAGEMENT_ENDPOINTS = ["activity", "api_keys", "credits", "end_users", "organization_members", "workspaces"]CATALOG_ENDPOINTS = ["models", "providers"]@@ -60,3 +60,14 @@ class TestOpenRouterSource:assert result[name] is Nonefor name in MANAGEMENT_ENDPOINTS:assert result[name] is not None++ def test_batches_rejected_for_management_key(self):+ with _patch_key_info({"is_management_key": True}):+ ok, error = self.source.validate_credentials(self.config, self.team_id, schema_name="batches")+ result = self.source.get_endpoint_permissions(+ self.config, self.team_id, ["batches", *MANAGEMENT_ENDPOINTS, *CATALOG_ENDPOINTS]+ )+ assert ok is False+ assert error is not None+ assert result.pop("batches") is not None+ assert all(reason is None for reason in result.values())