MCP / Tool reference
fleetdeck_action_status
Read an action's outcome without re-executing it.
Parameters
sessionIdstringrequiredSession ID returned by Acquire a session. Use the key that owns that session.
"session_123"Validation pattern
^[A-Za-z0-9._:-]+$requestIdany JSONrequiredYour 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"Unknown fields are rejected.
View JSON Schema
{
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"requestId": {
"$ref": "#/properties/sessionId"
}
},
"required": [
"sessionId",
"requestId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Call example
const result = await client.callTool({
name: "fleetdeck_action_status",
arguments: {
"sessionId": "session_123",
"requestId": "tap-001"
}
});
if (result.isError) {
console.error(result.content);
} else {
console.log(result.content);
}The SDK example assumes an initialized MCP client. See connection setup for HTTP authentication, initialization and stdio configuration.
Response
The result contains content blocks and isError. The text block contains JSON with the fields below. See the corresponding REST response contract.
{
"content": [
{
"type": "text",
"text": "{\n \"id\": \"action_123\",\n \"requestId\": \"tap-001\",\n \"status\": \"completed\",\n \"kind\": \"tap\",\n \"createdAt\": \"2030-01-01T10:00:00.000Z\",\n \"finishedAt\": \"2030-01-01T10:00:00.000Z\",\n \"result\": {\n \"status\": \"submitted\",\n \"verified\": false,\n \"instruction\": \"Take a fresh screenshot to verify the intended effect before the next decision\"\n }\n}"
}
],
"isError": false
}idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
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.
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.
finishedAtstring | nullalways presentUTC instant execution ended, or null while no terminal outcome is recorded.
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.
instructionstringoptionalDriver guidance for the next observation or recovery step.
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.
Behavior
- The MCP descriptor marks this tool read-only and idempotent.
- FleetDeck handler errors return isError=true with a JSON text payload. SDK input validation may return plain-text error content, and authentication or transport can fail before a tool result exists. Screenshot results place image content in MCP image blocks and omit those bytes from the parallel JSON block.
Errors
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 ↗Client onlyCONNECTION_FAILEDThe client could not reach the configured FleetDeck origin.
Recovery: Check DNS, TLS, proxy/firewall and FLEETDECK_BASE_URL. Before replaying a mutation, query its saved requestId when connectivity returns.
Full error reference ↗Client onlyINVALID_RESPONSEThe server response was not valid FleetDeck JSON.
Recovery: Check that the base URL points to FleetDeck and that a proxy did not replace the response. Preserve the original action identifiers before retrying.
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 ↗SDK validation can return plain-text error content. Authentication and transport may fail before a tool result exists. Read the JSON-RPC and transport error reference before parsing the text as JSON.
Annotations
| Annotation | Value |
|---|---|
readOnlyHint | true |
destructiveHint | false |
idempotentHint | true |
openWorldHint | true |
