> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapkit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Screenshot

> Capture a screenshot from the phone

Capture a screenshot from the phone's current screen.

This is an inspection endpoint: the Mac app reads the current phone screen and returns image data. It does not send input to the phone or change phone state.

## Request

```bash theme={null}
curl https://api.tapkit.ai/v1/phones/{phone_id}/screenshot \
  -H "X-API-Key: joot_your_api_key" \
  --output screenshot.png
```

### Path Parameters

| Parameter  | Type     | Description          |
| ---------- | -------- | -------------------- |
| `phone_id` | `string` | The phone identifier |

### Query Parameters

| Parameter | Type      | Default | Description                    |
| --------- | --------- | ------- | ------------------------------ |
| `async`   | `boolean` | `false` | Return immediately with job ID |

## Synchronous Response

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

## Asynchronous Response

When `?async=true`:

```json theme={null}
{
  "job_id": "job_abc123"
}
```

Retrieve the screenshot via `GET /jobs/{job_id}/download`.

## Examples

### Sync Screenshot (curl)

```bash theme={null}
curl https://api.tapkit.ai/v1/phones/abc123/screenshot \
  -H "X-API-Key: joot_..." \
  --output screen.png
```

### Sync Screenshot (Python)

```python theme={null}
import requests

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

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

### Async Screenshot

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

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

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

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

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

## Errors

### Mac App Not Running

```json theme={null}
{
  "error": "MAC_APP_NOT_RUNNING",
  "message": "Mac companion app is not connected"
}
```

### Timeout

```json theme={null}
{
  "error": "TIMEOUT",
  "message": "Screenshot capture timed out"
}
```

HTTP Status: `408 Request Timeout`