{"openapi":"3.0.3","info":{"title":"BasecampSEO API","version":"1.0.0","description":"Read-only access to your Google Search Console performance and indexing data.\n\n**Authentication.** Send an API key as `Authorization: Bearer bcs_live_...`. Create one in Settings → API. Keys act as the person who created them and can never see more than that person can.\n\n**Data freshness.** Search Console reports with a ~2 day lag, so every range defaults to ending two days ago. The last 16 months are fetched live from Google on a cache miss; older data comes from our own archive and is coarser.\n\n**Rate limits.** Every response carries `X-RateLimit-*`. A separate, smaller budget governs live Search Console calls. Cached responses do not consume it, which is why repeating a question is nearly free and varying it is not."},"servers":[{"url":"https://api.basecampseo.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Properties"},{"name":"Performance"},{"name":"Indexing"},{"name":"Context"},{"name":"Account"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"bcs_live_..."}},"schemas":{"Filter":{"type":"object","properties":{"dimension":{"type":"string","enum":["query","page","country","device","brand","page_group"]},"operator":{"type":"string","enum":["contains","equals","regex","not_contains","not_equals","not_regex","is","is_not"]},"value":{"type":"string","minLength":1,"maxLength":200}},"required":["dimension","operator","value"],"additionalProperties":false},"CreateApiKey":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","items":{"type":"string","enum":["properties:read","performance:read","indexing:read","config:read"]},"minItems":1,"default":["properties:read","performance:read","indexing:read","config:read"]},"team_id":{"type":"string","format":"uuid","nullable":true},"expires_in_days":{"type":"integer","minimum":1,"maximum":3650,"nullable":true}},"required":["name"],"additionalProperties":false},"Meta":{"type":"object","description":"Present on every response. `source` and `stale_reason` say whether the numbers came from Google or from our archive. Do not present archive figures as current.","properties":{"request_id":{"type":"string"},"property_id":{"type":"string"},"date_range":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"preset":{"type":"string"}}},"row_count":{"type":"integer","nullable":true},"limit":{"type":"integer","nullable":true},"total":{"type":"integer","nullable":true},"truncated_by":{"type":"string","nullable":true},"source":{"type":"string","nullable":true,"enum":["live","stored","hybrid"]},"stale_reason":{"type":"string","nullable":true},"cache":{"type":"string","enum":["hit","miss","bypass"]},"notes":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"docs_url":{"type":"string"}}}}}}},"paths":{"/v1/me":{"get":{"tags":["Account"],"summary":"This key, its scopes, and all four usage ceilings","responses":{"200":{"description":"Key identity and live quota counters"}}}},"/v1/properties":{"get":{"tags":["Properties"],"summary":"List every property this key can read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"include_archived","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Properties, alphabetical"}}}},"/v1/properties/{id}":{"get":{"tags":["Properties"],"summary":"One property, with its data window and connection health","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Property metadata"}}}},"/v1/properties/{id}/summary":{"get":{"tags":["Performance"],"summary":"Clicks, impressions, CTR and average position for a range","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","description":"URL-encoded JSON array of {dimension, operator, value}. The virtual dimensions \"brand\" and \"page_group\" expand from the property's configured brand terms and page groups. Any filter forces a live Search Console query.","schema":{"type":"string"}},{"name":"compare","in":"query","schema":{"type":"string","enum":["none","previous_period"],"default":"none"}}],"responses":{"200":{"description":"Totals, and the previous period when requested"}}}},"/v1/properties/{id}/timeseries":{"get":{"tags":["Performance"],"summary":"Daily metrics across a range","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","description":"URL-encoded JSON array of {dimension, operator, value}. The virtual dimensions \"brand\" and \"page_group\" expand from the property's configured brand terms and page groups. Any filter forces a live Search Console query.","schema":{"type":"string"}}],"responses":{"200":{"description":"One row per day"}}}},"/v1/properties/{id}/queries":{"get":{"tags":["Performance"],"summary":"Top search queries","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","description":"URL-encoded JSON array of {dimension, operator, value}. The virtual dimensions \"brand\" and \"page_group\" expand from the property's configured brand terms and page groups. Any filter forces a live Search Console query.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}},{"name":"order_by","in":"query","schema":{"type":"string","default":"-clicks"}}],"responses":{"200":{"description":"Rows ordered as requested. Note meta.truncated_by: Search Console selects the top N BY CLICKS, so ordering by another metric re-sorts that sample rather than re-selecting.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"dimension":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":"number"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/v1/properties/{id}/pages":{"get":{"tags":["Performance"],"summary":"Top landing pages","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","description":"URL-encoded JSON array of {dimension, operator, value}. The virtual dimensions \"brand\" and \"page_group\" expand from the property's configured brand terms and page groups. Any filter forces a live Search Console query.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}},{"name":"order_by","in":"query","schema":{"type":"string","default":"-clicks"}}],"responses":{"200":{"description":"Rows ordered as requested. Note meta.truncated_by: Search Console selects the top N BY CLICKS, so ordering by another metric re-sorts that sample rather than re-selecting.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"dimension":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":"number"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/v1/properties/{id}/countries":{"get":{"tags":["Performance"],"summary":"Traffic by country","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","description":"URL-encoded JSON array of {dimension, operator, value}. The virtual dimensions \"brand\" and \"page_group\" expand from the property's configured brand terms and page groups. Any filter forces a live Search Console query.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}},{"name":"order_by","in":"query","schema":{"type":"string","default":"-clicks"}}],"responses":{"200":{"description":"Rows ordered as requested. Note meta.truncated_by: Search Console selects the top N BY CLICKS, so ordering by another metric re-sorts that sample rather than re-selecting.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"dimension":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":"number"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/v1/properties/{id}/devices":{"get":{"tags":["Performance"],"summary":"Traffic by device","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","description":"URL-encoded JSON array of {dimension, operator, value}. The virtual dimensions \"brand\" and \"page_group\" expand from the property's configured brand terms and page groups. Any filter forces a live Search Console query.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}},{"name":"order_by","in":"query","schema":{"type":"string","default":"-clicks"}}],"responses":{"200":{"description":"Rows ordered as requested. Note meta.truncated_by: Search Console selects the top N BY CLICKS, so ordering by another metric re-sorts that sample rather than re-selecting.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"dimension":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":"number"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/v1/properties/{id}/movers/queries":{"get":{"tags":["Performance"],"summary":"Queries that gained and lost the most clicks vs the previous period","description":"Cannot be filtered. The underlying comparison returns nothing when filters are present, which is indistinguishable from \"nothing moved\", so the parameter is rejected instead. To compare within a segment, call /queries twice with explicit ranges.","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Gainers and losers"}}}},"/v1/properties/{id}/movers/pages":{"get":{"tags":["Performance"],"summary":"Pages that gained and lost the most clicks vs the previous period","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"date_range","in":"query","description":"Relative range, anchored two days ago (Search Console reports with a ~2 day lag). Defaults to last_28d.","schema":{"type":"string","default":"last_28d"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Gainers and losers"}}}},"/v1/properties/{id}/indexing":{"get":{"tags":["Indexing"],"summary":"Google indexing coverage for the property","description":"Stored inspection results refreshed daily, not live. A status of pending_discovery or pending_inspection means collection has not run yet, not that zero pages are indexed.","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","enum":[30,90,365],"default":90}},{"name":"include_trend","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Coverage totals, breakdown and sitemap groups"}}}},"/v1/properties/{id}/indexing/urls":{"get":{"tags":["Indexing"],"summary":"Individual URLs with their index status","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"bucket","in":"query","schema":{"type":"string","enum":["indexed","not_indexed","error","unknown"]}},{"name":"coverage_state","in":"query","schema":{"type":"string"}},{"name":"sitemap_path","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["importance","url","last_crawl_time","last_inspected_at"],"default":"importance"}},{"name":"dir","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"A page of URLs, with an exact total"}}}},"/v1/properties/{id}/brand-terms":{"get":{"tags":["Context"],"summary":"Brand terms configured for this property","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Brand terms"}}}},"/v1/properties/{id}/page-groups":{"get":{"tags":["Context"],"summary":"Page groups configured for this property","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Page groups"}}}},"/v1/properties/{id}/annotations":{"get":{"tags":["Context"],"summary":"Dated notes marking launches, migrations and algorithm updates","parameters":[{"name":"id","in":"path","required":true,"description":"Property UUID, bare domain (\"example.com\"), full Search Console property (\"sc-domain:example.com\"), or slug.","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Annotations"}}}}},"x-scopes":["properties:read","performance:read","indexing:read","config:read"]}