Skip to main content
Routal

List routes of a plan

Returns every route in the plan, each containing its ordered list of stops, the assigned vehicle, total distance, total duration and estimated arrival times.

GET
/v2/plan/{id}/routes

Returns every route in the plan, each containing its ordered list of stops, the assigned vehicle, total distance, total duration and estimated arrival times.

Use this endpoint after POST /v2/plan/{id}/optimize to read the optimized assignment, or any time during execution to build a live dispatch / monitoring view.

Authorization

api_key
private_key<token>

The Routal API authenticates requests with an API key passed as the private_key query string parameter. Generate and rotate your keys from the Developer Settings section of your Routal workspace.Never ship API keys to a browser or mobile app — they must stay server-side.

In: query

Path Parameters

id*string

Plan ID

Match^[0-9a-f]{24}

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/plan/string/routes"
[
  {
    "id": "4f75d991ac359f8c4c79d762",
    "project_id": "4f75d991ac359f8c4c79d762",
    "plan_id": "4f75d991ac359f8c4c79d762",
    "vehicle_id": "4f75d991ac359f8c4c79d762",
    "external_id": "ROUTE-2026-05-21-MAD03",
    "start_location": {
      "location_id": "4f75d991ac359f8c4c79d762",
      "label": "Location label",
      "country": "Spain",
      "country_code": "ES",
      "state": "Catalonia",
      "city": "Barcelona",
      "street": "Calle de Pau Claris",
      "postal_code": "08302",
      "comments": "Location comments",
      "lat": 40.45,
      "lng": -3.68,
      "main_text": "Calle de Pau Claris 12",
      "secondary_text": "Barcelona, Catalonia, Spain"
    },
    "end_location": {
      "location_id": "4f75d991ac359f8c4c79d762",
      "label": "Location label",
      "country": "Spain",
      "country_code": "ES",
      "state": "Catalonia",
      "city": "Barcelona",
      "street": "Calle de Pau Claris",
      "postal_code": "08302",
      "comments": "Location comments",
      "lat": 40.45,
      "lng": -3.68,
      "main_text": "Calle de Pau Claris 12",
      "secondary_text": "Barcelona, Catalonia, Spain"
    },
    "label": "Eixample route — Refrigerated van 02",
    "phone": "+34612345678",
    "comments": "Load at 06:00 at dock 4. Depart 06:30.",
    "email": "carlos.lopez@example.com",
    "plate": "2596 KHO",
    "vehicle_model": "Transit Custom L2H2",
    "color": "#1E88E5",
    "brand": "Ford",
    "vehicle": {
      "fuel_type": "diesel",
      "consumption": 8,
      "break": {
        "start": 43200,
        "end": 54000,
        "duration": 2700
      }
    },
    "planned_track": "spxsBsdb|Lymo`qvAx@TKvAr@K",
    "is_locked": true,
    "geo_fences": [
      "4f75d991ac359f8c4c79d762"
    ],
    "time_window": [
      28800,
      61200
    ],
    "max_distance": 120000,
    "min_distance": 5000,
    "max_time": 28800,
    "min_time": 3600,
    "max_weight": 800,
    "max_volume": 8,
    "max_services": 40,
    "provides": [
      "refrigerated",
      "lift_gate"
    ],
    "order": 0,
    "start_date": "2026-05-29T14:55:24.509Z",
    "end_date": "2026-05-29T14:55:24.509Z",
    "estimated_end_time": "2026-05-29T14:55:24.509Z",
    "last_position": {
      "lat": 40.45,
      "lng": -3.68,
      "created_at": "2026-05-29T14:55:24.508Z",
      "orientation": 270
    },
    "planned_start_time": 23400,
    "planned_end_time": 50400,
    "custom_fields": {},
    "distance_traveled": 0,
    "tracing_percent": 0,
    "price_per_minute": 0.0035,
    "price_per_distance": 0.00045,
    "toll_price": 4.8,
    "toll_price_currency": "EUR",
    "status": "not_started",
    "created_by": "4f75d991ac359f8c4c79d762",
    "created_at": "2026-05-29T14:55:24.339Z",
    "updated_at": "2026-05-29T14:55:24.339Z",
    "deleted_at": "2026-05-29T14:55:24.339Z",
    "deleted": true,
    "stops": [
      {
        "id": "4f75d991ac359f8c4c79d762",
        "fixed_id": "1",
        "organization_id": "4f75d991ac359f8c4c79d762",
        "project_id": "4f75d991ac359f8c4c79d762",
        "plan_id": "4f75d991ac359f8c4c79d762",
        "type": "delivery",
        "route_id": "4f75d991ac359f8c4c79d762",
        "vehicle_id": "4f75d991ac359f8c4c79d762",
        "client_id": "4f75d991ac359f8c4c79d762",
        "client_external_id": "CUST-58291",
        "external_id": "ORD-2026-58291",
        "location": {
          "location_id": "4f75d991ac359f8c4c79d762",
          "label": "Location label",
          "country": "Spain",
          "country_code": "ES",
          "state": "Catalonia",
          "city": "Barcelona",
          "street": "Calle de Pau Claris",
          "postal_code": "08302",
          "comments": "Location comments",
          "lat": 40.45,
          "lng": -3.68,
          "main_text": "Calle de Pau Claris 12",
          "secondary_text": "Barcelona, Catalonia, Spain"
        },
        "location_details": "Local 2, junto a la entrada principal",
        "label": "Acme Pharmacy — Aragó branch",
        "comments": "Ring intercom 2B. Do not leave at reception.",
        "phone": "+34612345678",
        "email": "sarah.johnson@example.com",
        "url": "https://shop.example.com/orders/58291",
        "reference_person": "Sarah Johnson",
        "duration": 180,
        "requires": [
          "refrigerated",
          "fragile"
        ],
        "cluster": "eixample-norte",
        "reward": 5,
        "time_windows": [
          [
            28800,
            61200
          ]
        ],
        "volume": 0.12,
        "weight": 8.4,
        "max_delivery_time": 7200,
        "status": "pending",
        "plan_execution_date": "2026-05-29T14:55:24.491Z",
        "order": 0,
        "planned_arrival_time": 29500,
        "planned_departure_time": 30000,
        "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
        "estimated_departure_time": "2026-05-29T14:55:24.491Z",
        "pickup_id": "4f75d991ac359f8c4c79d762",
        "distance_to_previous_stop": 30000,
        "distance_to_next_stop": 20000,
        "optimization_warning": true,
        "chain_id": "order-58291",
        "chain_position": 1,
        "custom_fields": {
          "order_reference": "ORD-2026-58291",
          "parcel_count": 2,
          "cod_amount": 24.9
        },
        "tasks": [
          {
            "id": "4f75d991ac359f8c4c79d762",
            "stop_id": "4f75d991ac359f8c4c79d762",
            "label": "Deliver refrigerated parcel 1/2",
            "comments": "Keep cold chain. Weight 12.4 kg.",
            "barcode": "8410076472158",
            "status": "completed",
            "custom_fields": {
              "sku": "SKU-4582",
              "quantity": 2,
              "lot_number": "L-2026-038"
            },
            "created_by": "4f75d991ac359f8c4c79d762",
            "created_at": "2026-05-29T14:55:24.485Z",
            "updated_at": "2026-05-29T14:55:24.485Z",
            "deleted_at": "2026-05-29T14:55:24.485Z"
          }
        ],
        "reports": [
          {
            "id": "4f75d991ac359f8c4c79d762",
            "stop_id": "4f75d991ac359f8c4c79d762",
            "route_id": "4f75d991ac359f8c4c79d762",
            "project_id": "4f75d991ac359f8c4c79d762",
            "plan_id": "4f75d991ac359f8c4c79d762",
            "type": "service_report_completed",
            "comments": "Customer not present. Notice left in the mailbox.",
            "images": [
              {
                "id": "4f75d991ac359f8c4c79d762",
                "url": "https://api.routal.com"
              }
            ],
            "signature": {
              "id": "4f75d991ac359f8c4c79d762",
              "url": "https://api.routal.com"
            },
            "tasks": [
              {
                "task_id": "4f75d991ac359f8c4c79d762",
                "status": "completed",
                "comments": "Parcel delivered in perfect condition.",
                "custom_fields": {
                  "sku": "SKU-4582",
                  "quantity": 2,
                  "lot_number": "L-2026-038"
                }
              }
            ],
            "cancel_reason": "nobody",
            "location": {
              "location_id": "4f75d991ac359f8c4c79d762",
              "label": "Location label",
              "country": "Spain",
              "country_code": "ES",
              "state": "Catalonia",
              "city": "Barcelona",
              "street": "Calle de Pau Claris",
              "postal_code": "08302",
              "comments": "Location comments",
              "lat": 40.45,
              "lng": -3.68,
              "main_text": "Calle de Pau Claris 12",
              "secondary_text": "Barcelona, Catalonia, Spain"
            },
            "time_in_stop": 180,
            "custom_fields": {
              "delivered_to": "neighbor 2A",
              "cod_collected": 24.9,
              "photo_count": 2
            },
            "created_at": "2026-05-29T14:55:24.486Z"
          }
        ],
        "report_attempts": 2,
        "survey": {
          "stop_id": "4f75d991ac359f8c4c79d762",
          "route_id": "4f75d991ac359f8c4c79d762",
          "rating": 1,
          "rating_tag": "time",
          "comments": "The delivery was very professional and punctual.",
          "created_at": "2026-05-29T14:55:24.489Z",
          "updated_at": "2026-05-29T14:55:24.489Z"
        },
        "pin": "4729",
        "customer_text_field": "Leave at reception if I'm not home.",
        "supervisors": [
          "4f75d991ac359f8c4c79d762"
        ],
        "location_validation_sent": false,
        "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
        "location_validated": false,
        "location_validated_at": "2026-05-29T14:55:24.500Z",
        "created_by": "4f75d991ac359f8c4c79d762",
        "created_at": "2026-05-29T14:55:24.339Z",
        "updated_at": "2026-05-29T14:55:24.339Z",
        "deleted_at": "2026-05-29T14:55:24.339Z",
        "deleted": true,
        "pickup": {
          "id": "4f75d991ac359f8c4c79d762",
          "fixed_id": "1",
          "organization_id": "4f75d991ac359f8c4c79d762",
          "project_id": "4f75d991ac359f8c4c79d762",
          "plan_id": "4f75d991ac359f8c4c79d762",
          "type": "delivery",
          "route_id": "4f75d991ac359f8c4c79d762",
          "vehicle_id": "4f75d991ac359f8c4c79d762",
          "client_id": "4f75d991ac359f8c4c79d762",
          "client_external_id": "CUST-58291",
          "external_id": "ORD-2026-58291",
          "location": {
            "location_id": "4f75d991ac359f8c4c79d762",
            "label": "Location label",
            "country": "Spain",
            "country_code": "ES",
            "state": "Catalonia",
            "city": "Barcelona",
            "street": "Calle de Pau Claris",
            "postal_code": "08302",
            "comments": "Location comments",
            "lat": 40.45,
            "lng": -3.68,
            "main_text": "Calle de Pau Claris 12",
            "secondary_text": "Barcelona, Catalonia, Spain"
          },
          "location_details": "Local 2, junto a la entrada principal",
          "label": "Acme Pharmacy — Aragó branch",
          "comments": "Ring intercom 2B. Do not leave at reception.",
          "phone": "+34612345678",
          "email": "sarah.johnson@example.com",
          "url": "https://shop.example.com/orders/58291",
          "reference_person": "Sarah Johnson",
          "duration": 180,
          "requires": [
            "refrigerated",
            "fragile"
          ],
          "cluster": "eixample-norte",
          "reward": 5,
          "time_windows": [
            [
              28800,
              61200
            ]
          ],
          "volume": 0.12,
          "weight": 8.4,
          "max_delivery_time": 7200,
          "status": "pending",
          "plan_execution_date": "2026-05-29T14:55:24.491Z",
          "order": 0,
          "planned_arrival_time": 29500,
          "planned_departure_time": 30000,
          "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
          "estimated_departure_time": "2026-05-29T14:55:24.491Z",
          "pickup_id": "4f75d991ac359f8c4c79d762",
          "distance_to_previous_stop": 30000,
          "distance_to_next_stop": 20000,
          "optimization_warning": true,
          "chain_id": "order-58291",
          "chain_position": 1,
          "custom_fields": {
            "order_reference": "ORD-2026-58291",
            "parcel_count": 2,
            "cod_amount": 24.9
          },
          "tasks": [
            {
              "id": "4f75d991ac359f8c4c79d762",
              "stop_id": "4f75d991ac359f8c4c79d762",
              "label": "Deliver refrigerated parcel 1/2",
              "comments": "Keep cold chain. Weight 12.4 kg.",
              "barcode": "8410076472158",
              "status": "completed",
              "custom_fields": {
                "sku": "SKU-4582",
                "quantity": 2,
                "lot_number": "L-2026-038"
              },
              "created_by": "4f75d991ac359f8c4c79d762",
              "created_at": "2026-05-29T14:55:24.485Z",
              "updated_at": "2026-05-29T14:55:24.485Z",
              "deleted_at": "2026-05-29T14:55:24.485Z"
            }
          ],
          "reports": [
            {
              "id": "4f75d991ac359f8c4c79d762",
              "stop_id": "4f75d991ac359f8c4c79d762",
              "route_id": "4f75d991ac359f8c4c79d762",
              "project_id": "4f75d991ac359f8c4c79d762",
              "plan_id": "4f75d991ac359f8c4c79d762",
              "type": "service_report_completed",
              "comments": "Customer not present. Notice left in the mailbox.",
              "images": [
                {
                  "id": "4f75d991ac359f8c4c79d762",
                  "url": "https://api.routal.com"
                }
              ],
              "signature": {
                "id": "4f75d991ac359f8c4c79d762",
                "url": "https://api.routal.com"
              },
              "tasks": [
                {
                  "task_id": "4f75d991ac359f8c4c79d762",
                  "status": "completed",
                  "comments": "Parcel delivered in perfect condition.",
                  "custom_fields": {
                    "sku": "SKU-4582",
                    "quantity": 2,
                    "lot_number": "L-2026-038"
                  }
                }
              ],
              "cancel_reason": "nobody",
              "location": {
                "location_id": "4f75d991ac359f8c4c79d762",
                "label": "Location label",
                "country": "Spain",
                "country_code": "ES",
                "state": "Catalonia",
                "city": "Barcelona",
                "street": "Calle de Pau Claris",
                "postal_code": "08302",
                "comments": "Location comments",
                "lat": 40.45,
                "lng": -3.68,
                "main_text": "Calle de Pau Claris 12",
                "secondary_text": "Barcelona, Catalonia, Spain"
              },
              "time_in_stop": 180,
              "custom_fields": {
                "delivered_to": "neighbor 2A",
                "cod_collected": 24.9,
                "photo_count": 2
              },
              "created_at": "2026-05-29T14:55:24.486Z"
            }
          ],
          "report_attempts": 2,
          "survey": {
            "stop_id": "4f75d991ac359f8c4c79d762",
            "route_id": "4f75d991ac359f8c4c79d762",
            "rating": 1,
            "rating_tag": "time",
            "comments": "The delivery was very professional and punctual.",
            "created_at": "2026-05-29T14:55:24.489Z",
            "updated_at": "2026-05-29T14:55:24.489Z"
          },
          "pin": "4729",
          "customer_text_field": "Leave at reception if I'm not home.",
          "supervisors": [
            "4f75d991ac359f8c4c79d762"
          ],
          "location_validation_sent": false,
          "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
          "location_validated": false,
          "location_validated_at": "2026-05-29T14:55:24.500Z",
          "created_by": "4f75d991ac359f8c4c79d762",
          "created_at": "2026-05-29T14:55:24.339Z",
          "updated_at": "2026-05-29T14:55:24.339Z",
          "deleted_at": "2026-05-29T14:55:24.339Z",
          "deleted": true
        }
      }
    ],
    "break_stop": {
      "is_completed": false,
      "order": 2,
      "planned_start_time": 20000,
      "planned_end_time": 30000,
      "real_start_time": 20000,
      "real_end_time": 30000
    }
  }
]
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
Empty