FleetDeckDocs

API reference / Touch automations

List touch runs

Run history for touch schedules and sequence runs on this phone, newest first.

GET/api/v1/devices/{deviceId}/touch-runs

Authorization

Bearer tokendevices:read

Send Authorization: Bearer <FLEETDECK_API_KEY> with the scope above. The key must also grant access to the target device. Authentication guide ↗

Request example
Request · cURL
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
200 · success
{
  "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

deviceIdstringrequired

Exact device ID from List devices. The current key must grant access to this phone.

min 1 charactersmax 128 characters
Example: "device_123"
Validation pattern^[A-Za-z0-9._:-]+$

Query parameters

scheduleIdstringoptional

Only runs of this schedule (a sequence run’s scheduleId works too).

statusstringoptional

Only runs in this state. Expired running leases are reported as interrupted.

Allowed:"running""completed""failed""cancelled""skipped""interrupted"
limitintegeroptional

Page size for JSON. Ignored for CSV, which pages internally.

min 1max 100default 20
cursorstringoptional

nextCursor from the previous page.

formatstringoptional

csv returns text/csv with up to 5,000 rows and an X-FleetDeck-Truncated header.

default "json"
Allowed:"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 present
View child fields
idstringalways present

Unique identifier of this resource. Use the returned value in subsequent requests.

min 1 charactersmax 128 characters
Example: "run_123"
Validation pattern^[A-Za-z0-9._:-]+$
scheduleIdstringalways present
min 1 charactersmax 128 characters
Example: "schedule_123"
Validation pattern^[A-Za-z0-9._:-]+$
statusstringalways present

Current state. A completed action means the driver finished; verify the intended screen or app effect separately.

Allowed:"running""completed""failed""cancelled""skipped""interrupted"
scheduledAtstringalways present

Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.

date-time
Example: "2030-01-01T10:00:00.000Z"
startedAtstring | nullalways present

UTC instant execution began, or null if it has not begun.

date-time
Example: "2030-01-01T10:00:00.000Z"
finishedAtstring | nullalways present

UTC instant execution ended, or null while no terminal outcome is recorded.

date-time
Example: "2030-01-01T10:00:00.000Z"
errorstring | nullalways present

Human-readable failure explanation. Use code for programmatic handling.

notificationSentAtstring | nullalways present
date-time
notificationAttemptsintegeralways present
Example: 0
durationMsinteger | nullalways present
Example: 41250
nextCursorstring | nullalways present
min 1 charactersmax 128 characters
Validation 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.