--- title: "Read a stored research report" method: GET path: "/projects/{project_id}/research/reports/{kind}" tags: ["research-reports"] --- # Read a stored research report `GET /projects/{project_id}/research/reports/{kind}` ## Request - Base URL: `https://eu.bisibility.com/api/v1` - URL: `https://eu.bisibility.com/api/v1/projects/{project_id}/research/reports/{kind}` - Auth: one of: - HTTP bearer - HTTP bearer - OAuth 2 (authorization code, authorization URL `/api/auth/oauth2/authorize`, token URL `/api/auth/oauth2/token`, scopes: `api:read`) Read-only view of a report that is already stored. Reads never call a provider and never require a connected provider. A report is fresh while now is before fresh_until. ## Path parameters - `project_id` string, required: Public project ID; membership and token scope are enforced. - `kind` 'backlinks' | 'domain_overview' | 'keyword_research', required ## Query parameters - `target` string - `target_scope` string - `mode` string - `include_subdomains` boolean - `seed` string - `include_clickstream` boolean - `result_limit` 100 | 300 | 500 - `connection_id` string - `language_code` string - `location_code` integer ## Headers - `Bisibility-API-Version` 'v1' - `X-Bisibility-Source` 'sdk' | 'cli' | 'mcp' ## Response `200` JSON response - StoredResearchReportResponse - `data` union, required - union - object - `history` unknown - `history_unavailable` unknown - `target_scope` 'site', required - `fresh_until` string, date-time, required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - `saved_at` string, date-time, required - `stale` boolean, required - `state` 'fresh' | 'stale', required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - object - `history` unknown - `history_unavailable` unknown, required - `fresh_until` string, date-time, required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - `saved_at` string, date-time, required - `stale` boolean, required - `state` 'fresh' | 'stale', required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - object - `history` unknown - `history_unavailable` unknown - `target_scope` 'page', required - `fresh_until` string, date-time, required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - `saved_at` string, date-time, required - `stale` boolean, required - `state` 'fresh' | 'stale', required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - StoredDomainOverviewReport - `cached` boolean, required - `cost_cents` number, required - `country_code` string, nullable, required - `data_state` 'no_data' | 'ok' | 'partial', required: the stored report outcome, the same value GET /projects/{project_id}/domain-overview returns as state - `fetched_at` string, date-time, required - `fresh_until` string, date-time, required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - `history` DomainOverviewHistoricalRow[], nullable, required - `metrics` DomainOverviewMetrics, required - `count` integer, nullable, required - `estimated_traffic_cost_cents` number, nullable, required - `etv` number, nullable, required - `is_down` integer, required - `is_lost` integer, required - `is_new` integer, required - `is_up` integer, required - `pos1` integer, required - `pos2_3` integer, required - `pos4_10` integer, required - `pos11_20` integer, required - `pos21_30` integer, required - `pos31_40` integer, required - `pos41_50` integer, required - `pos51_60` integer, required - `pos61_70` integer, required - `pos71_80` integer, required - `pos81_90` integer, required - `pos91_100` integer, required - `month` integer, required - `year` integer, required - `keywords` DomainOverviewKeywordsData, required - `cost_cents` number, required - `rows` object[], required - `cpc_cents` number, nullable, required - `difficulty` number, nullable, required - `estimated_traffic` number, nullable, required - `intent` 'informational' | 'navigational' | 'commercial' | 'transactional' | 'null', nullable, required - `keyword` string, required - `position` number, nullable, required - `rank_absolute` number, nullable, required - `rank_absolute_delta` number, nullable, required - `ranking_url` string, nullable, required - `search_volume` number, nullable, required - `serp_features` string[], required - `total_count` integer, nullable, required - `language_code` string, required - `location_code` integer, required - `overview` DomainOverviewMetrics, required - `count` integer, nullable, required - `estimated_traffic_cost_cents` number, nullable, required - `etv` number, nullable, required - `is_down` integer, required - `is_lost` integer, required - `is_new` integer, required - `is_up` integer, required - `pos1` integer, required - `pos2_3` integer, required - `pos4_10` integer, required - `pos11_20` integer, required - `pos21_30` integer, required - `pos31_40` integer, required - `pos41_50` integer, required - `pos51_60` integer, required - `pos61_70` integer, required - `pos71_80` integer, required - `pos81_90` integer, required - `pos91_100` integer, required - `pages` DomainOverviewPagesData, required - `cost_cents` number, required - `rows` object[], required - `etv` number, nullable, required - `etv_delta_pct` number, nullable, required - `keyword_count` integer, nullable, required - `path` string, required - `top_keyword` string, nullable, required - `top_keyword_position` number, nullable, required - `total_count` integer, required - `partial` boolean, required - `previous_fetched_at` string, date-time, nullable, required - `previous_overview` DomainOverviewMetrics, required - `count` integer, nullable, required - `estimated_traffic_cost_cents` number, nullable, required - `etv` number, nullable, required - `is_down` integer, required - `is_lost` integer, required - `is_new` integer, required - `is_up` integer, required - `pos1` integer, required - `pos2_3` integer, required - `pos4_10` integer, required - `pos11_20` integer, required - `pos21_30` integer, required - `pos31_40` integer, required - `pos41_50` integer, required - `pos51_60` integer, required - `pos61_70` integer, required - `pos71_80` integer, required - `pos81_90` integer, required - `pos91_100` integer, required - `previous_source_snapshot_at` string, date-time, nullable, required - `provider` string, required - `saved_at` string, date-time, required - `scope` 'root' | 'subdomain', required - `source_snapshot_at` string, date-time, nullable, required - `stale` boolean, required - `state` 'fresh' | 'stale', required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. This is report freshness, not the data outcome; data_state carries the no_data/ok/partial value that GET /projects/{project_id}/domain-overview returns as state. - `target` string, required - StoredKeywordResearchReport - `cached` boolean, required - `cost_cents` number, required - `country_code` string, required - `fetched_at` string, date-time, required - `fresh_until` string, date-time, required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. - `include_clickstream` boolean, required - `language_code` string, required - `mode` string, required - `partial` boolean, required - `provider` string, required - `request_key` string, required - `result_limit` integer, required - `rows` object[], required - `already_saved` boolean, required - `already_tracked` boolean, required - `keyword` string, required - `source` 'related' | 'suggestion' | 'idea', required - `competition` number, nullable, required - `cpc_cents` integer, nullable, required - `difficulty` integer, nullable, required - `intent` string, required - `monthly_trend` object[], required - `month` integer, required - `search_volume` number, nullable, required - `year` integer, required - `search_volume` number, nullable, required - `saved_at` string, date-time, required - `seed` string, required - `sources` object[], required - `cached` boolean, required - `cost_cents` number, required - `reason` 'budget_exhausted' | 'cost_limit' | 'in_progress' | 'needs_reauth' | 'no_source' | 'previous_source_failed' | 'provider_error' | 'rate_limited' | 'result_limit' | 'unsupported_location' - `returned` integer, required - `source` 'related' | 'suggestion' | 'idea', required - `status` 'ok' | 'failed' | 'skipped', required - `stale` boolean, required - `state` 'fresh' | 'stale', required: fresh_until is authoritative: a report is fresh while now is before fresh_until, and the window is 30 days counted from the earliest successful source fetch, which can be earlier than saved_at. ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - `404`: Not found - `409`: Unsupported API version - `429`: Rate limited ## Changes - **2026-10-19** `a6e1ec0dec82`: 1 breaking, 6 info - added the new path request parameter `project_id` - the endpoint scheme security `AppOAuth` was added to the API - media type `application/json` was changed to a more specific media type `application/problem+json` for the response status `400` - media type `application/json` was changed to a more specific media type `application/problem+json` for the response status `401` - …3 more [Operation history](https://skmtc.dev/bisibility/apis/bisibility-public-api/changes/projects/:project_id/research/reports/:kind/get.md) --- [API](https://skmtc.dev/bisibility/apis/bisibility-public-api.md) · [All operations](https://skmtc.dev/bisibility/apis/bisibility-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bisibility/apis/bisibility-public-api/revisions/a6e1ec0dec82?raw)