# list_hikes

Hikes with their spot and place links.

`GET /v1/guides/{productId}/hikes` · MCP tool `list_hikes` · scope `read` · beta · since 2026-10-06.8

Every hike of the guide by name, with its difficulty and grade, figures, transit notes, equipment, sources, line and the ordered spot and place links.

## Path parameters

- `productId` (string, required): Id of the guide (a product of type map). From list_guides or create_guide.

## Returns

200.

- `productId` (string, required): The guide's id.
- `hikes` (array of Hike, required): Every hike, by name.
  Fields of Hike: https://developers.sceniq.earth/fields/hike.md

## Examples

### Every hike of a guide with its spot and place links

```bash
curl "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/hikes" \
  -H "Authorization: Bearer $SCENIQ_API_KEY"
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_hikes",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2"
    }
  }
}
```

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "hikes": [
    {
      "hikeId": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
      "name": "Fairy Falls trail to the Grand Prismatic overlook",
      "difficulty": "easy",
      "grade": null,
      "durationMin": 45,
      "gainM": 35,
      "descentM": 35,
      "distanceKm": 2,
      "start": "Fairy Falls trailhead on the Grand Loop Road, 1.6 km south of Midway Geyser Basin",
      "startMapsUrl": "https://maps.apple.com/?ll=44.5156,-110.8326&q=Fairy%20Falls%20Trailhead",
      "transit": [
        {
          "mode": "car",
          "note": "Park at the Fairy Falls trailhead lot, which fills by 09:30 in July and August. No public transport runs in the park."
        }
      ],
      "description": "A flat kilometer on the old Fountain Freight Road, then a short climb to a platform above Grand Prismatic Spring. Go mid morning on a warm day, once the steam has lifted.",
      "equipment": [
        "Bear spray",
        "A warm layer for the morning"
      ],
      "sources": [
        "https://www.nps.gov/places/000/grand-prismatic-spring.htm",
        "GPX recorded by Mara Lindgren on 2026-09-14"
      ],
      "track": null,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000,
      "spots": [
        {
          "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
          "order": 1024
        }
      ],
      "facilities": [
        {
          "facilityId": "k17d4f6g8h0j2k4k6z8x0c2v4b6n8m0q",
          "order": 1024
        }
      ]
    },
    {
      "hikeId": "kx7r4t6y8v0j2p4p6a8s0d2f4g6h8j0k",
      "name": "Inspiration Point from Tunnel View",
      "difficulty": "moderate",
      "grade": "Class 1",
      "durationMin": 120,
      "gainM": 305,
      "descentM": 305,
      "distanceKm": 4.2,
      "start": "Pohono Trail sign at the Tunnel View parking",
      "startMapsUrl": "https://www.google.com/maps/search/?api=1&query=37.7156,-119.677",
      "transit": [],
      "description": "Steep switchbacks up the Pohono Trail to a quieter, higher version of the Tunnel View frame. Most of the climb is in full sun.",
      "equipment": [
        "Two liters of water per person"
      ],
      "sources": [
        "GPX recorded by Mara Lindgren on 2026-06-11"
      ],
      "track": null,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000,
      "spots": [
        {
          "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
          "order": 1024
        }
      ],
      "facilities": []
    }
  ]
}
```

## Errors

- `invalid_argument` (400): A required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message).
- `unauthenticated` (401): The request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
- `invalid_api_key` (401): The key is unknown, revoked or expired.
- `forbidden` (403): The key belongs to a creator account that is no longer active.
- `not_found` (404): The id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
- `rate_limited` (429): Over a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
- `internal_error` (500): An unexpected failure. The message is hidden on purpose.

Reference: https://developers.sceniq.earth/reference/list_hikes