--- updatedAt: 2026-06-09T09:13:41.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # Breadcrumbs Export GPS breadcrumb trails for employee shifts on a specific date. Breadcrumbs capture location movement while an employee is clocked in โ€” useful for field-service compliance, route verification, and enterprise audit workflows. The API uses an **async three-step flow**: request a report, poll until it is ready, then download a JSON file. ## Endpoints | Step | Method | Endpoint | Description | | :--- | :----- | :-------------------------------------------------- | :--------------------------------- | | 1 | POST | /time-clock/breadcrumbs/v1/report | Start report generation for a date | | 2 | GET | /time-clock/breadcrumbs/v1/report/{fileId} | Poll task status | | 3 | GET | /time-clock/breadcrumbs/v1/report/{fileId}/download | Download the JSON report | *** ## Overview * **Single-day export:** pass one `date` (`YYYY-MM-DD`). The report includes shift breadcrumbs for that calendar day across **all time clocks** in the company (company timezone). * **Async generation:** step 1 returns a `fileId` (UUID). A background worker builds the file and uploads it to storage. * **Poll then download:** call step 2 until `status` is `completed`, then call step 3 to stream the JSON. * **Shift-scoped data:** breadcrumbs are grouped per shift (`timeActivityId`) and user. Only shifts with breadcrumb data appear in the file. * **Prerequisite:** breadcrumbs must be **enabled** on at least one time clock in the company (Time Clock settings). > ๐Ÿ“˜ What are breadcrumbs? > > While an employee is clocked into a shift, Connecteam can record periodic GPS events โ€” **motion** readings, **geofence** enter/exit events, and **providerChange** events (network/GPS state changes). These are stored on the shift and exported in the report. > ๐Ÿ‘ Authenticated download > > **Always download through step 3** with your API key or OAuth token. The API validates that the `fileId` belongs to your company before streaming the file. *** ## Authentication * **API Key** (`X-API-KEY` header), or * **OAuth 2.0** with scope `time_clock.read` **Plan requirement:** Time Clock API (`timeClockApi`, Operations API category). *** ## Step 1 โ€” Generate Report `POST /time-clock/breadcrumbs/v1/report` ### Request Body | Field | Type | Required | Description | | :---- | :------------------ | :------- | :-------------------------------------------------- | | date | string (YYYY-MM-DD) | Yes | Calendar date to export. Must not be in the future. | ### Example Request ```bash curl --request POST \ --url https://api.connecteam.com/time-clock/breadcrumbs/v1/report \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "date": "2025-03-15" }' ``` ### Response ```json { "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "fileId": "550e8400-e29b-41d4-a716-446655440000" } } ``` Save `data.fileId` โ€” you need it for steps 2 and 3. *** ## Step 2 โ€” Poll Status `GET /time-clock/breadcrumbs/v1/report/{fileId}` ### Path Parameters | Parameter | Type | Required | Description | | :-------- | :------------ | :------- | :-------------------------------- | | fileId | string (UUID) | Yes | The `fileId` returned from step 1 | ### Task Status Values | Status | Meaning | | :------------ | :----------------------------------- | | `in_queue` | Task created; waiting for the worker | | `in_progress` | Report is being generated | | `completed` | File is ready โ€” proceed to step 3 | | `error` | Generation failed โ€” see `errorMsg` | ### Example Request ```bash curl --request GET \ --url https://api.connecteam.com/time-clock/breadcrumbs/v1/report/550e8400-e29b-41d4-a716-446655440000 \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Response (in progress) ```json { "requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "data": { "status": "in_progress", "errorMsg": null } } ``` ### Response (completed) ```json { "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "data": { "status": "completed", "errorMsg": null } } ``` Poll every few seconds until `status` is `completed` or `error`. *** ## Step 3 โ€” Download Report `GET /time-clock/breadcrumbs/v1/report/{fileId}/download` Streams the JSON file (`Content-Type: application/json`) with a `Content-Disposition: attachment` header. **Only available when status is `completed`.** ### Example Request ```bash curl --request GET \ --url https://api.connecteam.com/time-clock/breadcrumbs/v1/report/550e8400-e29b-41d4-a716-446655440000/download \ --header 'X-API-KEY: YOUR_API_KEY' \ --output breadcrumbs_2025-03-15.json ``` *** ## Report File Structure The downloaded JSON has this top-level shape: ```json { "breadcrumbsByActivities": [ { "timeClockId": 12345, "timeActivityId": "shift-abc123", "userId": 9170357, "breadcrumbs": [ { "timestamp": 1710504000, "receivedTimestamp": 1710504002, "type": "motion", "gps": { "altitude": 50.0, "latitude": 40.7128, "longitude": -74.0060, "speed": 2.5, "accuracy": 10.0, "altitudeAccuracy": 5.0, "latitudeAccuracy": null, "longitudeAccuracy": null } }, { "timestamp": 1710507600, "receivedTimestamp": 1710507601, "type": "geoFence", "action": "ENTER", "geoFenceId": "gf-site-001", "gps": { "altitude": 48.0, "latitude": 40.7130, "longitude": -74.0058, "speed": 0.0, "accuracy": 8.0 } } ] } ] } ``` ### Activity Fields | Field | Type | Description | | :------------- | :------ | :---------------------------------------------------- | | timeClockId | integer | Time clock the shift belongs to | | timeActivityId | string | Shift ID (same as shift `id` in time-activities APIs) | | userId | integer | Employee ID | | breadcrumbs | array | Ordered GPS events for this shift | ### Breadcrumb Event Fields | Field | Type | Description | | :---------------- | :------ | :---------------------------------------------------------------------------------------------- | | timestamp | integer | When the event was recorded on the device (Unix seconds) | | receivedTimestamp | integer | When Connecteam received the event (Unix seconds) | | type | string | `motion`, `geoFence`, or `providerChange` | | gps | object | Latitude, longitude, altitude, speed (m/s), accuracy (meters), and optional accuracy components | | action | string | (geoFence only) `ENTER` or `EXIT` | | geoFenceId | string | (geoFence only) Geofence identifier | | isNetworkEnabled | boolean | (providerChange only) Device network state | | isLocationEnabled | boolean | (providerChange only) OS location services state | | isGpsEnabled | boolean | (providerChange only) GPS hardware state | > ๐Ÿ“ Export notes > > * Activities with **no breadcrumbs** are omitted from the file. > * Internal fields (`age`, `lastLocationTrackingEvent`) are stripped from the export. > * Shifts are included when they have activity on the requested date (per company timezone day boundaries). *** ## Integration Example ```javascript const BASE = 'https://api.connecteam.com/time-clock/breadcrumbs/v1'; const API_KEY = 'YOUR_API_KEY'; const headers = { 'X-API-KEY': API_KEY, 'Content-Type': 'application/json' }; async function downloadBreadcrumbsReport(date) { // Step 1 โ€” start generation const createRes = await fetch(`${BASE}/report`, { method: 'POST', headers, body: JSON.stringify({ date }), }); if (!createRes.ok) throw new Error(await createRes.text()); const { data: { fileId } } = await createRes.json(); // Step 2 โ€” poll until completed const pollHeaders = { 'X-API-KEY': API_KEY }; let status = 'in_queue'; let errorMsg = null; while (status === 'in_queue' || status === 'in_progress') { await new Promise((r) => setTimeout(r, 5000)); const statusRes = await fetch(`${BASE}/report/${fileId}`, { headers: pollHeaders }); if (!statusRes.ok) throw new Error(await statusRes.text()); ({ status, errorMsg } = (await statusRes.json()).data); } if (status === 'error') throw new Error(errorMsg || 'Report generation failed'); // Step 3 โ€” download JSON const downloadRes = await fetch(`${BASE}/report/${fileId}/download`, { headers: pollHeaders }); if (!downloadRes.ok) throw new Error(await downloadRes.text()); return downloadRes.json(); } // Export breadcrumbs for March 15, 2025 const report = await downloadBreadcrumbsReport('2025-03-15'); console.log(`Activities with breadcrumbs: ${report.breadcrumbsByActivities.length}`); ``` *** ## Error Codes | HTTP Status | When | | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid `fileId` format (not a UUID); report not ready for download (`status` โ‰  `completed`); breadcrumbs not enabled; future `date`; no time clocks in company | | `401` | Missing or invalid authentication | | `403` | `fileId` belongs to a different company | | `404` | `fileId` not found; report file missing from storage | | `422` | Request body validation failure | When `status` is `error`, `errorMsg` in the status response contains the failure reason. *** ## Prerequisites & Limitations > ๐Ÿ“ Important Considerations > > * **Enable breadcrumbs** in Time Clock settings before calling the API. If no time clock has breadcrumbs enabled, step 1 returns `400`. > * **Task metadata** is retained for approximately **2 hours** (poll within this window). > * **Generated files** in storage use a **1-day TTL** tag โ€” download soon after completion. > * **Company-wide scope:** one request exports breadcrumbs from all time clocks for the date. > * **Date only:** there is no multi-day range in a single request; call once per day. *** [Generate Report API Reference](https://developer.connecteam.com/reference/generate_breadcrumbs_report_time_clock_breadcrumbs_v1_report_post) ยท [Get Status API Reference](https://developer.connecteam.com/reference/get_report_status_time_clock_breadcrumbs_v1_report__fileid__get) ยท [Download API Reference](https://developer.connecteam.com/reference/download_breadcrumbs_report_time_clock_breadcrumbs_v1_report__fileid__download_get)