# List Keywords

Source: https://www.ranked.ai/developers/api-reference/keywords/list

`GET https://app.ranked.ai/api/v1/projects/{projectId}/rankings/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

- `projectId` (path, string, required): Project UUID

### Query parameters

- `limit` (query, number, default 50): Maximum keywords to return (max: 1000)

- `offset` (query, number, default 0): Number of keywords to skip

- `device` (query, string, default all): Filter by device: `all`, `desktop`, or `mobile`

- `date_from` (query, string): Start date for position change calculation (ISO 8601, e.g., `2026-04-01`)

- `date_to` (query, string): End date for position change calculation (ISO 8601)

**Request**

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

**Response**

```json 200
{
  "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
    }
  }
}
```

### 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 |