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 4 missing tables to the Promptwatch source (#123937)

Tom Owers0a30aee37e74
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 608babe1f91f..b79bfcf3a7c3 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
@@ -9794,10 +9794,10 @@ Today (6): `monitors`, `personas`, `prompts`, `responses`, `tags`, `topics`
Diffed against: <https://promptwatch.com/docs/v2/openapi.json>
-- [ ] `Models (GET /api/v2/models)` — resolve response model identifiers into labels and search capabilities (high)
-- [ ] `Brands (GET /api/v2/brands)` — identify tracked brands and classify competitors for mention analysis (high)
-- [ ] `Grouped citations (GET /api/v2/citations/grouped)` — analyze cited URLs, citation share, position, and source authority beyond response citation counts (high)
-- [ ] `Visitor trends (GET /api/v2/analytics/visitors/trend)` — measure website traffic from AI referrers over time (high)
+- [x] `Models (GET /api/v2/models)` — resolve response model identifiers into labels and search capabilities (high)
+- [x] `Brands (GET /api/v2/brands)` — identify tracked brands and classify competitors for mention analysis (high)
+- [x] `Grouped citations (GET /api/v2/citations/grouped)` — analyze cited URLs, citation share, position, and source authority beyond response citation counts (high)
+- [x] `Visitor trends (GET /api/v2/analytics/visitors/trend)` — measure website traffic from AI referrers over time (high)
- [ ] `Crawler activity events (GET /api/v2/analytics/crawlers/events)` — analyze AI crawler requests, failures, and requested pages (medium)
- [ ] `Query fanouts (GET /api/v2/query-fanouts)` — analyze search queries generated by AI models when answering tracked prompts (medium)
- [ ] `Tracked pages (GET /api/v2/page-tracker)` — measure citation performance for individual website pages (medium)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/canonical_descriptions.py
index 6b80480e6860..4d172ed55b95 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/canonical_descriptions.py
@@ -64,4 +64,58 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"description": "Description of the audience profile.",
},
},
+ "models": {
+ "description": "Language models that Promptwatch supports, including deprecated models.",
+ "docs_url": "https://promptwatch.com/docs/api-reference/models/list-models",
+ "columns": {
+ "id": "Unique model identifier, as used in responses and monitors.",
+ "label": "Readable model label.",
+ "provider": "Provider identifier, for example openai or anthropic.",
+ "providerName": "Readable provider name.",
+ "modelName": "Model name.",
+ "apiIdentifier": "API identifier for the model.",
+ "description": "Model description.",
+ "searchEnabled": "Whether search is enabled for this model.",
+ "liveSearch": "Whether this model supports live search.",
+ "deprecated": "Whether the model is deprecated.",
+ },
+ },
+ "brands": {
+ "description": "Brands tracked in the project, with their relation to the project.",
+ "docs_url": "https://promptwatch.com/docs/api-reference/brands/list-brands",
+ "columns": {
+ "id": "Unique brand identifier.",
+ "name": "Brand name.",
+ "domain": "Brand hostname, when known.",
+ "relation": "Relation to the project: SELF, DIRECT_COMPETITOR, OTHER, or IGNORED.",
+ },
+ },
+ "grouped_citations": {
+ "description": (
+ "Cited URLs over the last 92 days, with citation count, share, and position. "
+ "Each sync keeps the 1,000 most cited URLs."
+ ),
+ "docs_url": "https://promptwatch.com/docs/api-reference/citations/grouped-citations",
+ "columns": {
+ "urlId": "Unique identifier of the cited URL.",
+ "url": "Cited page, with its title, source type, content type, page rank, traffic, and domain metrics.",
+ "count": "Number of times this URL was cited.",
+ "citationShare": "Percentage of analyzed responses that cite this URL.",
+ "avgPosition": "Average citation position, starting at 1.",
+ "minPosition": "Best (lowest) citation position.",
+ "maxPosition": "Worst (highest) citation position.",
+ "models": "Models that cited this URL most often.",
+ "totalModels": "Number of models that cited this URL.",
+ "providers": "Providers of the models that cited this URL.",
+ },
+ },
+ "visitor_trends": {
+ "description": "Daily website visits from AI referrers, with one row for each date and referrer.",
+ "docs_url": "https://promptwatch.com/docs/api-reference/analytics/visitor-trends",
+ "columns": {
+ "date": "Day of the visits, in UTC.",
+ "referrer": "AI referrer domain, for example chatgpt.com.",
+ "visitors": "Number of visits from this referrer on this day.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/promptwatch.py b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/promptwatch.py
index 9dd88d5c177d..1256965e4e99 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/promptwatch.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/promptwatch.py
@@ -30,11 +30,18 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_
from products.warehouse_sources.backend.temporal.data_imports.sources.promptwatch.settings import (
AUTH_ERROR,
BASE_URL,
+ CAPPED_ENDPOINTS,
+ CITATION_WINDOW_DAYS,
+ CREATED_AT_SORTED_ENDPOINTS,
+ DATA_SELECTORS,
+ EXTRA_PARAMS,
MAX_PAGES,
PAGE_SIZE,
PAGINATED_ENDPOINTS,
+ PATHS,
PROJECT_ERROR,
QUOTA_ERROR,
+ VISITOR_WINDOW_DAYS,
)
logger = structlog.get_logger(__name__)
@@ -63,8 +70,9 @@ def make_session(api_key: str, *, enforce_row_limit: bool) -> Session:
return
if response.status_code == 429 and "hourly API request limit" in str(body.get("message", "")):
raise NonReportableError("PROMPTWATCH_HOURLY_QUOTA")
- if response.ok and PAGINATED_ENDPOINTS.intersection(body):
- total_pages = body.get("totalPages")
+ if response.ok and ("pagination" in body or PAGINATED_ENDPOINTS.intersection(body)):
+ pagination = body.get("pagination", body)
+ total_pages = pagination.get("totalPages") if isinstance(pagination, dict) else None
if not isinstance(total_pages, int) or isinstance(total_pages, bool) or total_pages < 0:
raise ValueError("Promptwatch returned invalid pagination metadata.")
if total_pages > MAX_PAGES:
@@ -107,6 +115,77 @@ def validate_credentials(config: PromptWatchSourceConfig, api_version: str) -> t
return True, None
+def _rest_config(
+ config: PromptWatchSourceConfig, session: Session, api_version: str, resource: EndpointResource
+) -> RESTAPIConfig:
+ return {
+ "client": {
+ "base_url": f"{BASE_URL}/{api_version}",
+ "auth": {"type": "api_key", "name": "X-API-Key", "api_key": config.api_key},
+ "headers": {"X-Project-Id": config.project_id} if config.project_id else {},
+ "session": session,
+ "allow_redirects": False,
+ "request_timeout": 30,
+ },
+ "resources": [resource],
+ }
+
+
+def _citation_row(row: dict[str, Any]) -> dict[str, Any]:
+ return {"urlId": row["url"]["id"], **row}
+
+
+def _visitor_rows(body: dict[str, Any]) -> list[dict[str, Any]]:
+ dates = body.get("dates") or []
+ return [
+ {"date": day, "referrer": series["name"], "visitors": visitors}
+ for series in body.get("series") or []
+ for day, visitors in zip(dates, series["data"], strict=True)
+ ]
+
+
+def _as_date(value: object) -> date:
+ if isinstance(value, datetime):
+ return value.date()
+ if isinstance(value, date):
+ return value
+ return date.fromisoformat(str(value)[:10])
+
+
+def _visitor_trend_rows(
+ config: PromptWatchSourceConfig,
+ inputs: SourceInputs,
+ manager: ResumableSourceManager[PromptWatchResumeConfig],
+ api_version: str,
+) -> Iterator[list[dict[str, Any]]]:
+ end = datetime.now(UTC).date()
+ start = end - timedelta(days=VISITOR_WINDOW_DAYS - 1)
+ if inputs.should_use_incremental_field and inputs.db_incremental_field_last_value is not None:
+ # The last synced day can be partial, so read it again.
+ start = _as_date(inputs.db_incremental_field_last_value) - timedelta(days=1)
+ with make_session(config.api_key, enforce_row_limit=False) as session:
+ while start <= end:
+ window_end = min(start + timedelta(days=VISITOR_WINDOW_DAYS - 1), end)
+ resource: EndpointResource = {
+ "name": "visitor_trends",
+ "endpoint": {
+ "path": PATHS["visitor_trends"],
+ "params": {"startDate": start.isoformat(), "endDate": window_end.isoformat(), "timezone": "UTC"},
+ "data_selector": "$",
+ "paginator": "single_page",
+ },
+ "data_map": _visitor_rows,
+ }
+ yield from rest_api_resource(
+ _rest_config(config, session, api_version, resource),
+ inputs.team_id,
+ inputs.job_id,
+ db_incremental_field_last_value=None,
+ )
+ manager.safe_point()
+ start = window_end + timedelta(days=1)
+
+
def promptwatch_source(
config: PromptWatchSourceConfig,
inputs: SourceInputs,
@@ -114,6 +193,9 @@ def promptwatch_source(
api_version: str,
) -> Iterator[list[dict[str, Any]]]:
endpoint = inputs.schema_name
+ if endpoint == "visitor_trends":
+ yield from _visitor_trend_rows(config, inputs, manager, api_version)
+ return
paginated = endpoint in PAGINATED_ENDPOINTS
resume = manager.load_state() if paginated and manager.can_resume() else None
if resume and resume.page == 0:
@@ -128,45 +210,50 @@ def promptwatch_source(
last = last.replace(tzinfo=UTC) if last.tzinfo is None else last
start = max(start, last - timedelta(seconds=1))
from_date = start.isoformat()
+ elif endpoint == "grouped_citations":
+ today = datetime.now(UTC).date()
+ from_date = (today - timedelta(days=CITATION_WINDOW_DAYS - 1)).isoformat()
+ until = today.isoformat()
if resume:
from_date, until = resume.from_date, resume.until
- params: dict[str, Any] = {}
+ params: dict[str, Any] = dict(EXTRA_PARAMS.get(endpoint, {}))
if paginated:
- params.update(size=PAGE_SIZE, sortBy="createdAt", sortOrder="asc")
+ params.update(size=PAGE_SIZE)
+ if endpoint in CREATED_AT_SORTED_ENDPOINTS:
+ params.update(sortBy="createdAt", sortOrder="asc")
if from_date is not None:
- params.update({"from": from_date, "until": until})
+ if endpoint == "grouped_citations":
+ params.update(startDate=from_date, endDate=until)
+ else:
+ params.update({"from": from_date, "until": until})
def save_checkpoint(state: dict[str, Any] | None) -> None:
manager.save_state(
PromptWatchResumeConfig(page=int(state["page"]) if state else 0, from_date=from_date, until=until)
)
- with make_session(
- config.api_key, enforce_row_limit=not (endpoint == "responses" and inputs.should_use_incremental_field)
- ) as session:
+ enforce_row_limit = endpoint not in CAPPED_ENDPOINTS and not (
+ endpoint == "responses" and inputs.should_use_incremental_field
+ )
+ with make_session(config.api_key, enforce_row_limit=enforce_row_limit) as session:
endpoint_config: Endpoint = {
- "path": endpoint,
+ "path": PATHS.get(endpoint, endpoint),
"params": params,
- "data_selector": "$" if endpoint == "monitors" else endpoint,
+ "data_selector": DATA_SELECTORS.get(endpoint, endpoint),
"data_selector_required": True,
- "paginator": PageNumberPaginator(base_page=1, total_path="totalPages", maximum_page=MAX_PAGES)
+ "paginator": PageNumberPaginator(
+ base_page=1,
+ total_path="pagination.totalPages" if endpoint == "grouped_citations" else "totalPages",
+ maximum_page=MAX_PAGES,
+ )
if paginated
else "single_page",
}
resource: EndpointResource = {"name": endpoint, "endpoint": endpoint_config}
- rest_config: RESTAPIConfig = {
- "client": {
- "base_url": f"{BASE_URL}/{api_version}",
- "auth": {"type": "api_key", "name": "X-API-Key", "api_key": config.api_key},
- "headers": {"X-Project-Id": config.project_id} if config.project_id else {},
- "session": session,
- "allow_redirects": False,
- "request_timeout": 30,
- },
- "resources": [resource],
- }
+ if endpoint == "grouped_citations":
+ resource["data_map"] = _citation_row
yield from rest_api_resource(
- rest_config,
+ _rest_config(config, session, api_version, resource),
inputs.team_id,
inputs.job_id,
db_incremental_field_last_value=None,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/settings.py
index 3c9b1587e3f1..b8c2819d6958 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/settings.py
@@ -1,11 +1,40 @@
from products.warehouse_sources.backend.temporal.data_imports.sources.common.schema import incremental_field
+from products.warehouse_sources.backend.types import IncrementalFieldType
BASE_URL = "https://server.promptwatch.com/api"
PAGE_SIZE = 50
MAX_PAGES = 20
-ENDPOINTS = ("prompts", "responses", "monitors", "tags", "topics", "personas")
-PAGINATED_ENDPOINTS = {"prompts", "responses"}
-INCREMENTAL_FIELDS = {"responses": [incremental_field("createdAt")]}
+ENDPOINTS = (
+ "prompts",
+ "responses",
+ "monitors",
+ "tags",
+ "topics",
+ "personas",
+ "models",
+ "brands",
+ "grouped_citations",
+ "visitor_trends",
+)
+PAGINATED_ENDPOINTS = {"prompts", "responses", "brands", "grouped_citations"}
+CREATED_AT_SORTED_ENDPOINTS = {"prompts", "responses"}
+# Ranked by citation count, so the page cap keeps the most cited URLs instead of failing the sync.
+CAPPED_ENDPOINTS = {"grouped_citations"}
+PATHS = {"grouped_citations": "citations/grouped", "visitor_trends": "analytics/visitors/trend"}
+DATA_SELECTORS = {"monitors": "$", "grouped_citations": "data", "visitor_trends": "$"}
+EXTRA_PARAMS: dict[str, dict[str, str]] = {
+ "models": {"includeDeprecated": "true"},
+ "grouped_citations": {"sortBy": "count", "sortOrder": "desc"},
+}
+PRIMARY_KEYS = {"grouped_citations": ["urlId"], "visitor_trends": ["date", "referrer"]}
+INCREMENTAL_FIELDS = {
+ "responses": [incremental_field("createdAt")],
+ "visitor_trends": [incremental_field("date", IncrementalFieldType.Date)],
+}
+MERGE_ONLY_ENDPOINTS = {"responses", "visitor_trends"}
+# The API rejects date ranges longer than these.
+CITATION_WINDOW_DAYS = 92
+VISITOR_WINDOW_DAYS = 60
AUTH_ERROR = "Promptwatch rejected your API key. Check the key in Settings > API Keys."
PROJECT_ERROR = "Promptwatch denied access. Check your project ID and API key permissions."
QUOTA_ERROR = "Promptwatch reached its hourly API quota. Wait until the next UTC hour or upgrade your plan."
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/source.py
index a11af722e5e2..c5432769aa65 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/source.py
@@ -32,10 +32,13 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.promptwatc
validate_credentials,
)
from products.warehouse_sources.backend.temporal.data_imports.sources.promptwatch.settings import (
+ CREATED_AT_SORTED_ENDPOINTS,
ENDPOINTS,
INCREMENTAL_FIELDS,
+ MERGE_ONLY_ENDPOINTS,
NON_RETRYABLE_ERRORS,
PAGINATED_ENDPOINTS,
+ PRIMARY_KEYS,
)
from products.warehouse_sources.backend.types import ExternalDataSourceType
@@ -68,7 +71,7 @@ class PromptWatchSource(ResumableSource[PromptWatchSourceConfig, PromptWatchResu
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
- return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names, merge_only={"responses"})
+ return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names, merge_only=MERGE_ONLY_ENDPOINTS)
def validate_credentials(
self,
@@ -94,8 +97,8 @@ class PromptWatchSource(ResumableSource[PromptWatchSourceConfig, PromptWatchResu
items=lambda: promptwatch_source(
config, inputs, resumable_source_manager, self.resolve_api_version(inputs.api_version)
),
- primary_keys=["id"],
- sort_mode="asc" if inputs.schema_name in PAGINATED_ENDPOINTS else None,
+ primary_keys=PRIMARY_KEYS.get(inputs.schema_name, ["id"]),
+ sort_mode="asc" if inputs.schema_name in CREATED_AT_SORTED_ENDPOINTS else None,
supports_resume=inputs.schema_name in PAGINATED_ENDPOINTS,
)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/tests/test_promptwatch.py b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/tests/test_promptwatch.py
index d7706b0f5a69..8bbf7599a5ef 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/tests/test_promptwatch.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/promptwatch/tests/test_promptwatch.py
@@ -3,6 +3,7 @@ from datetime import UTC, datetime
from typing import Any
import pytest
+import time_machine
from unittest.mock import patch
from requests import HTTPError
@@ -94,16 +95,18 @@ def test_response_requests(
@pytest.mark.parametrize(
- "endpoint,body",
+ "endpoint,body,params",
[
- ("prompts", {"prompts": [{"id": "prompt"}], "totalPages": 1}),
- ("monitors", [{"id": "monitor"}]),
- ("tags", {"tags": [{"id": "tag"}]}),
- ("topics", {"topics": [{"id": "topic"}]}),
- ("personas", {"personas": [{"id": "persona"}]}),
+ ("prompts", {"prompts": [{"id": "prompt"}], "totalPages": 1}, {"sortBy": "createdAt"}),
+ ("monitors", [{"id": "monitor"}], {}),
+ ("tags", {"tags": [{"id": "tag"}]}, {}),
+ ("topics", {"topics": [{"id": "topic"}]}, {}),
+ ("personas", {"personas": [{"id": "persona"}]}, {}),
+ ("models", {"models": [{"id": "model"}], "total": 1}, {"includeDeprecated": "true"}),
+ ("brands", {"brands": [{"id": "brand"}], "total": 1, "totalPages": 1}, {"page": "1", "sortBy": None}),
],
)
-def test_configuration_tables(endpoint: str, body: object) -> None:
+def test_configuration_tables(endpoint: str, body: object, params: dict[str, str | None]) -> None:
config = PromptWatchSourceConfig(api_key="fake-api-key", start_date="2026-01-01")
result = run(config, endpoint, [ScriptedResponse(json=body)])
@@ -111,6 +114,8 @@ def test_configuration_tables(endpoint: str, body: object) -> None:
assert len(result.items) == 1 and len(result.items[0]) == 1
assert len(result.requests) == 1
assert result.requests[0].path == f"/api/v2/{endpoint}"
+ for name, value in params.items():
+ assert result.requests[0].param(name) == value
assert "from" not in result.requests[0].query
assert "until" not in result.requests[0].query
assert "x-project-id" not in result.requests[0].headers
@@ -277,3 +282,153 @@ def test_malformed_response_retries(config: PromptWatchSourceConfig, status: int
assert result.raised is None
assert len(result.requests) == 2
+
+
+def citation(url_id: str) -> dict[str, Any]:
+ return {"url": {"id": url_id, "url": f"https://{url_id}.example.com", "domain": {"domainName": "example.com"}}}
+
+
+@time_machine.travel(datetime(2026, 5, 10, 15, tzinfo=UTC), tick=False)
+def test_grouped_citations(config: PromptWatchSourceConfig) -> None:
+ result = run(
+ config,
+ "grouped_citations",
+ [
+ ScriptedResponse(json={"data": [citation("a")], "pagination": {"totalPages": 2}}),
+ ScriptedResponse(json={"data": [citation("b")], "pagination": {"totalPages": 2}}),
+ ],
+ )
+
+ assert result.raised is None
+ assert [row["urlId"] for row in result.rows] == ["a", "b"]
+ assert result.rows[0]["url"]["url"] == "https://a.example.com"
+ assert result.response is not None
+ assert result.response.primary_keys == ["urlId"]
+ assert result.response.sort_mode is None
+ assert result.paths == ["/api/v2/citations/grouped"] * 2
+ assert result.params("page") == ["1", "2"]
+ assert result.params("startDate") == ["2026-02-08"] * 2
+ assert result.params("endDate") == ["2026-05-10"] * 2
+ assert result.params("sortBy") == ["count"] * 2
+ assert result.params("sortOrder") == ["desc"] * 2
+ assert "from" not in result.requests[0].query
+ assert [state.page for state in result.saved_states] == [2, 0]
+
+
+def test_grouped_citations_resume_keeps_the_saved_window(config: PromptWatchSourceConfig) -> None:
+ result = run(
+ config,
+ "grouped_citations",
+ [ScriptedResponse(json={"data": [citation("b")], "pagination": {"totalPages": 2}})],
+ resume_state=PromptWatchResumeConfig(page=2, from_date="2026-01-01", until="2026-04-01"),
+ )
+
+ assert [row["urlId"] for row in result.rows] == ["b"]
+ assert result.params("page") == ["2"]
+ assert result.params("startDate") == ["2026-01-01"]
+ assert result.params("endDate") == ["2026-04-01"]
+
+
+ "endpoint,body,error",
+ [
+ ("grouped_citations", {"data": [citation("a")], "pagination": {"totalPages": MAX_PAGES + 1}}, None),
+ ("brands", {"brands": [{"id": "brand"}], "total": 2000, "totalPages": MAX_PAGES + 1}, "PROMPTWATCH_ROW_LIMIT"),
+ ("grouped_citations", {"data": [citation("a")], "pagination": {}}, "invalid pagination metadata"),
+ ("grouped_citations", {"data": [citation("a")], "pagination": None}, "invalid pagination metadata"),
+ ],
+)
+def test_page_limits_for_new_tables(
+ config: PromptWatchSourceConfig, endpoint: str, body: dict[str, Any], error: str | None
+) -> None:
+ with patch(LOGGER_PATCH) as logger:
+ result = run(config, endpoint, lambda _request: ScriptedResponse(json=body))
+
+ if error:
+ assert result.raised is not None
+ assert error in str(result.raised)
+ assert len(result.requests) == 1
+ else:
+ assert result.raised is None
+ assert result.params("page") == [str(page) for page in range(1, MAX_PAGES + 1)]
+ logger.warning.assert_called_once_with(
+ "promptwatch.page_cap_reached", maximum_page=MAX_PAGES, total_pages=MAX_PAGES + 1
+ )
+
+
+def visitor_body(dates: list[str], series: dict[str, list[int]]) -> dict[str, Any]:
+ return {"dates": dates, "series": [{"name": name, "data": data} for name, data in series.items()]}
+
+
+@time_machine.travel(datetime(2026, 5, 10, 15, tzinfo=UTC), tick=False)
+ "incremental,watermark,windows",
+ [
+ (False, None, [("2026-03-12", "2026-05-10")]),
+ (True, None, [("2026-03-12", "2026-05-10")]),
+ (False, "2026-05-08", [("2026-03-12", "2026-05-10")]),
+ (True, "2026-05-08", [("2026-05-07", "2026-05-10")]),
+ (True, datetime(2026, 5, 8, 0, tzinfo=UTC), [("2026-05-07", "2026-05-10")]),
+ (True, "2026-05-12", []),
+ (
+ True,
+ "2026-01-01",
+ [("2025-12-31", "2026-02-28"), ("2026-03-01", "2026-04-29"), ("2026-04-30", "2026-05-10")],
+ ),
+ ],
+)
+def test_visitor_trend_windows(
+ config: PromptWatchSourceConfig,
+ incremental: bool,
+ watermark: str | datetime | None,
+ windows: list[tuple[str, str]],
+) -> None:
+ result = run(
+ config,
+ "visitor_trends",
+ lambda _request: ScriptedResponse(json=visitor_body([], {})),
+ **incremental_inputs(incremental, watermark),
+ )
+
+ assert result.raised is None
+ assert result.rows == []
+ assert result.paths == ["/api/v2/analytics/visitors/trend"] * len(windows)
+ assert list(zip(result.params("startDate"), result.params("endDate"))) == windows
+ assert result.params("timezone") == ["UTC"] * len(windows)
+
+
+@time_machine.travel(datetime(2026, 3, 15, 15, tzinfo=UTC), tick=False)
+def test_visitor_trend_rows(config: PromptWatchSourceConfig) -> None:
+ result = run(
+ config,
+ "visitor_trends",
+ [
+ ScriptedResponse(
+ json=visitor_body(["2026-03-14", "2026-03-15"], {"chatgpt.com": [620, 655], "claude.ai": [0, 12]})
+ )
+ ],
+ **incremental_inputs(True, "2026-03-15"),
+ )
+
+ assert result.raised is None
+ assert result.rows == [
+ {"date": "2026-03-14", "referrer": "chatgpt.com", "visitors": 620},
+ {"date": "2026-03-15", "referrer": "chatgpt.com", "visitors": 655},
+ {"date": "2026-03-14", "referrer": "claude.ai", "visitors": 0},
+ {"date": "2026-03-15", "referrer": "claude.ai", "visitors": 12},
+ ]
+ assert result.response is not None
+ assert result.response.primary_keys == ["date", "referrer"]
+ assert result.saved_states == []
+
+
+@time_machine.travel(datetime(2026, 3, 15, 15, tzinfo=UTC), tick=False)
+def test_visitor_trend_series_length_mismatch_fails(config: PromptWatchSourceConfig) -> None:
+ result = run(
+ config,
+ "visitor_trends",
+ [ScriptedResponse(json=visitor_body(["2026-03-14", "2026-03-15"], {"chatgpt.com": [620]}))],
+ **incremental_inputs(True, "2026-03-15"),
+ )
+
+ assert isinstance(result.raised, ValueError)