# list_routes

Routes (hikes, approaches) with their spot and facility links.

`GET /v1/guides/{productId}/routes` · MCP tool `list_routes` · scope `read` · stable · since 2026-09-17

Every route with stats, transit notes, equipment, sources and the ordered spot and facility 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.
- `routes` (array of Route, required): Every route, by name.
  Fields of Route: https://developers.sceniq.earth/fields/route.md

## Examples

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

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

MCP `tools/call`:

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

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "routes": [
    {
      "routeId": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
      "name": "Fairy Falls trail to the Grand Prismatic overlook",
      "activity": "hike",
      "sacGrade": "Class 1",
      "gradeScale": "yds",
      "effortLabel": "Easy",
      "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."
        },
        {
          "mode": "plane",
          "note": "Yellowstone Airport (WYS) in West Yellowstone, 45 km by road, has flights from June to September."
        }
      ],
      "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"
      ],
      "extraProps": [
        {
          "label": "Dogs",
          "value": "Not allowed on park trails"
        }
      ],
      "track": {
        "coordinates": [
          [
            -110.8326,
            44.5156,
            2181
          ],
          [
            -110.8349,
            44.517,
            2182
          ],
          [
            -110.8372,
            44.5183,
            2183
          ],
          [
            -110.8391,
            44.519,
            2186
          ],
          [
            -110.8402,
            44.5196,
            2201
          ],
          [
            -110.8406,
            44.5199,
            2214
          ]
        ],
        "source": "gpx",
        "fileName": "fairy-falls-overlook-2026-09-14.gpx"
      },
      "status": null,
      "season": {
        "months": [
          4,
          5,
          6,
          7,
          8,
          9,
          10
        ],
        "closureNote": "Park roads close to cars from early November to mid April; the trailhead is then reached by snowcoach only.",
        "statusUrl": "https://www.nps.gov/yell/planyourvisit/conditions.htm"
      },
      "variants": [
        {
          "name": "On to Fairy Falls",
          "extraKm": 6.8,
          "extraMin": 120,
          "purpose": "A 60 m waterfall 3.4 km further along the same trail, quiet before 09:00."
        }
      ],
      "stages": [],
      "segments": [
        {
          "name": "Fountain Freight Road",
          "km": 1.1,
          "accessNote": "Flat gravel road over the Firehole River, closed to cars. Bikes allowed."
        },
        {
          "name": "Overlook spur",
          "km": 0.3,
          "accessNote": "Hikers only. The one climb of the route."
        }
      ],
      "shape": "out_and_back",
      "durationBasis": "round_trip",
      "ascentMin": null,
      "descentMin": null,
      "sourceGrade": "Easy",
      "figureSources": [
        {
          "field": "distanceKm",
          "kind": "sourced",
          "url": "https://www.nps.gov/places/000/grand-prismatic-spring.htm"
        },
        {
          "field": "gainM",
          "kind": "computed",
          "note": "From the GPX, smoothed"
        },
        {
          "field": "durationMin",
          "kind": "computed",
          "note": "Walking time without the stop on the platform"
        }
      ],
      "reviewNotes": "The NPS page gives no elevation gain; the figure comes from the GPX.",
      "factsCheckedOn": "2026-09-20",
      "reviewBy": "2027-04-01",
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000,
      "spots": [
        {
          "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
          "order": 1024,
          "quickest": false,
          "role": "required"
        }
      ],
      "facilities": [
        {
          "facilityId": "km7d4f6g8h0j2k4k6z8x0c2v4b6n8m0q",
          "order": 1024
        }
      ]
    },
    {
      "routeId": "kx7r4t6y8v0j2p4p6a8s0d2f4g6h8j0k",
      "name": "Inspiration Point from Tunnel View",
      "activity": "hike",
      "sacGrade": "Class 1",
      "gradeScale": "yds",
      "effortLabel": "Moderate",
      "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"
      ],
      "extraProps": [],
      "track": null,
      "status": null,
      "season": null,
      "variants": [],
      "stages": [],
      "segments": [],
      "shape": "out_and_back",
      "durationBasis": "round_trip",
      "ascentMin": null,
      "descentMin": null,
      "sourceGrade": null,
      "figureSources": [],
      "reviewNotes": null,
      "factsCheckedOn": null,
      "reviewBy": null,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000,
      "spots": [
        {
          "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
          "order": 1024,
          "quickest": false,
          "role": "optional"
        }
      ],
      "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_routes