API reference / Touch automations
List touch runs
Run history for touch schedules and sequence runs on this phone, newest first.
/api/v1/devices/{deviceId}/touch-runsAuthorization
devices:readSend Authorization: Bearer <FLEETDECK_API_KEY> with the scope above. The key must also grant access to the target device. Authentication guide ↗
Request example
curl --request GET \
--url 'https://fleetdeck.co/api/v1/devices/device_123/touch-runs' \
--header "Authorization: Bearer $FLEETDECK_API_KEY"Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"runs": [
{
"id": "run_123",
"scheduleId": "schedule_123",
"status": "completed",
"scheduledAt": "2030-01-01T10:00:00.000Z",
"startedAt": "2030-01-01T10:00:00.000Z",
"finishedAt": "2030-01-01T10:00:00.000Z",
"error": null,
"notificationSentAt": null,
"notificationAttempts": 0,
"durationMs": 41250
}
],
"nextCursor": null
}Path parameters
deviceIdstringrequiredExact device ID from List devices. The current key must grant access to this phone.
"device_123"Validation pattern
^[A-Za-z0-9._:-]+$Query parameters
scheduleIdstringoptionalOnly runs of this schedule (a sequence run’s scheduleId works too).
statusstringoptionalOnly runs in this state. Expired running leases are reported as interrupted.
"running""completed""failed""cancelled""skipped""interrupted"limitintegeroptionalPage size for JSON. Ignored for CSV, which pages internally.
20cursorstringoptionalnextCursor from the previous page.
formatstringoptionalcsv returns text/csv with up to 5,000 rows and an X-FleetDeck-Truncated header.
"json""json""csv"Request body
This endpoint does not require a request body.
Behavior and limits
Run history for touch schedules and sequence runs on this phone, newest first. Query: scheduleId, status (running, completed, failed, cancelled, skipped, interrupted), limit 1..100 (default 20) and cursor (the previous nextCursor). Add format=csv for a spreadsheet download of up to 5,000 rows across pages, starting at cursor if given; X-FleetDeck-Truncated tells whether more rows exist. CSV cells starting with =, +, -, @, tab or carriage return are prefixed with an apostrophe so spreadsheets do not run them as formulas.
Response 200
TouchRunList · application/json
runsobject[]always presentView child fields
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
"run_123"Validation pattern
^[A-Za-z0-9._:-]+$scheduleIdstringalways present"schedule_123"Validation pattern
^[A-Za-z0-9._:-]+$statusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"running""completed""failed""cancelled""skipped""interrupted"scheduledAtstringalways presentFuture execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.
"2030-01-01T10:00:00.000Z"startedAtstring | nullalways presentUTC instant execution began, or null if it has not begun.
"2030-01-01T10:00:00.000Z"finishedAtstring | nullalways presentUTC instant execution ended, or null while no terminal outcome is recorded.
"2030-01-01T10:00:00.000Z"errorstring | nullalways presentHuman-readable failure explanation. Use code for programmatic handling.
notificationSentAtstring | nullalways presentnotificationAttemptsintegeralways present0durationMsinteger | nullalways present41250nextCursorstring | nullalways presentValidation pattern
^[A-Za-z0-9._:-]+$Errors
Expand a code for its recovery steps. Responses use error and code; validation errors also include issues.
401UNAUTHORIZEDMissing, malformed, expired or revoked credential; user verification/password state can also deny access.
Recovery: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.
Full error reference ↗403FORBIDDENRequired scope, device grant, account membership or worker identity is missing.
Recovery: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.
Full error reference ↗404NOT_FOUNDUnknown route or resource unavailable to this caller.
Recovery: Check method/path and use returned IDs from this account/key. Do not guess IDs.
Full error reference ↗402PLAN_REQUIREDDevice account has no active entitlement.
Recovery: Restore an active device entitlement in the workspace before controlling it.
Full error reference ↗422VALIDATIONA field, type, bound or unknown property failed validation.
Recovery: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.
Full error reference ↗500INTERNALUnexpected service error.
Recovery: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.
Full error reference ↗Example error messages are illustrative. Match the code and HTTP status; do not depend on exact message wording.
