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(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.txt
index 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.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/openfda/openfda.py
1 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.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/openweather/settings.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/opinion_stage/opinion_stage.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/opinion_stage/settings.py
diff --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.md
index 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.py
index 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.py
index 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.openrouter
OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
REQUEST_TIMEOUT = 60
-MAX_OFFSET_PAGES = 10_000
+MAX_PAGES = 10_000
class 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 = None
def _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.py
index 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: str
path: 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] = None
page_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.py
index 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.openrouter
from 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, OpenRouterResumeC
releaseStatus=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](htt
def _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 None
def _build_schema(endpoint: str) -> SourceSchema:
@@ -162,6 +171,8 @@ Use a **management API key** (create one under [Settings -> Management Keys](htt
endpoint = 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](htt
endpoint = 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_REQUIRED
else:
result[name] = None
return result
diff --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.py
index 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 None
assert 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.py
index 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_module
from 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 None
for 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())