REST API & Webhooks
Keywords & Search Console API
Programmatically retrieve live Google Search Console query rankings, position deltas, and movement classifications.
The Keywords API provides programmatic access to verified Google Search Console query performance, historical rank tracking, and movement trends.
List Query Rankings
Retrieve verified query performance and position deltas for a connected site.
GET /api/v1/keywordsHeaders
Authorization: Bearer hub_live_YOUR_API_KEYQuery Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
site_id | string (UUID) | No | — | Filter rankings to a specific project site. |
status | string | No | — | Filter by classification: climbing, dropping, stable, new, lost. |
query | string | No | — | Substring search on target search queries. |
limit | integer | No | 20 | Max results per page (1 to 100). |
cursor | string | No | — | Opaque pagination cursor for subsequent batches. |
Response (200 OK)
{
"data": [
{
"id": "01j7xa1b2c3d4e5f6g7h8",
"site_id": "8f3b2c1a-5d4e-4f3a-9b8c-7d6e5f4a3b2c",
"query": "ai technical seo audit",
"page_path": "/services/technical-seo",
"current_position": 3.4,
"previous_position": 7.1,
"position_delta": 3.7,
"impressions": 1420,
"clicks": 112,
"ctr": 0.0788,
"ranking_status": "climbing",
"period": {
"start": "2026-09-01",
"end": "2026-09-14"
},
"recorded_at": "2026-09-14T12:00:00.000Z"
}
],
"meta": {
"per_page": 20,
"has_next": false,
"total_in_batch": 1
},
"links": {
"self": "https://hubseo.dev/api/v1/keywords?limit=20"
}
}For rows with ranking_status: "lost", current_position is null: the query no longer has a measured position. previous_position is null when there is no earlier measurement.
Zero-Mock Invariant
Ranking telemetry is derived directly from live Google Search Console API synchronization batches. If a site does not have active GSC search traffic for a query, it will never emit simulated or synthetic data.