Get Session

GET /v1/traces/:sessionID

Returns the full analytics record for a single delivery session for the given sessionID: the delivery type, elevation method, per-phase time metrics, point-of-interest timestamps, and the driver's activity timeline.

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

Request

Path Parameters

Parameter	Type	Required?	Description
sessionID	string	Yes	The client-defined delivery identifier provided to the Doorstep SDK when recording the delivery.

Example Request

curl "https://api.core.doorstep.ai/v1/traces/310454891" \
  -H "Authorization: Bearer $API_KEY"

Response

200

The full analytics record for the requested session.

Response Body

Field	Type	Description
id	string	Unique delivery/session identifier.
address	string	Delivery address for the building.
sessionType	string	Delivery type, based on where the driver marked drop-off. One of: doorstep, threshold, curbside, vehicle_handoff.
elevationMethod	string | null	How the driver changed floors this session. One of: elevator, stairs, or null if no floor change was detected.
timeMetrics	object	Per-phase durations for the session, in seconds.
timeMetrics.walkingTime	number	Round-trip total on-foot time (can exceed the one-way park → drop-off time).
timeMetrics.inBuildingTime	number	Time spent inside the building.
timeMetrics.idleTime	number	Time the driver spent idle.
timeMetrics.parkingToEntrance	number	Time from the parking POI to the entrance POI.
timeMetrics.parkingToDropoff	number	Time from the parking POI to the drop-off POI.
poiTimestamps	object	Epoch timestamps (seconds) marking when each key tracking event was hit.
poiTimestamps.parking	number	When the driver parked the vehicle.
poiTimestamps.entrance	number	When the driver reached the building entrance.
poiTimestamps.elevation	number	When the driver changed floors (see elevationMethod for elevator, stairs, or both). Present only when a floor change is detected.
poiTimestamps.dropoff	number	When the package was marked as dropped off.
driverActivity	array	Sequential timeline of driver states.
driverActivity[].state	string	The driver's state for the segment. One of: car (in/at the vehicle), walk (walking), idle (stationary).
driverActivity[].startTime	number	Segment start, in epoch seconds.
driverActivity[].endTime	number	Segment end, in epoch seconds.
driverActivity[].duration	number	Segment duration, in seconds.

Consecutive activity segments are contiguous (endTime of one equals startTime of the next) and their durations sum to the full tracked session span.

All time metrics and durations are in seconds. All POI and activity timestamps are in epoch seconds.

Example Response

{
  "id": "5fcb4afc-d2b1-4726-8d74-bd8da071a923",
  "address": "1240 3rd St NE #1006, Washington, DC 20002, USA",
  "sessionType": "doorstep",
  "elevationMethod": "elevator",
  "timeMetrics": {
    "walkingTime": 589.37,
    "inBuildingTime": 387.39,
    "idleTime": 177.00,
    "parkingToEntrance": 154.00,
    "parkingToDropoff": 381.53
  },
  "poiTimestamps": {
    "parking": 1780447114.346,
    "entrance": 1780447268.347,
    "elevation": 1780447312.133,
    "dropoff": 1780447495.871
  },
  "driverActivity": [
    { "state": "car",  "startTime": 1780447052, "endTime": 1780447119, "duration": 67 },
    { "state": "walk", "startTime": 1780447119, "endTime": 1780447151, "duration": 32 },
    { "state": "idle", "startTime": 1780447151, "endTime": 1780447289, "duration": 138 },
    { "state": "walk", "startTime": 1780447289, "endTime": 1780447446, "duration": 157 },
    { "state": "idle", "startTime": 1780447446, "endTime": 1780447526, "duration": 80 },
    { "state": "walk", "startTime": 1780447526, "endTime": 1780447579, "duration": 53 },
    { "state": "idle", "startTime": 1780447579, "endTime": 1780447650, "duration": 71 },
    { "state": "walk", "startTime": 1780447650, "endTime": 1780447796, "duration": 146 },
    { "state": "car",  "startTime": 1780447796, "endTime": 1780447981, "duration": 185 }
  ]
}

401

The API key is missing or invalid.

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

404

No session was found with the given sessionID.

{
  "status": 404,
  "code": "not_found",
  "message": "No session found with given sessionID"
}

500

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

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