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(openrouter): add workspace members, model endpoints and task classifications tables (#123364)

Tom Owerseb1b9efcaa28
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 7ae6dc017d9f..06c442b4d975 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
@@ -8829,11 +8829,11 @@ Today (7): `activity`, `api_keys`, `credits`, `models`, `organization_members`,
Diffed against: <https://openrouter.ai/docs/llms.txt>
-- [ ] `model endpoints (list all endpoints for a model)` — per-provider pricing, context length and availability - the lookup that joins the models and providers tables we already sync (high)
+- [x] `model endpoints (list all endpoints for a model)` — per-provider pricing, context length and availability - the lookup that joins the models and providers tables we already sync (high)
- [ ] `/api/v1/analytics/query (+ /analytics/meta)` — metric/dimension query over usage - richer breakdowns than the 30-day activity rollup we sync (high)
-- [ ] `workspace members` — membership table linking the workspaces and organization_members we already sync (high)
+- [x] `workspace members` — membership table linking the workspaces and organization_members we already sync (high)
- [ ] `benchmarks` — model benchmark scores, a lookup for model quality comparison (medium)
-- [ ] `task classifications (market share)` — per-task-category model market share, a breakdown dimension for usage analysis (medium)
+- [x] `task classifications (market share)` — per-task-category model market share, a breakdown dimension for usage analysis (medium)
- [ ] `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)
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 471b2850d046..b7c663777f1a 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
@@ -157,4 +157,59 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"results": "Always null in list responses.",
},
},
+ "workspace_members": {
+ "description": "Members of each workspace in the OpenRouter organization, with their workspace role. The default workspace lists every organization member.",
+ "docs_url": "https://openrouter.ai/docs/api/api-reference/workspaces/list-workspace-members",
+ "columns": {
+ "id": "Unique identifier for the workspace membership.",
+ "workspace_id": "ID of the workspace. Joins to workspaces.id.",
+ "user_id": "Clerk user ID of the member. Joins to organization_members.id.",
+ "role": "Role of the member in the workspace: admin or member.",
+ "created_at": "ISO 8601 timestamp of when the membership was created.",
+ },
+ },
+ "model_endpoints": {
+ "description": "Provider endpoints serving each model, with per-provider pricing, context length, quantization, and recent uptime, latency, and throughput.",
+ "docs_url": "https://openrouter.ai/docs/api/api-reference/endpoints/list-all-endpoints-for-a-model",
+ "columns": {
+ "parent_model_id": "ID of the model the endpoints were listed for. Joins to models.id.",
+ "model_id": "Permaslug of the model. Variants such as ':free' share it with their base model.",
+ "model_name": "Display name of the model.",
+ "name": "Display name of the endpoint.",
+ "tag": "Routing tag of the endpoint, unique per model, e.g. 'azure/swedencentral'.",
+ "provider_name": "Name of the provider serving the endpoint.",
+ "context_length": "Maximum context length in tokens for this endpoint.",
+ "max_completion_tokens": "Maximum completion tokens for this endpoint.",
+ "max_prompt_tokens": "Maximum prompt tokens for this endpoint.",
+ "pricing": "Per-token and per-request pricing on this endpoint.",
+ "quantization": "Quantization of the served weights, e.g. 'fp8', or null.",
+ "service_tier": "Service tier of the endpoint, or null.",
+ "status": "Endpoint status code.",
+ "supported_parameters": "Request parameters this endpoint supports.",
+ "supports_tool_choice": "Which tool_choice modes the endpoint supports.",
+ "supports_implicit_caching": "Whether the endpoint caches prompts without explicit cache markers.",
+ "native_tools": "Server tools the endpoint runs as the provider's own built-in tool.",
+ "uptime_last_5m": "Uptime percentage over the last 5 minutes.",
+ "uptime_last_30m": "Uptime percentage over the last 30 minutes.",
+ "uptime_last_1d": "Uptime percentage over the last day.",
+ "latency_last_30m": "Latency percentiles over the last 30 minutes.",
+ "throughput_last_30m": "Throughput percentiles over the last 30 minutes.",
+ },
+ },
+ "task_classifications": {
+ "description": "Share of all OpenRouter traffic by task classification (e.g. code generation, web search) over a trailing window, with the top models per classification. Covers every OpenRouter account, from sampled requests.",
+ "docs_url": "https://openrouter.ai/docs/api/api-reference/classifications/task-classification-market-share",
+ "columns": {
+ "tag": "Classification tag identifier, e.g. 'code:general_impl' or 'agent:web_search'.",
+ "display_name": "Human-readable label for the classification.",
+ "macro_category": "Coarse grouping derived from the tag prefix: code, data, agent, or general.",
+ "usage_share": "Fraction of classified sampled requests attributed to this classification (0-1).",
+ "token_share": "Fraction of classified sampled token volume attributed to this classification (0-1).",
+ "category_usage_share": "Fraction of this classification's usage within its macro-category (0-1).",
+ "category_token_share": "Fraction of this classification's token volume within its macro-category (0-1).",
+ "models": "Top models for this classification by request volume, with each model's share of its requests and tokens.",
+ "as_of": "Date the snapshot was computed (YYYY-MM-DD).",
+ "window_days": "Length of the trailing window in days.",
+ },
+ },
}
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 01ddfcb9c668..264519945979 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
@@ -2,7 +2,7 @@ import dataclasses
from collections.abc import Iterator
from datetime import UTC, date, datetime, timedelta
from typing import Any, Optional
-from urllib.parse import urlencode
+from urllib.parse import quote, urlencode
import requests
from structlog.types import FilteringBoundLogger
@@ -35,12 +35,16 @@ class OpenRouterPageCapError(Exception):
@dataclasses.dataclass(frozen=False)
class OpenRouterResumeConfig:
- # Offset already fetched for offset-paginated endpoints (api_keys/organization_members/workspaces).
+ # Offset already fetched for offset-paginated endpoints (api_keys/organization_members/workspaces),
+ # or within the current parent for fan-out endpoints.
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
+ # Fan-out endpoints walk parent ids sorted. This is the last parent with yielded rows; `offset` is
+ # set while that parent still has child pages left.
+ parent_id: str | None = None
def _headers(api_key: str) -> dict[str, str]:
@@ -241,6 +245,129 @@ def _get_cursor_rows(
raise OpenRouterPageCapError(f"OpenRouter: hit the {MAX_PAGES}-page cap for {config.name} with pages left")
+def _list_parent_ids(
+ session: requests.Session,
+ headers: dict[str, str],
+ logger: FilteringBoundLogger,
+ resumable_source_manager: ResumableSourceManager[OpenRouterResumeConfig],
+ parent: OpenRouterEndpointConfig,
+) -> list[str]:
+ ids: set[str] = set()
+ offset = 0
+ for _ in range(MAX_PAGES):
+ params: dict[str, Any] = dict(parent.params)
+ if parent.pagination is not None:
+ params["offset"] = offset
+ if parent.pagination == "offset_limit":
+ params["limit"] = parent.page_size
+
+ data = _fetch(session, _build_url(parent.path, params), headers, logger)
+ rows = data.get("data") or []
+ ids.update(str(row["id"]) for row in rows if row.get("id"))
+ resumable_source_manager.safe_point()
+
+ if parent.pagination is None or not rows:
+ break
+ if parent.pagination == "offset_limit" and len(rows) < parent.page_size:
+ break
+ offset += len(rows)
+ else:
+ # Fanning out over a partial parent list would replace the child table without the rest.
+ raise OpenRouterPageCapError(f"OpenRouter: hit the {MAX_PAGES}-page cap listing {parent.name}")
+
+ # Sorted, so the saved parent id marks the same point in the list on a resumed attempt.
+ return sorted(ids)
+
+
+def _get_child_pages(
+ session: requests.Session,
+ headers: dict[str, str],
+ logger: FilteringBoundLogger,
+ config: OpenRouterEndpointConfig,
+ parent_id: str,
+ offset: int,
+) -> Iterator[tuple[list[dict[str, Any]], int | None]]:
+ """Yield each child page of one parent with the offset to resume from, or None after the last page."""
+ path = config.path.replace("{parent_id}", quote(parent_id, safe="/:"))
+ for _ in range(MAX_PAGES):
+ params: dict[str, Any] = dict(config.params)
+ if config.pagination is not None:
+ params["offset"] = offset
+ if config.pagination == "offset_limit":
+ params["limit"] = config.page_size
+
+ try:
+ data = _fetch(session, _build_url(path, params), headers, logger)
+ except requests.HTTPError as e:
+ # The parent was deleted after we listed it.
+ if e.response is not None and e.response.status_code == 404:
+ yield [], None
+ return
+ raise
+
+ page = data.get("data")
+ if config.child_rows_key is not None:
+ page = page.get(config.child_rows_key) if isinstance(page, dict) else None
+ page = page or []
+ if config.parent_id_column is not None:
+ page = [{**row, config.parent_id_column: parent_id} for row in page]
+
+ is_last = (
+ config.pagination is None
+ or not page
+ or (config.pagination == "offset_limit" and len(page) < config.page_size)
+ )
+ offset += len(page)
+ yield page, None if is_last else offset
+ if is_last:
+ return
+
+ raise OpenRouterPageCapError(f"OpenRouter: hit the {MAX_PAGES}-page cap for {config.name} of {parent_id}")
+
+
+def _get_fan_out_rows(
+ session: requests.Session,
+ headers: dict[str, str],
+ logger: FilteringBoundLogger,
+ resumable_source_manager: ResumableSourceManager[OpenRouterResumeConfig],
+ config: OpenRouterEndpointConfig,
+ parent: OpenRouterEndpointConfig,
+) -> Iterator[list[dict[str, Any]]]:
+ # A saved parent id with an offset is a parent we stopped partway through; without one it's finished.
+ resume = resumable_source_manager.load_state() if resumable_source_manager.can_resume() else None
+ resume_parent = resume.parent_id if resume is not None else None
+ resume_offset = resume.offset if resume is not None else None
+
+ parent_ids = _list_parent_ids(session, headers, logger, resumable_source_manager, parent)
+ for parent_id in parent_ids:
+ offset = 0
+ if resume_parent is not None:
+ if parent_id < resume_parent or (parent_id == resume_parent and resume_offset is None):
+ continue
+ if parent_id == resume_parent and resume_offset is not None:
+ offset = resume_offset
+
+ for page, next_offset in _get_child_pages(session, headers, logger, config, parent_id, offset):
+ resumable_source_manager.save_state(OpenRouterResumeConfig(parent_id=parent_id, offset=next_offset))
+ if page:
+ yield page
+ else:
+ resumable_source_manager.safe_point()
+
+
+def _get_task_classification_rows(
+ session: requests.Session,
+ headers: dict[str, str],
+ logger: FilteringBoundLogger,
+ config: OpenRouterEndpointConfig,
+) -> Iterator[list[dict[str, Any]]]:
+ data = _fetch(session, _build_url(config.path, config.params), headers, logger).get("data") or {}
+ snapshot = {"as_of": data.get("as_of"), "window_days": data.get("window_days")}
+ rows = [{**row, **snapshot} for row in data.get("classifications") or []]
+ if rows:
+ yield rows
+
+
def _get_single_rows(
session: requests.Session,
headers: dict[str, str],
@@ -281,6 +408,12 @@ def get_rows(
should_use_incremental_field,
db_incremental_field_last_value,
)
+ elif config.fan_out_parent is not None:
+ yield from _get_fan_out_rows(
+ session, headers, logger, resumable_source_manager, config, OPENROUTER_ENDPOINTS[config.fan_out_parent]
+ )
+ elif config.task_classifications:
+ yield from _get_task_classification_rows(session, headers, logger, config)
elif config.pagination == "cursor":
yield from _get_cursor_rows(session, headers, logger, resumable_source_manager, config)
elif config.pagination is not 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 a8ac38a9a9cc..a0433e9299ef 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
@@ -39,6 +39,15 @@ class OpenRouterEndpointConfig:
is_singleton: bool = False
# Day-by-day pull driven by the ?date= filter (only /activity). See openrouter.py.
daily_activity: bool = False
+ # Fan-out child: `path` holds a `{parent_id}` placeholder filled with each `id` of this parent
+ # endpoint, and `pagination` applies to the child requests.
+ fan_out_parent: Optional[str] = None
+ # Child response `data` is an object holding the rows under this key (e.g. a model's endpoints).
+ child_rows_key: Optional[str] = None
+ # Column the parent id is copied into, for child rows that don't carry it themselves.
+ parent_id_column: Optional[str] = None
+ # /classifications/task wraps its rows with the snapshot date and window. See openrouter.py.
+ task_classifications: bool = False
should_sync_default: bool = True
@@ -115,6 +124,37 @@ OPENROUTER_ENDPOINTS: dict[str, OpenRouterEndpointConfig] = {
# rows with is_active=false instead of dropping them.
params={"include_inactive": "true"},
),
+ "workspace_members": OpenRouterEndpointConfig(
+ name="workspace_members",
+ path="/workspaces/{parent_id}/members",
+ requires_management_key=True,
+ # The default workspace lists every organization member through implicit membership, and the
+ # docs don't say what `id` holds for those rows, so key on the workspace and user instead.
+ primary_keys=["workspace_id", "user_id"],
+ partition_key="created_at",
+ pagination="offset_limit",
+ fan_out_parent="workspaces",
+ ),
+ "model_endpoints": OpenRouterEndpointConfig(
+ name="model_endpoints",
+ path="/models/{parent_id}/endpoints",
+ requires_management_key=False,
+ # `model_id` is the permaslug, which variants such as `:free` share with their base model, so
+ # the requested model id keys the rows. `tag` is unique per model, e.g. "azure/swedencentral".
+ primary_keys=["parent_model_id", "tag"],
+ fan_out_parent="models",
+ child_rows_key="endpoints",
+ parent_id_column="parent_model_id",
+ ),
+ "task_classifications": OpenRouterEndpointConfig(
+ name="task_classifications",
+ path="/classifications/task",
+ requires_management_key=False,
+ primary_keys=["tag"],
+ # Only the trailing 7-day window exists today; pinned so a new default can't change the table.
+ params={"window": "7d"},
+ task_classifications=True,
+ ),
"batches": OpenRouterEndpointConfig(
name="batches",
path="/batches",
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 29b47e4155b4..892ebe014c61 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
@@ -33,7 +33,7 @@ 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 read only "
- "the models, providers, and batches tables."
+ "the models, model endpoints, providers, task classifications, and batches tables."
)
_INFERENCE_KEY_REQUIRED = (
@@ -41,13 +41,14 @@ _INFERENCE_KEY_REQUIRED = (
"and a management key isn't tied to a workspace."
)
-# The organization members and workspaces endpoints resolve only when the management key's account
+# The organization members and workspaces endpoints (and the workspace members fan-out, which lists
+# workspaces first) resolve only when the management key's account
# belongs to an OpenRouter organization; an account without one gets a 404. Retrying can't create an
# organization, so we stop and tell the customer.
_NO_ORGANIZATION = (
- "Your OpenRouter account isn't part of an organization, so the organization members and workspaces "
- "tables can't be synced. Disable these tables, or reconnect with a management key that belongs to an "
- "organization."
+ "Your OpenRouter account isn't part of an organization, so the organization members, workspaces, and "
+ "workspace members tables can't be synced. Disable these tables, or reconnect with a management key that "
+ "belongs to an organization."
)
@@ -76,7 +77,7 @@ class OpenRouterSource(ResumableSource[OpenRouterSourceConfig, OpenRouterResumeC
releaseStatus=ReleaseStatus.GA,
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, end users, organization members, and workspaces tables can sync. A regular inference key can read only the models, providers, and batches tables.
+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, workspaces, and workspace members tables can sync. A regular inference key can read only the models, model endpoints, providers, task classifications, 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",
@@ -131,6 +132,10 @@ A management key can't read batches. To sync them, connect a second OpenRouter s
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"
+ if endpoint == "task_classifications":
+ return (
+ "Share of all OpenRouter traffic by task type over the last 7 days, across every OpenRouter account"
+ )
return None
def _build_schema(endpoint: str) -> SourceSchema:
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 4ed6683ec41a..4fe61d723851 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
@@ -199,6 +199,70 @@ class TestCursorPagination:
assert result.params("after") == ["b2"]
+class TestFanOut:
+ def test_workspace_members_walk_every_workspace_and_skip_a_deleted_one(self):
+ members_page1 = [{"workspace_id": "ws-a", "user_id": f"u{i}"} for i in range(100)]
+ members_page2 = [{"workspace_id": "ws-a", "user_id": "u100"}]
+ result = _driver().run(
+ "workspace_members",
+ [
+ ScriptedResponse(json={"data": [{"id": "ws-b"}, {"id": "ws-a"}]}),
+ ScriptedResponse(json={"data": members_page1}),
+ ScriptedResponse(json={"data": members_page2}),
+ ScriptedResponse(status=404, json={"error": {"code": 404}}),
+ ],
+ )
+
+ assert result.raised is None
+ assert result.paths == [
+ "/api/v1/workspaces",
+ "/api/v1/workspaces/ws-a/members",
+ "/api/v1/workspaces/ws-a/members",
+ "/api/v1/workspaces/ws-b/members",
+ ]
+ assert result.params("offset") == ["0", "0", "100", "0"]
+ assert result.items == [members_page1, members_page2]
+ assert result.saved_states == [
+ OpenRouterResumeConfig(parent_id="ws-a", offset=100),
+ OpenRouterResumeConfig(parent_id="ws-a"),
+ OpenRouterResumeConfig(parent_id="ws-b"),
+ ]
+
+ def test_workspace_members_resume_partway_through_a_workspace(self):
+ result = _driver().run(
+ "workspace_members",
+ [
+ ScriptedResponse(json={"data": [{"id": "ws-a"}, {"id": "ws-b"}, {"id": "ws-c"}]}),
+ ScriptedResponse(json={"data": [{"workspace_id": "ws-b", "user_id": "u100"}]}),
+ ScriptedResponse(json={"data": []}),
+ ],
+ resume_state=OpenRouterResumeConfig(parent_id="ws-b", offset=100),
+ )
+
+ assert result.raised is None
+ assert result.paths == [
+ "/api/v1/workspaces",
+ "/api/v1/workspaces/ws-b/members",
+ "/api/v1/workspaces/ws-c/members",
+ ]
+ assert result.params("offset") == ["0", "100", "0"]
+
+ def test_model_endpoints_resume_after_saved_model_and_tag_rows_with_it(self):
+ endpoint = {"model_id": "openai/gpt-oss-20b", "tag": "azure"}
+ result = _driver().run(
+ "model_endpoints",
+ [
+ ScriptedResponse(json={"data": [{"id": "openai/gpt-oss-20b"}, {"id": "openai/gpt-oss-20b:free"}]}),
+ ScriptedResponse(json={"data": {"id": "openai/gpt-oss-20b:free", "endpoints": [endpoint]}}),
+ ],
+ resume_state=OpenRouterResumeConfig(parent_id="openai/gpt-oss-20b"),
+ )
+
+ assert result.raised is None
+ assert result.paths == ["/api/v1/models", "/api/v1/models/openai/gpt-oss-20b:free/endpoints"]
+ assert result.items == [[{**endpoint, "parent_model_id": "openai/gpt-oss-20b:free"}]]
+
+
class TestSingleAndSingleton:
def test_models_yields_list(self):
rows = [{"id": "a"}, {"id": "b"}]
@@ -206,6 +270,15 @@ class TestSingleAndSingleton:
assert result.raised is None
assert result.items == [rows]
+ def test_task_classifications_copy_snapshot_onto_each_row(self):
+ classification = {"tag": "code:general_impl", "usage_share": 0.23, "models": [{"id": "openai/gpt-4.1-mini"}]}
+ body = {"data": {"as_of": "2026-06-17", "window_days": 7, "classifications": [classification]}}
+ result = _driver().run("task_classifications", [ScriptedResponse(json=body)])
+
+ assert result.raised is None
+ assert result.params("window") == ["7d"]
+ assert result.items == [[{**classification, "as_of": "2026-06-17", "window_days": 7}]]
+
def test_credits_singleton_wrapped_in_list(self):
row = {"total_credits": 10, "total_usage": 3}
result = _driver().run("credits", [ScriptedResponse(json={"data": row})])