Get Session

GET /v1/traces/:sessionID

Returns the record for a single delivery session for the given sessionID: the session type, per-phase time metrics, events timelines, building polygon, 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	Unique identifier for the session as passed into the Doorstep SDK. Example: a7fcaea4-9a2c-3001-956d-e08b4560267f

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
sessionID	string	Unique identifier for the session as passed into the Doorstep SDK. Example: a7fcaea4-9a2c-3001-956d-e08b4560267f
address	string	Address for the given session.
sessionType	string	The type of delivery. One of: pickup, doorstep, threshold, curbside, or vehicle_handoff.
elevationMethod	string | null	The method of elevation. Either stairs or elevator, or null if no elevation POI.
metadata	object	Extra information passed to the Doorstep SDK, e.g. driverID, customerID, stopID
events	array	Timeline of the session's key events.
events[].type	string	The event type (e.g. parking, dropoff, entrance, elevation).
events[].timestamp	number	Epoch seconds when the event occurred.
timeMetrics	object	Time metrics for the given session, in seconds. See Time Metrics for fields walkingTime, inBuildingTime, and idleTime, along with parkingToEntrance and parkingToDropoff described below.
timeMetrics.parkingToEntrance	number | null	Time from parking to entrance, or null if either POI wasn't recorded.
timeMetrics.parkingToDropoff	number | null	Time from parking to dropoff, or null if either POI wasn't recorded.
driverActivity	array	Timeline of driver states.
driverActivity[].state	string	The driver's state for the segment. One of: Driving, Walking, or Idle.
driverActivity[].startTime	number	Segment start, in epoch seconds.
driverActivity[].endTime	number	Segment end, in epoch seconds.
detectedBuilding	object	The building detected at the session's location.
detectedBuilding.id	string	Unique identifier for the detected building.
detectedBuilding.geometry	object	GeoJSON Polygon geometry outlining the building.

Example Response

{
  "sessionID": "310454891",
  "address": "246 5th Ave, Suite 320, New York, NY 10001",
  "sessionType": "doorstep",
  "elevationMethod": "elevator",
  "metadata": {
    "driverID": "d_88213",
    "customerID": "c_40921",
    "stopID": "2ls846wu68jygh"
  },
  "events": [
    { "type": "parking", "timestamp": 1783448309 },
    { "type": "entrance", "timestamp": 1783448512 },
    { "type": "elevation", "timestamp": 1783448530 },
    { "type": "dropoff", "timestamp": 1783448549 },
  ],
  "timeMetrics": {
    "walkingTime": 285.40,
    "inBuildingTime": 285.36,
    "idleTime": 308.00,
    "parkingToEntrance": 203,
    "parkingToDropoff": 240
  },
  "driverActivity": [
    { "state": "Driving",  "startTime": 1783448220, "endTime": 1783448314 },
    { "state": "Walking", "startTime": 1783448314, "endTime": 1783448339 },
    { "state": "Idle", "startTime": 1783448339, "endTime": 1783448367 },
    { "state": "Walking", "startTime": 1783448367, "endTime": 1783448391 },
    { "state": "Idle", "startTime": 1783448391, "endTime": 1783448507 },
    { "state": "Walking", "startTime": 1783448507, "endTime": 1783448921 },
    { "state": "Driving",  "startTime": 1783448921, "endTime": 1783449548 }
  ],
  "detectedBuilding": {
    "id": "6836551c1692f0hbj",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-73.988012, 40.748812],
          [-73.987965, 40.748812],
          [-73.987965, 40.748856],
          [-73.988012, 40.748856],
          [-73.988012, 40.748812]
        ]
      ]
    }
  }
}

401

The API key is missing or invalid.

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

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