List Sessions

GET /v1/traces

Returns a list of sessions for your organization, ordered from most recent to oldest. Filter by delivery type, address, time window, or geographic area.

Requires an API key sent as a Bearer token in the Authorization header.

Request

Query Parameters

Parameter	Type	Required	Description
sessionType	string	Optional	Filter by delivery type. Allowed values: doorstep, threshold, curbside, vehicle_handoff, pickup
address	string	Optional	Filter sessions delivered to a specific address. Example: 123 Main St, San Francisco, CA 94105
from	number	Optional	Start of the time window in epoch seconds. Sessions with a timestamp ≥ from are included.
to	number	Optional	End of the time window in epoch seconds. Sessions with a timestamp ≤ to are included.
page	integer	Optional	Page number. Default: 1.
limit	integer	Optional	Sessions per page. Default: 50. Maximum: 200.
geometry	string	Optional	A GeoJSON Polygon or MultiPolygon (as a JSON string) to spatially filter sessions by dropoff location. Other GeoJSON types (Point, LineString, GeometryCollection, etc.) are not supported. Maximum area: 1,000,000 km². Example: {"type":"Polygon","coordinates":[[[-74.02,40.70],[-73.97,40.70],[-73.97,40.75],[-74.02,40.75],[-74.02,40.70]]]}
region	string	Optional	Filter by US metro area. Pass the full Census CBSA name, exactly as published. Example: New York-Newark-Jersey City, NY-NJ, Los Angeles-Long Beach-Anaheim, CA, Chicago-Naperville-Elgin, IL-IN See CBSA Regions for the full list of valid values.

Example Request

curl "https://api.core.doorstep.ai/v1/traces?from=1781500000&to=1781600000&limit=100" \
  -H "Authorization: Bearer $API_KEY"

Response

200

Paginated list of sessions.

Response Body

Field	Type	Description
sessions	array	Sessions for the current page.
sessions[].uuid	string	The session UUID. Can be used with Doorstep Atlas to visualize what happened during a delivery.
sessions[].sessionID	string | null	Unique identifier for the session as passed into the Doorstep SDK.
sessions[].address	string | null	Delivery address.
sessions[].sessionType	string | null	Delivery type. One of: doorstep, threshold, curbside, vehicle_handoff.
sessions[].timestamp	number	Epoch seconds when the session was recorded.
page	integer	The current page number.
limit	integer	The number of results per page.

Example Response

{
  "sessions": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sessionID": "310454891",
      "address": "123 Main St, San Francisco, CA 94105",
      "sessionType": "doorstep",
      "timestamp": 1781573400
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "sessionID": "310454892",
      "address": "456 Market St, San Francisco, CA 94105",
      "sessionType": "curbside",
      "timestamp": 1781573100
    }
  ],
  "page": 1,
  "limit": 50
}

400

The region parameter was not recognized. See CBSA Regions for the full list of valid values.

{
  "status": 400,
  "code": "bad_request",
  "message": "Unrecognized region: San Francisco, C"
}

The geometry parameter is malformed — invalid JSON, an unsupported geometry type (only Polygon and MultiPolygon are accepted), a ring with fewer than 3 points, non-numeric coordinates, a coordinate outside valid longitude/latitude range, or a ring that encloses no area.

{
  "status": 400,
  "code": "bad_request",
  "message": "Invalid geometry: each ring must have at least 3 points"
}

The geometry parameter covers too large an area — over 1,000,000 km². Use a smaller area, or split the request into multiple smaller geometries.

{
  "status": 400,
  "code": "bad_request",
  "message": "Geometry too large: covers approximately 2,437,003 km², max is 1,000,000 km². Use a smaller area."
}

401

The API key is missing or invalid.

{
  "status": 401,
  "code": "unauthorized",
  "message": "Token Invalid"
}

500

Something went wrong on our end. Try the request again later.

{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal Server Error"
}