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 geometry object (as a JSON string) to spatially filter sessions by dropoff location. 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. The slug is derived from the Census CBSA MSA name: lowercase, spaces replaced with underscores, first city and first state only. Example: new_york_ny, los_angeles_ca, chicago_il

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
}

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"
}