Skip to main content
GET
/
phones
/
{phone_id}
/
screenshot
Screenshot
curl --request GET \
  --url https://api.example.com/phones/{phone_id}/screenshot
Capture a screenshot from the phone’s current screen.

​
Request

curl https://api.tapkit.ai/phones/{phone_id}/screenshot \
  -H "X-API-Key: TK_your_api_key" \
  --output screenshot.png

​
Path Parameters

ParameterTypeDescription
phone_idstringThe phone identifier

​
Query Parameters

ParameterTypeDefaultDescription
asyncbooleanfalseReturn immediately with job ID

​
Synchronous Response

Returns PNG image data directly with Content-Type: image/png.

​
Asynchronous Response

When ?async=true: 
{
  "job_id": "job_abc123"
}
Retrieve the screenshot via GET /jobs/{job_id}/download.

​
Examples

​
Sync Screenshot (curl)

curl https://api.tapkit.ai/phones/abc123/screenshot \
  -H "X-API-Key: TK_..." \
  --output screen.png

​
Sync Screenshot (Python)

import requests

response = requests.get(
    f"https://api.tapkit.ai/phones/{phone_id}/screenshot",
    headers={"X-API-Key": "TK_..."}
)

with open("screenshot.png", "wb") as f:
    f.write(response.content)

​
Async Screenshot

# Request screenshot asynchronously
response = requests.get(
    f"https://api.tapkit.ai/phones/{phone_id}/screenshot?async=true",
    headers={"X-API-Key": "TK_..."}
)
job_id = response.json()["job_id"]

# Poll for completion
while True:
    job = requests.get(
        f"https://api.tapkit.ai/jobs/{job_id}",
        headers={"X-API-Key": "TK_..."}
    ).json()

    if job["status"] == "completed":
        break
    time.sleep(0.1)

# Download the image
image = requests.get(
    f"https://api.tapkit.ai/jobs/{job_id}/download",
    headers={"X-API-Key": "TK_..."}
)

with open("screenshot.png", "wb") as f:
    f.write(image.content)

​
Errors

​
Mac App Not Running

{
  "error": "MAC_APP_NOT_RUNNING",
  "message": "Mac companion app is not connected"
}

​
Timeout

{
  "error": "TIMEOUT",
  "message": "Screenshot capture timed out"
}
HTTP Status: 408 Request Timeout