# list_itineraries

Day-by-day trips of a guide, including archived ones.

`GET /v1/guides/{productId}/itineraries` · MCP tool `list_itineraries` · scope `read` · beta · since 2026-10-06.3

All itineraries in display order. Days come back exactly as stored: edit them and send them to set_itinerary_days. What buyers see is decided at publish: archived itineraries and ones with no spot, route or place stop buyers can open stay hidden. get_guide_readiness lists unarchived trips with no such stop.

## Path parameters

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

## Returns

200: ItineraryList.

- `productId` (string, required): The guide's id.
- `itineraries` (array of Itinerary, required): All the guide's itineraries in order, archived ones included.
  Fields of Itinerary: https://developers.sceniq.earth/fields/itinerary.md

## Examples

### The guide's trips in display order

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

MCP `tools/call`:

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

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "itineraries": [
    {
      "itineraryId": "ki7a2c4e6g8j0m2p4s6v8y0b2d4f6h8k",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Yellowstone over two days",
      "description": "Thermal colors, a night at Old Faithful and first light in Lamar Valley.",
      "body": "Book the inn ahead. Check road conditions and keep wildlife at a distance.",
      "coverMediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9",
      "travelMode": "car",
      "season": {
        "months": [
          6,
          7,
          8,
          9
        ],
        "note": "Check the park road status before setting out."
      },
      "startsAt": "Old Faithful",
      "endsAt": "Lamar Valley",
      "days": [
        {
          "title": "Thermal basins and the overlook",
          "note": "Wait for the steam to lift before the overlook.",
          "stops": [
            {
              "kind": "place",
              "facilityId": "k17d4f6g8h0j2k4k6z8x0c2v4b6n8m0q",
              "when": "morning"
            },
            {
              "kind": "route",
              "routeId": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
              "when": "morning"
            },
            {
              "kind": "spot",
              "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
              "when": "midday",
              "note": "See the colors from the platform, then walk the boardwalk."
            },
            {
              "kind": "travel",
              "mode": "car",
              "from": "Midway Geyser Basin",
              "to": "Old Faithful",
              "when": "afternoon"
            },
            {
              "kind": "place",
              "facilityId": "k17j9h5g1f7d3s9a5p1p7j3v9y5t1r7m",
              "when": "evening"
            }
          ],
          "overnight": {
            "facilityId": "k17j9h5g1f7d3s9a5p1p7j3v9y5t1r7m",
            "name": "Old Faithful Inn",
            "note": "Reserve before the trip."
          }
        },
        {
          "title": "First light in Lamar Valley",
          "stops": [
            {
              "kind": "travel",
              "mode": "car",
              "from": "Old Faithful",
              "to": "Lamar Valley",
              "when": "night"
            },
            {
              "kind": "spot",
              "spotKey": "01M3GYV6A0Y3SYC62RBPEA9S0C",
              "when": "sunrise"
            },
            {
              "kind": "note",
              "title": "Keep wildlife at a distance",
              "note": "Follow the park's current wildlife guidance."
            }
          ]
        }
      ],
      "order": 1024,
      "archived": false,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    }
  ]
}
```

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