# list_spots

All spots of a guide in editor order.

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

Includes archived spots (flagged). Each spot carries its spotKey, which chapters and routes reference.

## 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.
- `spots` (array of Spot, required): Every spot in editor order, archived ones included.
  Fields of Spot: https://developers.sceniq.earth/fields/spot.md

## Examples

### List the spots of a guide

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

MCP `tools/call`:

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

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "spots": [
    {
      "spotId": "k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c",
      "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "title": "Grand Prismatic Spring",
      "kicker": "Yellowstone, Midway Geyser Basin",
      "lat": 44.5251,
      "lon": -110.8382,
      "mapsUrl": "https://maps.apple.com/?ll=44.5251,-110.8382&q=Grand%20Prismatic%20Spring",
      "shortDescription": "The largest hot spring in the United States. See it from the boardwalk, then from the overlook above the Fairy Falls trail.",
      "longDescription": "Grand Prismatic is about 110 meters across, and from the boardwalk you mostly see steam and the orange mats that run off toward the Firehole River. For the colors, park at the Fairy Falls trailhead and follow the trail to the signed spur for the overlook: about 1 km each way, 20 minutes up. The whole spring opens up below the platform. Come on a warm, dry morning; on a cold day the steam hides everything.",
      "color": null,
      "cardOrientation": "landscape",
      "customValues": {
        "best_time": "morning",
        "crowds": "packed",
        "photo_notes": "From the overlook a 24 mm lens takes in the whole spring. On the boardwalk, shoot the runoff channels instead of the steam."
      },
      "tripFacts": {
        "elevationM": 2176,
        "elevationRefersTo": "ground",
        "busyness": 5,
        "bestSeason": "Late May to September"
      },
      "arrival": {
        "byCar": {
          "directions": "Grand Loop Road, 11 km north of Old Faithful. Midway Geyser Basin lot.",
          "parking": "Midway Geyser Basin lot, full by 10:00 in summer. Fairy Falls trailhead lot 1.6 km south.",
          "walkToSpotMin": 10
        },
        "byTrainBus": {
          "none": true
        },
        "bestTime": "Mid morning on a warm, dry day: cold air turns the steam into fog that hides the colors."
      },
      "mapLinks": [],
      "imagesEnabled": true,
      "customPropsEnabled": true,
      "archived": false,
      "ref": null,
      "accessMode": "short_walk",
      "pinLabel": null,
      "pins": [
        {
          "kind": "viewpoint",
          "label": "Grand Prismatic Overlook",
          "lat": 44.5192,
          "lon": -110.8391,
          "note": "Platform on a spur of the Fairy Falls trail, about 1 km from the trailhead lot."
        },
        {
          "kind": "parking",
          "label": "Fairy Falls trailhead lot",
          "lat": 44.5153,
          "lon": -110.8325,
          "note": "For the overlook. Full by mid morning in July and August."
        }
      ],
      "links": [
        {
          "kind": "official",
          "url": "https://www.nps.gov/places/000/grand-prismatic-spring.htm",
          "label": "Grand Prismatic Spring (NPS)"
        },
        {
          "kind": "status",
          "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
          "label": "Park road status"
        }
      ],
      "status": null,
      "fees": [],
      "schedule": null,
      "features": [],
      "restrictions": [
        {
          "kind": "no_drone",
          "label": "No drones in the park",
          "note": "Drones are banned in all US national parks."
        },
        {
          "kind": "no_entry",
          "label": "Stay on the boardwalk",
          "note": "The crust around the spring is thin, and the water under it is scalding."
        }
      ],
      "events": [],
      "food": null,
      "areaId": "area_01m3gvdap06m6mx2kp4t553d6g",
      "timeZone": "America/Denver",
      "timeZoneManual": false,
      "customNotes": {
        "crowds": "Quieter before 9:00 and after 18:00"
      },
      "sources": [
        {
          "url": "https://www.nps.gov/places/000/grand-prismatic-spring.htm",
          "kind": "page",
          "capturedOn": "2026-09-20",
          "supports": [
            "arrival",
            "restrictions"
          ]
        }
      ],
      "reviewNotes": "The overlook pin comes from your GPX of 18 September; please confirm it. The trail distance is from the NPS page (0.6 mi each way).",
      "factsCheckedOn": "2026-09-20",
      "reviewBy": "2027-04-01",
      "siteChange": null,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    },
    {
      "spotId": "k17bc3xz8h6f4d2s0q9w7e5r3t1y2v4j",
      "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "title": "Tunnel View",
      "kicker": "Yosemite Valley",
      "lat": 37.7156,
      "lon": -119.677,
      "mapsUrl": "https://www.google.com/maps/search/?api=1&query=37.7156,-119.677",
      "shortDescription": "El Capitan, Half Dome and Bridalveil Fall in one frame, at the east end of the Wawona Tunnel.",
      "longDescription": null,
      "color": null,
      "cardOrientation": "landscape",
      "customValues": {
        "best_time": "sunset",
        "crowds": "busy"
      },
      "tripFacts": null,
      "arrival": {
        "byCar": {
          "directions": "Wawona Road (Highway 41), at the east end of the Wawona Tunnel.",
          "parking": "Lots on both sides of the road; the north lot fills first at sunset.",
          "walkToSpotMin": 1
        },
        "bestTime": "The hour before sunset, or when a winter storm starts to clear."
      },
      "mapLinks": [],
      "imagesEnabled": true,
      "customPropsEnabled": true,
      "archived": false,
      "ref": "yose-tunnel-view",
      "accessMode": "drive_up",
      "pinLabel": null,
      "pins": [],
      "links": [],
      "status": null,
      "fees": [],
      "schedule": null,
      "features": [],
      "restrictions": [],
      "events": [],
      "food": null,
      "areaId": "area_01m3gvgcb04pf38p66vz544w1b",
      "timeZone": "America/Los_Angeles",
      "timeZoneManual": false,
      "customNotes": {},
      "sources": [],
      "reviewNotes": null,
      "factsCheckedOn": null,
      "reviewBy": null,
      "siteChange": null,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    },
    {
      "spotId": "k17rwzt006kbqwjbs5jrqk4jjf5srec9",
      "spotKey": "01M3GYV6A0Y3SYC62RBPEA9S0C",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "title": "Lamar Valley",
      "kicker": "Yellowstone, northeast entrance road",
      "lat": null,
      "lon": null,
      "mapsUrl": null,
      "shortDescription": null,
      "longDescription": null,
      "color": null,
      "cardOrientation": "landscape",
      "customValues": {},
      "tripFacts": null,
      "arrival": null,
      "mapLinks": [],
      "imagesEnabled": true,
      "customPropsEnabled": true,
      "archived": false,
      "ref": null,
      "accessMode": null,
      "pinLabel": null,
      "pins": [],
      "links": [],
      "status": null,
      "fees": [],
      "schedule": null,
      "features": [],
      "restrictions": [],
      "events": [],
      "food": null,
      "areaId": null,
      "timeZone": null,
      "timeZoneManual": false,
      "customNotes": {},
      "sources": [],
      "reviewNotes": "No pin yet: the creator is sending the pullout they use for the bison herds.",
      "factsCheckedOn": null,
      "reviewBy": null,
      "siteChange": null,
      "createdAt": 1789895640000,
      "updatedAt": 1789895640000
    }
  ]
}
```

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