API reference / Sessions and actions
Read action status without replay
Reads the existing record, including after session expiry/release while the key and device access remain valid.
/api/v1/sessions/{sessionId}/actions/{requestId}Authorization
Same key that acquired the session; continued device accessSend 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/sessions/session_123/actions/tap-001' \
--header "Authorization: Bearer $FLEETDECK_API_KEY"Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"id": "action_123",
"requestId": "tap-001",
"status": "completed",
"kind": "tap",
"createdAt": "2030-01-01T10:00:00.000Z",
"finishedAt": "2030-01-01T10:00:00.000Z",
"result": {
"status": "submitted",
"verified": false,
"instruction": "Take a fresh screenshot to verify the intended effect before the next decision"
}
}Path parameters
sessionIdstringrequiredSession ID returned by Acquire a session. Use the key that owns that session.
"session_123"Validation pattern
^[A-Za-z0-9._:-]+$requestIdstringrequiredYour stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.
"tap-001"Validation pattern
^[A-Za-z0-9._:-]+$Request body
This endpoint does not require a request body.
Behavior and limits
Reads the existing record, including after session expiry/release while the key and device access remain valid. Does not execute the command. Result payloads are cleared opportunistically after one hour; result:null can mean pending work, expiry or retention cleanup. Inspect status and finishedAt.
Response 200
ActionRecord · application/json
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
"action_123"Validation pattern
^[A-Za-z0-9._:-]+$requestIdstringalways presentYour stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.
"tap-001"Validation pattern
^[A-Za-z0-9._:-]+$statusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"queued""running""completed""failed""unknown""cancelled"kindstringalways presentAction type that produced this record.
"screenshot""inspect""apps""tap""double_tap""long_press""swipe""text""key""button""open_url""launch_app""kill_app""clipboard_get""set_clipboard""push_media""media_chunk""native_tool"createdAtstringalways presentUTC instant when the record was created.
"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"resultany JSON | nullalways presentDriver-defined JSON or null. Known shapes are documented in ActionResult; native tool output may differ.
View child fields
statusstringoptionalCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"submitted""applied""staged""imported"verifiedbooleanoptionalMedia import acknowledgement is not publication verification. Other input normally returns false.
falseinstructionstringoptionalDriver guidance for the next observation or recovery step.
"Take a fresh screenshot to verify the intended effect before the next decision"contentobject[]optionalContent blocks returned by the driver. Screenshot image blocks contain base64 image bytes.
View child fields
typestringalways presentDiscriminator that selects the action or content shape.
"image"mimeTypestringalways presentMIME type of the returned image.
"image/jpeg""image/png"datastringalways presentBase64 image bytes, without a data URL prefix.
widthintegeroptionalCaptured image width in pixels.
heightintegeroptionalCaptured image height in pixels.
capturedAtstringoptionalUTC capture timestamp supplied by the relay.
coordinateSpacestringoptionalCoordinate convention for common FleetDeck actions. Normalized x/y values are relative to the current screen.
xmlstringoptionalADB UI hierarchy XML; bounds use screen pixels.
treeany JSONoptionalWDA accessibility tree; shape varies by version.
screenobjectoptionalADB {w,h} pixels; WDA {width,height} logical points.
packagesstring[]optionalAndroid package-name strings returned by ADB app inventory.
appsany JSON[]optionalPhone-agent-defined app entries. Entry fields depend on the agent version.
valuestringoptionalPlaintext clipboard value.
codestringoptionalExecution error code, distinct from an HTTP error.
errorstringoptionalHuman-readable failure explanation. Use code for programmatic handling.
HTTP 200 confirms that the action record was returned. Check status and result for execution failures.
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 ↗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 ↗Execution errors inside HTTP 200
These codes live in result when the driver fails or cannot confirm delivery. Read action.status first.
Action result (driver 422)UNSUPPORTEDTool or parameter is unavailable on this transport, OS or phone-agent version.
Recovery: Recheck capabilities and driver limitations. Connect a suitable private native bridge or update the phone agent; verify actual hardware support.
Full error reference ↗Native driver 422UNSUPPORTED_TEXTADB input cannot encode the requested text.
Recovery: Use ASCII without literal %s, or a compatible relay/IME/native extension. The bridge stores UNSUPPORTED_TEXT as failed with its code; inspect the action result.
Full error reference ↗Action result (driver 422)MEDIA_IMPORT_FAILEDPhone rejected Photos/gallery import.
Recovery: Check complete file bytes, MIME, supported agent version and Photos/gallery permission. Inspect the gallery before retrying.
Full error reference ↗Action result (driver 502/503/504)DEVICE_UNAVAILABLEPhone or relay could not provide the requested operation.
Recovery: Check online state, capture/USB trust and relay connectivity. Wake/unlock locally if required; inspect state before repeating input.
Full error reference ↗Action result (driver 502/504)DELIVERY_UNKNOWNDelivery may have happened but its outcome is unconfirmed.
Recovery: Read the original action, then capture/inspect the phone. Do not blindly replay taps, uploads or publication.
Full error reference ↗Action result (driver 503)CONFIGURATIONServer relay transport configuration is invalid.
Recovery: Have the operator repair the relay URL; changing phone credentials will not correct server configuration.
Full error reference ↗Native driver 502/504NATIVE_FAILEDNative ADB/MCP execution failed or exceeded its deadline.
Recovery: Check ADB trust/serial or the native MCP service and connection. Inspect first; the command may already have had effects. The bridge preserves this code in an unknown action result.
Full error reference ↗Native driver 502/504WDA_FAILEDWDA rejected or timed out on an operation.
Recovery: Check WDA signing, running session and connectivity. A later action can re-establish a lost WDA session; inspect before new input. The bridge preserves this code in an unknown action result.
Full error reference ↗Example error messages are illustrative. Match the code and HTTP status; do not depend on exact message wording.
