> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ranked.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Keywords

> Get keyword positions across Desktop, Mobile, AI Mode, and Maps

Returns tracked keywords with current positions across all search channels, net position change, and metadata.

### Path parameters

<ParamField path="projectId" type="string" required>
  Project UUID
</ParamField>

### Query parameters

<ParamField query="limit" type="number" default="50">
  Maximum keywords to return (max: 1000)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of keywords to skip
</ParamField>

<ParamField query="device" type="string" default="all">
  Filter by device: `all`, `desktop`, or `mobile`
</ParamField>

<ParamField query="date_from" type="string">
  Start date for position change calculation (ISO 8601, e.g., `2026-04-01`)
</ParamField>

<ParamField query="date_to" type="string">
  End date for position change calculation (ISO 8601)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.ranked.ai/api/v1/projects/{projectId}/rankings/keywords?limit=10" \
    -H "Authorization: Bearer rk_live_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "0e982fa1-a846-4e61-98ba-8811fafe892c",
        "keyword": "tree care services sioux city",
        "location": "Sioux City, Iowa, United States",
        "location_code": 1016030,
        "target_url": "https://siouxcitytreeco.com",
        "device": "desktop",
        "language_code": "en",
        "desktop_position": 8,
        "mobile_position": 3,
        "ai_mode_position": 3,
        "maps_position": 3,
        "desktop_url": "https://siouxcitytreeco.com/",
        "mobile_url": "https://siouxcitytreeco.com/",
        "ai_mode_url": "https://siouxcitytreeco.com/",
        "maps_url": "https://siouxcitytreeco.com/",
        "featured_snippet": false,
        "local_pack_position": null,
        "monthly_search_volume": null,
        "net_change": 93,
        "tags": [],
        "last_checked": "2026-05-16T00:10:17.701+00:00",
        "created_at": "2026-03-14T18:24:05.660Z"
      }
    ],
    "meta": {
      "pagination": {
        "total": 20,
        "limit": 10,
        "offset": 0,
        "has_more": true
      }
    }
  }
  ```
</ResponseExample>

### Response fields

| Field                   | Type           | Description                                                       |
| ----------------------- | -------------- | ----------------------------------------------------------------- |
| `desktop_position`      | number or null | Current Google Desktop rank                                       |
| `mobile_position`       | number or null | Current Google Mobile rank                                        |
| `ai_mode_position`      | number or null | Current Google AI Mode rank                                       |
| `maps_position`         | number or null | Current Google Maps rank                                          |
| `net_change`            | number         | Sum of position changes across all channels. Positive = improved. |
| `featured_snippet`      | boolean        | Whether the keyword has a featured snippet                        |
| `monthly_search_volume` | number or null | Estimated monthly search volume                                   |
| `last_checked`          | string         | When positions were last scanned                                  |