---
title: "List locations"
method: GET
path: "/locations"
tags: ["Locations"]
---

# List locations

`GET /locations`

## Request

- Base URL: `https://api.ekho.com`
- URL: `https://api.ekho.com/locations`
- Auth: HTTP bearer

Returns a cursor-paginated list of the locations acting as pickup or last-leg delivery points in your program. Narrow to one with `id` or your own `external_id`, though sending both is a 400, or filter by `service`. The name and address on each are what a buyer sees at checkout.

## Query parameters

- `id` string: Ekho location id. Narrows the list to at most one.
- `external_id` string: Your own id for the location. Narrows the list to at most one.
- `service` 'pickup' | 'last_leg_delivery': Return only locations that perform this service.
- `limit` integer: Page size, 1 to 100.
- `starting_after` string: Return the page after this resource id (newest first).

## Response `200`

A page of locations.

- object
  - `data` Location[], required
    - `id` string, required
    - `external_id` string, nullable, required: Your own id for this location. Null when you have not set one.
    - `name` string, required
    - `email` string, nullable, required
    - `phone` string, nullable, required
    - `address` LocationAddress, required
      - `address_line_one` string, required
      - `address_line_two` string, nullable, required
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `lat` number, nullable, required
      - `lng` number, nullable, required
    - `services` string[], required: The services this location performs for your program.
    - `created_at` integer, required: When this location joined your program, in epoch milliseconds.
    - `updated_at` integer, required: When this location was last changed, in epoch milliseconds.
  - `has_more` boolean, required: True when another page follows the returned one.
  - `next_cursor` string, nullable, required: Pass as `starting_after` to fetch the next page; null when `has_more` is false.

## Other responses

- `400`: The request was malformed or failed validation. `errors` itemizes every field at fault, so one response names them all; the fields in the example stand in for this request's own.
- `401`: Authentication is missing or invalid.
- `403`: The token lacks the scope this endpoint requires, or the account behind it does not run a program and so has no locations.
- `429`: The rate limit has been exceeded.
- `500`: An unexpected error occurred.

## Changes

- **2026-09-18** `c4f268c2d91b`: 1 breaking, 1 warning, 2 info
  - removed the enum value `delivery` from the `query` request parameter `service`
  - added the new `last_leg_delivery` enum value to the `data/items/services/items/` response property for the response status `200`
  - added the new enum value `last_leg_delivery` to the `query` request parameter `service`
  - removed the `delivery` enum value from the `data/items/services/items/` response property for the response status `200`
- **2026-09-18** `78c545d96a34`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ekho/apis/ekho-api/changes/locations/get.md)

---

[API](https://skmtc.dev/ekho/apis/ekho-api.md) · [All operations](https://skmtc.dev/ekho/apis/ekho-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ekho/apis/ekho-api/revisions/efe485119dd7?raw)