iRemotech Device API
Programmatic remote access to your managed fleet of iPhones. List your devices, take screenshots, send actions (tap, type, swipe…), open a live video stream, drive a device live with a control channel, upload files, and launch Instagram automations — all over a simple HTTPS + WebSocket API.
- Base URL:
https://api.iremotech.com/v1(the live stream and live control usewss://api.iremotech.com). - Format: JSON requests and responses; screenshots are JPEG; the live stream is a WebSocket.
- Versioning: everything is under
/v1. Changes within v1 are additive and backward-compatible. - Reference: the machine-readable contract is in
openapi.yaml.
1. Quickstart
- In the dashboard, open API Access and click Create key. Copy the key — it is shown only once.
- List your devices:
curl https://api.iremotech.com/v1/devices \
-H "Authorization: Bearer $IREMOTECH_API_KEY"
[
{ "public_id": "dev_1a2b3c4d5e6f7a8b", "name": "iPhone A" }
]
- Tap the screen of that device:
curl -X POST https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/actions \
-H "Authorization: Bearer $IREMOTECH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "tap", "x": 200, "y": 640 }'
Coordinates (x/y) are in the pixel space of the snapshot you get from
GET /devices/{id}/snapshot — read the pixel position straight off that image
and send it. The API scales it to the device for you; don't pre-scale.
That's the whole model: get a public_id, then act on it.
2. Authentication
Send your key as a Bearer token on every request:
Authorization: Bearer irt_live_<key_id>_<secret>
Keys are created and revoked from the dashboard. You can hold several at once (rotate by minting a new one, migrating, then revoking the old). Treat a key like a password: it grants access to your devices.
Scopes
Each key carries a set of scopes. A key can only do what its scopes allow; calling
an endpoint without the needed scope returns 403 forbidden.
| Scope | Grants |
|---|---|
read |
List devices, take screenshots, read usage, read automation jobs |
control |
Send actions to a device, open the live control channel |
stream |
Open the live video stream |
upload |
Upload files to a device |
manage |
Rename devices and edit their notes and labels (§3b) — shown as Manage in the dashboard |
automations |
Launch Instagram automations on a device (§4b) — shown as Automations in the dashboard |
By default a new key has every scope; remove the ones a given integration doesn't need.
The scopes of an existing key cannot be changed: to get a scope a key lacks (for
example manage or automations, which keys created before they existed do not
have), create a new key.
3. Devices
List devices — GET /v1/devices (scope: read)
curl https://api.iremotech.com/v1/devices -H "Authorization: Bearer $KEY"
Returns an array of devices. Use public_id in every other call — it is an opaque
identifier and does not expose the underlying hardware.
[
{
"public_id": "dev_1a2b3c4d5e6f7a8b",
"name": "EJ-369",
"custom_name": "Front desk 03",
"notes": "SIM replaced in September",
"labels": [
{ "name": "VIP", "color": "#E53935" },
{ "name": "Batch 3", "color": "#9E9E9E" }
],
"dashboard_id": 5016,
"dashboard_url": "https://iremotech.com/dashboard/device/5016"
}
]
nameis the device's original name;custom_nameis the name you gave it (nullif none).notesare your free-text notes (nullif none).labelsare the device's labels in display order ([]if none).dashboard_urlopens the device in the dashboard.
To change custom_name, notes or labels, see §3b.
Device detail — GET /v1/devices/{public_id} (scope: read)
curl https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $KEY"
{
"public_id": "dev_1a2b3c4d5e6f7a8b",
"name": "EJ-369",
"custom_name": "Front desk 03",
"notes": "SIM replaced in September",
"labels": [{ "name": "VIP", "color": "#E53935" }],
"dashboard_id": 5016,
"dashboard_url": "https://iremotech.com/dashboard/device/5016",
"screen": { "width": 375, "height": 667 },
"snapshot": { "width": 406, "height": 720 }
}
snapshot is the size of the screenshots and stream frames for this device —
the pixel space every action coordinate is in. screen is the phone's
logical canvas in iPhone points, informational only (for example to size a
viewer); never convert coordinates to it — the API scales for you.
Screenshot — GET /v1/devices/{public_id}/snapshot (scope: read)
Returns the current screen as a JPEG.
curl https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/snapshot \
-H "Authorization: Bearer $KEY" --output screen.jpg
3b. Editing a device — name, notes, labels
PATCH /v1/devices/{public_id} (scope: manage)
Rename a device, write its notes and organise your fleet with labels from your own
tools. The change is saved in your iRemotech dashboard, and a GET right after it
returns the new values.
Your existing API keys cannot call this endpoint. It needs the Manage scope (
manage), and the scopes of an existing key cannot be changed. Create a new key in the dashboard (API Access → Create key; new keys include every scope, Manage included), move your integration to it, then revoke the old key. With an older key this endpoint answers403 forbidden.
Send a JSON object with one or more of these three fields. A field you leave out is not touched.
| Field | Type | What it does |
|---|---|---|
custom_name |
string or null |
The name you give the device: 1–64 characters after leading and trailing whitespace is removed. null removes it, and the device is shown by its original name again. An empty string is rejected — send null instead. |
notes |
string or null |
Free-text notes, up to 2,000 characters. null or "" clears them. |
labels |
array | The device's complete list of labels, in the order you want them shown. It replaces the current labels; [] removes them all (null is rejected). Up to 20 labels, each { "name": "...", "color": "#RRGGBB" } — color is optional. |
Lengths are counted in Unicode code points: a letter, accented or not, counts as one; some emoji are made of several code points (flags, skin tones, combined emoji) and count as more than one.
The response is the device with the values now saved — the same shape as an item of
GET /v1/devices (§3). An empty custom_name or notes is returned as null.
Examples
In every example, replace dev_1a2b3c4d5e6f7a8b with the device's public_id;
$API_KEY is a key with the Manage scope.
Rename a device:
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "custom_name": "Front desk 03" }'
{
"public_id": "dev_1a2b3c4d5e6f7a8b",
"name": "EJ-369",
"custom_name": "Front desk 03",
"notes": "SIM replaced in September",
"labels": [{ "name": "VIP", "color": "#E53935" }],
"dashboard_id": 5016,
"dashboard_url": "https://iremotech.com/dashboard/device/5016"
}
Only custom_name changed; notes and labels are returned as they already were.
Remove the custom name (the device is shown by its original name again):
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "custom_name": null }'
The response has "custom_name": null.
Set the notes:
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "notes": "SIM replaced in September" }'
The response has "notes": "SIM replaced in September".
Clear the notes ("notes": "" does the same):
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "notes": null }'
The response has "notes": null.
Replace the labels — the device ends up with exactly these two labels, in this order:
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "labels": [ { "name": "VIP", "color": "#E53935" }, { "name": "Batch 3" } ] }'
The response has the labels as they are now saved, with their colours:
"labels": [
{ "name": "VIP", "color": "#E53935" },
{ "name": "Batch 3", "color": "#9E9E9E" }
]
Here Batch 3 did not exist yet, so it was created in the default grey. If VIP
already existed in another colour, the response shows that colour — see
"How labels work" below.
Remove all labels:
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "labels": [] }'
The response has "labels": [].
Several fields in one request:
curl -X PATCH https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "custom_name": "Front desk 03", "notes": "SIM replaced in September", "labels": [ { "name": "VIP" } ] }'
{
"public_id": "dev_1a2b3c4d5e6f7a8b",
"name": "EJ-369",
"custom_name": "Front desk 03",
"notes": "SIM replaced in September",
"labels": [{ "name": "VIP", "color": "#E53935" }],
"dashboard_id": 5016,
"dashboard_url": "https://iremotech.com/dashboard/device/5016"
}
The fields of one request are saved together or not at all.
To add or remove a single label, read the device's current labels (GET), change
the list, and send the whole list back.
How labels work
- Labels belong to your account and are shared by all your devices. A label is
identified by its
name, matched exactly: names are case-sensitive, soVIPandvipare two different labels. - A name your account does not have yet is created — with the
coloryou send, or grey (#9E9E9E) if you send none. - A name that already exists is used as it is, and a
coloryou send for it is ignored: a label has one colour on every device, so changing it from one device would change it everywhere. Change a label's colour in the dashboard. - A name must be 1–50 characters after leading and trailing whitespace is
removed, and can appear only once in
labels. - Removing a label from a device does not delete the label from your account. Your account can have up to 200 different labels; delete the ones you no longer use in the dashboard.
Limits
| What | Limit |
|---|---|
custom_name |
1–64 characters |
notes |
up to 2,000 characters |
| Labels per device | 20 |
Label name |
1–50 characters, once per request |
Label color |
#RRGGBB (six hexadecimal digits), optional |
| Labels per account | 200 different labels |
| Request body | 64 KB (65,536 bytes) |
| Edits of one device | 10 per minute, with a burst of 5 |
| Edits across your account | 5 per second, with a burst of 20 |
In practice: one device accepts 5 edits in quick succession, then one every 6
seconds; across your account, 20 edits at once and then 5 per second — enough to
relabel a fleet of 200 phones in under a minute. Send one request per device with
its final values; do not loop on one device. A request that goes over a limit gets
429 rate_limited with a Retry-After header. Every request to one of your
devices counts, including one rejected for an invalid body.
Editing does not count toward your daily budgets (§10). Each request still counts toward the general request rate of your key and account (§9).
Errors
A request that fails changes nothing — except upstream_unavailable, where the
outcome is not known. The request is idempotent: sending the same request again
leads to the same saved state, so repeating it is safe.
| HTTP | code |
Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized |
Missing or invalid API key | Check the key |
| 403 | forbidden |
The key does not have the Manage scope, or the key or account is not active (suspended, revoked, expired, IP not allowed) | Without the Manage scope: create a new key (see the note above). Otherwise check detail: the key may be revoked or expired, or your IP not in its allowlist; if your account is suspended, contact us |
| 404 | device_not_found |
No such device in your account | Check the public_id |
| 422 | invalid_action |
The body failed validation: empty body or {}, not a JSON object, a request body larger than 64 KB, unknown field, a name that is empty or too long, notes that are too long, text containing the null character or invalid Unicode, bad colour, the same label name twice, more than 20 labels, labels: null |
Fix the request |
| 422 | label_limit_reached |
The change would create labels beyond your account's 200 | Reuse existing labels, or delete unused ones in the dashboard |
| 429 | rate_limited |
Too many edits | Wait Retry-After seconds, then retry |
| 503 | rename_unavailable |
You sent custom_name and the device's server did not accept the change. Nothing was changed, including the other fields you sent. |
Retry later, or send the other fields without custom_name |
| 503 | upstream_unavailable |
The device settings could not be saved right now | Repeat the same request |
Renaming is the only change that also has to be accepted by the device's server; notes and labels do not depend on it.
(invalid_action is this API's code for any request body that fails validation.)
When the API rejects the body itself, the response has an errors array with one
item per problem: loc says where (["body", "notes"], ["body", "labels", 0, "color"],
…) and msg says what. A change rejected further along (by the dashboard) has no
errors array; its detail says what was wrong. Example — notes longer than 2,000
characters:
{
"type": "https://errors.kernel-api.iremotech.com/invalid_action",
"title": "invalid_action",
"status": 422,
"code": "invalid_action",
"detail": "request validation failed",
"errors": [
{
"type": "string_too_long",
"loc": ["body", "notes"],
"msg": "String should have at most 2000 characters"
}
]
}
Example — a key without the Manage scope:
{
"type": "https://errors.kernel-api.iremotech.com/forbidden",
"title": "forbidden",
"status": 403,
"code": "forbidden",
"detail": "scope 'manage' required"
}
Example — the rename was not accepted:
{
"type": "https://errors.kernel-api.iremotech.com/rename_unavailable",
"title": "rename_unavailable",
"status": 503,
"code": "rename_unavailable",
"detail": "the device's server did not accept the new name, so nothing was changed; retry later, or send the other fields without custom_name"
}
4. Actions — POST /v1/devices/{public_id}/actions (scope: control)
Send one action per call. The body is a single object discriminated by type.
Coordinates are in snapshot pixels — the snapshot size from device detail (§3), i.e. the pixel position read straight off a screenshot. Never scale them to screen.
type |
Fields | Effect |
|---|---|---|
tap |
x, y [, hold_ms (20–500, default 150)] |
Tap a point; hold_ms is how long the finger stays down — vary it per tap (e.g. 80–220) for a natural cadence |
double_tap |
x, y, gap_ms (0–500, default 100) |
Double-tap a point (both taps + the gap timed on the device) |
swipe |
x1, y1, x2, y2, duration_ms (default 250) |
Swipe between two points |
long_press |
x, y, hold_ms (default 600) |
Press and hold (the finger stays down about one second longer than hold_ms: a long-press pickup before and a settle after) |
drag |
x1, y1, x2, y2, duration_ms (default 600) |
Drag between two points |
scroll |
x, y, dy (wheel notches, positive scrolls down, clamped to ±20 per message) |
Scroll at a point — the pointer is moved to (x, y) first |
text |
text |
Type text |
key |
key |
Send a single key |
press |
name or (modifiers + key) |
A preset (e.g. home) or a modifier chord |
open_url |
url |
Open a URL |
open_app |
target [, username] |
Open an app screen or Telegram bot by name |
clipboard_set |
text |
Set the device clipboard |
clipboard_get |
— | Returns { "clipboard": "..." } |
airplane |
on (boolean) |
Toggle airplane mode |
device_ip |
— | Returns the device's current IP |
recalibrate |
— | Recentre the pointer (does not reboot or wipe) |
Most actions return { "result": {} }. clipboard_get and device_ip return data
under result.
One example per action
All send POST https://api.iremotech.com/v1/devices/$ID/actions with
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json"; only the
-d body changes:
# tap a point
-d '{ "type": "tap", "x": 200, "y": 640 }'
# tap with a chosen press duration (20–500 ms; omit for 150 ms)
-d '{ "type": "tap", "x": 200, "y": 640, "hold_ms": 120 }'
# swipe up (from y=600 to y=200)
-d '{ "type": "swipe", "x1": 200, "y1": 600, "x2": 200, "y2": 200, "duration_ms": 250 }'
# press and hold
-d '{ "type": "long_press", "x": 200, "y": 640, "hold_ms": 600 }'
# drag between two points
-d '{ "type": "drag", "x1": 100, "y1": 400, "x2": 300, "y2": 400, "duration_ms": 600 }'
# scroll: dy in wheel notches (positive = down); a few notches per message
-d '{ "type": "scroll", "x": 200, "y": 400, "dy": -3 }'
# type text into the focused field
-d '{ "type": "text", "text": "hello world" }'
# send a single key
-d '{ "type": "key", "key": "enter" }'
# a named key preset (e.g. go to the home screen)
-d '{ "type": "press", "name": "home" }'
# open a URL on the device
-d '{ "type": "open_url", "url": "https://example.com" }'
# open an app screen or a Telegram bot by name
-d '{ "type": "open_app", "target": "instagram_account_status" }'
-d '{ "type": "open_app", "target": "telegram", "username": "yourbot" }'
# set the device clipboard
-d '{ "type": "clipboard_set", "text": "some text" }'
# read the device clipboard -> { "result": { "clipboard": "some text" } }
-d '{ "type": "clipboard_get" }'
# toggle airplane mode on/off
-d '{ "type": "airplane", "on": true }'
# read the device's current IP -> { "result": { "ip": "..." } }
-d '{ "type": "device_ip" }'
# recentre the pointer if taps start landing off-target
-d '{ "type": "recalibrate" }'
Full example:
curl -X POST https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/actions \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "clipboard_get" }'
# -> { "result": { "clipboard": "some text" } }
An unknown or malformed action returns 400 invalid_action. A well-formed action
the device refuses returns 422 command_rejected.
Open apps and screens — open_app
Open an app screen or a Telegram bot by a short name — no need to know any
URL. Send { "type": "open_app", "target": "<name>" }. For Telegram, also
pass username (the bot handle).
target |
Opens |
|---|---|
instagram |
Instagram (app home) |
instagram_account_status |
Instagram → Account Status |
instagram_settings |
Instagram → Settings |
instagram_reel |
Instagram → new Reel camera |
instagram_profile |
Instagram → your profile |
instagram_camera |
Instagram → Camera |
instagram_dms |
Instagram → Direct messages |
instagram_activity |
Instagram → Activity |
instagram_explore |
Instagram → Explore |
ios_notes |
iOS Notes |
ios_photos |
iOS Photos |
ios_settings |
iOS Settings |
ios_about |
iOS Settings → General → About |
ios_phone |
iOS Phone |
ios_messages |
iOS Messages |
telegram (+ username) |
A Telegram bot by handle |
An unknown target (or a bad/misplaced username) returns
400 invalid_action.
4b. Instagram automations
Launch the Instagram automations your agency already uses in the dashboard — a warm-up session, an account status check, or an account listing — on one of your phones, then follow the job until it finishes.
POST /v1/devices/{public_id}/automations(scope:automations) launches one job.GET /v1/automations/{job_id}(scope:read) reads one job.GET /v1/devices/{public_id}/automations(scope:read) lists a phone's jobs.
A
warm_upneeds automation tokens up front. When tokens are enabled for your agency, a warm-up is launched only when your token balance covers its maximum cost: the requested session length plus 120 seconds of overhead, at your agency's token rate (see the tokens guide and "Tokens" below). Otherwise the launch answers402 insufficient_tokensand nothing is queued. Status checks and account listings use no tokens.
Your existing API keys cannot launch automations. Launching needs the Automations scope (
automations), and the scopes of an existing key cannot be changed. Create a new key in the dashboard (API Access → Create key; new keys include every scope), move your integration to it, then revoke the old key. With an older key the launch answers403 forbidden. Reading jobs needs onlyread.
Leave the phone alone while its automation runs. You always have priority over an automation. If the phone was used in the two minutes before the job starts, the job does not start yet; if it is used while the job runs, the job stops within about a second. Each time counts as an interruption: the job goes back to waiting and is tried again 5 to 7 minutes later, and after three interruptions it is abandoned (
needs_review). So: launch, then leave that phone alone until the job iscompleted."Used" means anything that may interrupt the job: any request that reaches the phone itself — an action, a screenshot, the device detail (
GET /v1/devices/{public_id}, which reads the phone), a live stream or live control — and someone using the phone from the dashboard. Listing your devices (GET /v1/devices), editing a device (§3b), reading usage and reading jobs do not reach the phone.
Launch — POST /v1/devices/{public_id}/automations (scope: automations)
| Field | Type | Rules |
|---|---|---|
type |
string | warm_up, account_status or list_accounts. Required. |
account |
string | The Instagram username, without @: 1–30 letters, digits, periods or underscores (whitespace at both ends is removed). Required for warm_up and account_status; not allowed for list_accounts. It must be an active account currently on that phone (not deleted, not paused). It is matched without regard to case; the job's account is the username as stored in the dashboard (lowercase), which may differ in case from what you sent. |
session_duration_s |
integer | warm_up only. How long the warm-up session lasts, 60–900 seconds. Default 600. |
rotate_ip |
boolean | warm_up and account_status only. Change the phone's IP address before starting. Default: the rule of the account's profile in the dashboard, or false when it has none. |
null for an optional field is the same as leaving it out. Any other field is
rejected.
What each type does:
warm_up— a warm-up session onaccount, with the settings of the account's warm-up profile in the dashboard (likes, comments, watch times) when it has one, otherwise the standard settings. You choose only its length and the IP rotation.account_status— checksaccount's status (the same check as in the dashboard), one account per call. To check every account on a phone, launch one call per account.list_accounts— reads which Instagram accounts are on the phone.
There is no /v1 read of the accounts that are active on a phone yet. list_accounts
returns the usernames found on the phone's screen; an account that is paused or removed
in the dashboard answers 404 account_not_found when you launch on it. Manage your
accounts in the dashboard.
In every example, replace dev_1a2b3c4d5e6f7a8b with the device's public_id;
$API_KEY is a key with the Automations scope.
Warm up an account for 7 minutes:
curl -X POST https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/automations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "warm_up", "account": "alice.moreee", "session_duration_s": 420 }'
Check an account's status, changing the IP first:
curl -X POST https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/automations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "account_status", "account": "alice.moreee", "rotate_ip": true }'
List the accounts on a phone:
curl -X POST https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/automations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "list_accounts" }'
The answer is 202 Accepted with the queued job (here, the warm-up):
{
"job_id": "job_8812",
"type": "warm_up",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": "alice.moreee",
"status": "queued",
"created_at": "2026-10-01T10:15:02.000Z",
"dispatched_at": null,
"finished_at": null,
"duration_ms": null,
"result": null,
"failure": null
}
Keep job_id to follow the job; treat it as an opaque string. A job cannot be
cancelled once launched.
Follow a job
Read one job — GET /v1/automations/{job_id} (scope: read):
curl https://api.iremotech.com/v1/automations/job_8812 \
-H "Authorization: Bearer $API_KEY"
The warm-up launched above, completed:
{
"job_id": "job_8812",
"type": "warm_up",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": "alice.moreee",
"status": "completed",
"created_at": "2026-10-01T10:15:02.000Z",
"dispatched_at": "2026-10-01T10:15:14.000Z",
"finished_at": "2026-10-01T10:23:01.000Z",
"duration_ms": 467000,
"result": {
"session_duration_s": 420,
"scrolls": 61,
"likes": 4,
"comments": 0,
"reels_viewed": 38,
"reels_skipped": 12,
"soft_resets": 0
},
"failure": null
}
A completed account status check:
{
"job_id": "job_8811",
"type": "account_status",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": "alice.moreee",
"status": "completed",
"created_at": "2026-10-01T09:50:02.000Z",
"dispatched_at": "2026-10-01T09:50:14.000Z",
"finished_at": "2026-10-01T09:51:48.000Z",
"duration_ms": 94120,
"result": {
"account_state": {
"removed_content_and_messaging_issues": "green",
"what_cant_be_recommended": "warning",
"monetization": "unknown",
"features_you_cant_use": "green",
"who_dont_follow_you": "green",
"under_18": "green"
},
"post_rotation_retries": 0
},
"failure": null
}
A completed account listing:
{
"job_id": "job_8810",
"type": "list_accounts",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": null,
"status": "completed",
"created_at": "2026-10-01T09:40:02.000Z",
"dispatched_at": "2026-10-01T09:40:14.000Z",
"finished_at": "2026-10-01T09:42:01.000Z",
"duration_ms": 94120,
"result": { "accounts": ["alice.moreee", "bob.k"], "rows_detected": 2, "rows_read": 2 },
"failure": null
}
A warm-up abandoned after three interruptions:
{
"job_id": "job_8813",
"type": "warm_up",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": "alice.moreee",
"status": "needs_review",
"created_at": "2026-10-01T10:15:02.000Z",
"dispatched_at": "2026-10-01T10:15:14.000Z",
"finished_at": "2026-10-01T10:38:40.000Z",
"duration_ms": null,
"result": null,
"failure": { "reason": "excessive_user_takeover" }
}
List a phone's jobs — GET /v1/devices/{public_id}/automations?limit=20
(scope: read), newest first. limit is 1–100 (default 20). Only jobs launched
through the API are listed.
curl "https://api.iremotech.com/v1/devices/dev_1a2b3c4d5e6f7a8b/automations?limit=20" \
-H "Authorization: Bearer $API_KEY"
{
"jobs": [
{
"job_id": "job_8814",
"type": "warm_up",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": "alice.moreee",
"status": "queued",
"created_at": "2026-10-01T11:02:40.000Z",
"dispatched_at": null,
"finished_at": null,
"duration_ms": null,
"result": null,
"failure": null
},
{
"job_id": "job_8812",
"type": "warm_up",
"device": "dev_1a2b3c4d5e6f7a8b",
"account": "alice.moreee",
"status": "completed",
"created_at": "2026-10-01T10:15:02.000Z",
"dispatched_at": "2026-10-01T10:15:14.000Z",
"finished_at": "2026-10-01T10:23:01.000Z",
"duration_ms": 467000,
"result": {
"session_duration_s": 420,
"scrolls": 61,
"likes": 4,
"comments": 0,
"reels_viewed": 38,
"reels_skipped": 12,
"soft_resets": 0
},
"failure": null
}
]
}
A phone with no jobs answers { "jobs": [] }. Each item has the same fields as a
single job, and every field is always present (null when it does not apply):
| Field | Meaning |
|---|---|
job_id |
The job's id (opaque string) |
type |
warm_up, account_status or list_accounts |
device |
The device's public_id |
account |
The Instagram username as stored in the dashboard (lowercase; it may differ in case from what you sent), or null for list_accounts |
status |
See the table below |
created_at |
When the job was launched (ISO 8601, UTC) |
dispatched_at |
When the automation service took the job, or null |
finished_at |
When the job finished, or null |
duration_ms |
How long the run took, in milliseconds, or null |
result |
What the job found (see below) when completed, otherwise null |
failure |
{ "reason": "..." } when failed or needs_review, otherwise null |
status |
Meaning |
|---|---|
queued |
Accepted, waiting for the automation service to pick it up (it looks for new jobs every 15 seconds) |
dispatched |
Handed to the automation service: waiting for the phone to be free, or running |
completed |
Finished; result is filled |
failed |
Refused before running, or finished with an error; failure.reason says why |
needs_review |
The automation service gave up (for example excessive_user_takeover after three interruptions) |
expired |
Never picked up: a job still queued 45 minutes after launch (plus a short grace) reads expired. Launch again if you still need it |
failure.reason is a lowercase code in snake_case. The codes to handle:
failure.reason |
Meaning |
|---|---|
excessive_user_takeover |
needs_review: the job was interrupted three times (see the note at the top of this section) |
device_offline |
failed: the phone could not be reached |
missing_target_account |
failed: account was not found on the phone |
rejected_by_dispatcher |
failed: the job was refused before it ran; finished_at stays null. Launch again |
unknown |
No reason was given |
New codes may appear, so treat an unknown one as a generic failure.
completed, failed, needs_review and expired are final. Poll a job every 15 to 30
seconds until it reaches one of them. Only one automation runs on a phone at a time,
so a job can stay dispatched for a while without any visible change: it waits until
no other automation is running on the phone and the phone is not in use (see the note
at the top of this section). After an interruption it stays dispatched until it is
tried again. In rare cases a job stays dispatched without ever reaching a final
status (for example when our operations team stops it by hand); give up polling
after a reasonable time — we suggest two hours — and launch again later: a launch on
the same account answers 409 automation_pending for up to 24 hours after that job
was dispatched, then succeeds.
result per type (new members may be added; ignore the ones you do not know):
type |
result members |
|---|---|
account_status |
account_state — an object with six flags, each "green", "warning" or "unknown": removed_content_and_messaging_issues, what_cant_be_recommended, monetization, features_you_cant_use, who_dont_follow_you, under_18; post_rotation_retries (integer) |
list_accounts |
accounts (the usernames found), rows_detected, rows_read |
warm_up |
session_duration_s (the length actually run), scrolls, likes, comments, reels_viewed, reels_skipped, soft_resets |
Every counter (rows_detected, rows_read, post_rotation_retries, the warm-up
members) can be null when the run did not report it; accounts is always an array.
Tokens
A warm_up uses your agency's automation tokens, charged like a scheduled warm-up. When
tokens are enabled for your agency, a warm-up is launched only when your balance covers
its maximum cost: the requested session length plus 120 seconds of overhead, at your
agency's token rate. Warm-ups you launched through the API that have not finished yet
count against your balance until they finish. Otherwise the launch answers
402 insufficient_tokens and nothing is queued.
A completed warm-up is charged for the time it actually ran, at most the session length
plus 120 seconds. A warm-up that does not complete (failed, needs_review or
expired) is not charged. account_status and list_accounts use no tokens, and
reading jobs uses none. How tokens work: the tokens guide.
Daily budgets
Each launch that is accepted (202) counts as one action toward your daily
actions budget (§10), exactly like one request to POST /v1/devices/{public_id}/actions
(and is billed as one action where usage-based billing applies); a refused launch
counts nothing. When your daily actions or active_minutes budget is used up (the
same check as an action), launches answer 429 quota_exceeded.
Launching does not count toward active_minutes — the automation, not you, uses the
phone. Reading jobs counts toward no budget.
Limits
| What | Limit |
|---|---|
account_status on one account |
2 per 30 minutes |
account_status across your agency |
50 different accounts per hour |
list_accounts on one phone |
1 per calendar day (Europe/Berlin time) |
warm_up on one account |
1 per 60 minutes |
Pending warm_up / account_status |
one queued or dispatched job of the type per account |
Pending list_accounts |
one queued or dispatched job per phone |
| Launches on one phone | 10 per minute, with a burst of 3 |
| Launches across your account | 2 per second, with a burst of 10 |
| Reading jobs across your account (one job, or a phone's list) | 10 per second, with a burst of 20 |
| Request body | 64 KB (65,536 bytes) |
There is no per-phone pause between status checks: to check every account on a
phone, launch one account_status per account (each account is still limited to
2 checks per 30 minutes).
A request over a limit gets 429 rate_limited with a Retry-After header (seconds to
wait). Over the launch or read limits, the response also has the X-RateLimit-*
headers (§9). Over a per-automation limit (status checks, warm-ups, listings) it has
only Retry-After, and that can be minutes, or for a listing until midnight
Europe/Berlin time. A launch while the same job is still pending gets
409 automation_pending (see below). Every launch request to one of your devices
counts toward the two launch limits, including one rejected for an invalid body.
Reading jobs has its own limit (above), on top of the general request rate of your key and account (§9). A job read may be answered from a short cache, so an answer can be up to 3 seconds old: polling faster than that shows nothing new.
When a launch answers 409 automation_pending
A job of the same type is already queued or running for this account (warm_up,
account_status) or on this phone (list_accounts). That includes a job started from
the dashboard, which this API does not list. The block ends when that job finishes. A
queued job that is never picked up stops blocking after 45 minutes; a job that was
picked up but never reports a result blocks for up to 24 hours after it was picked up.
What to do: wait and launch again later. To see whether the job is yours, list the
phone's jobs with GET /v1/devices/{public_id}/automations; if it is not listed, it was
started from the dashboard, where you can follow it.
Errors
| HTTP | code |
Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized |
Missing or invalid API key | Check the key |
| 402 | insufficient_tokens |
A warm_up your token balance does not cover; nothing was queued |
Top up tokens, or launch a shorter session_duration_s |
| 403 | forbidden |
The key does not have the scope (automations to launch, read to read jobs), or the key or account is not active (including your agency's API access being suspended) |
Without the scope: create a new key (see the note above). Otherwise check detail |
| 404 | device_not_found |
No such device in your account (launching, or listing a phone's jobs) | Check the public_id |
| 404 | account_not_found |
account is not an active account on this phone right now (deleted, paused or removed in the dashboard, or on another phone) |
Check the username and the phone; manage accounts in the dashboard |
| 404 | job_not_found |
No such job in your account (reading a job) | Check the job_id |
| 409 | automation_pending |
The same automation is already queued or running (warm_up, account_status: for this account; list_accounts: on this phone), including one started from the dashboard |
See "When a launch answers 409 automation_pending" above |
| 422 | invalid_action |
The request failed validation: not a JSON object, unknown type or field, account missing, not allowed or not a valid username, session_duration_s not an integer, out of 60–900 or sent for another type, rotate_ip not a boolean or sent for list_accounts, body larger than 64 KB; or limit out of 1–100 when listing |
Fix the request |
| 429 | rate_limited |
Over a limit of the table above, or the general request rate (§9) | Wait Retry-After seconds (for a per-automation limit this can be minutes or hours), then retry |
| 429 | quota_exceeded |
Your daily actions or active_minutes budget is used up (launching only) |
Retry after resets_at (§10) |
| 503 | upstream_unavailable |
Automations could not be reached right now, launches are temporarily paused, or the service is busy | Retry with a growing delay (see below) |
A launch is not idempotent. When a launch answers 503 upstream_unavailable, it
may or may not have been queued. Some of these answers say in detail that nothing was
queued (launches temporarily paused, or the service busy, the latter with a
Retry-After header); the safe handling is the same for all of them. Retry the same
request with a growing delay (for example 30 seconds, then 1 to 2 minutes), not in a
tight loop. If the retry answers 409 automation_pending, your first launch was most
likely queued: look for it with GET /v1/devices/{public_id}/automations. If it is not
listed, the same automation was started from the dashboard, and the block lifts when
that job ends. A launch on a phone that is not set up for automations yet keeps
answering 503 until it is. A read that answers 503 changed nothing; retry it later.
(invalid_action is this API's code for any request that fails validation.) When
the API rejects the body itself, the response has an errors array with one item per
problem: loc says where (["body", "rotate_ip"]; ["body"] for a rule between
fields, such as a missing account) and msg says what. A launch rejected further
along has no errors array; its detail says what was wrong. Example — rotate_ip
sent as a string:
{
"type": "https://errors.kernel-api.iremotech.com/invalid_action",
"title": "invalid_action",
"status": 422,
"code": "invalid_action",
"detail": "request validation failed",
"errors": [
{
"type": "bool_type",
"loc": ["body", "rotate_ip"],
"msg": "Input should be a valid boolean"
}
]
}
Example — a warm_up without account:
{
"type": "https://errors.kernel-api.iremotech.com/invalid_action",
"title": "invalid_action",
"status": 422,
"code": "invalid_action",
"detail": "request validation failed",
"errors": [
{
"type": "value_error",
"loc": ["body"],
"msg": "Value error, account is required for warm_up and account_status"
}
]
}
Example — a warm-up the token balance does not cover:
{
"type": "https://errors.kernel-api.iremotech.com/insufficient_tokens",
"title": "insufficient_tokens",
"status": 402,
"code": "insufficient_tokens",
"detail": "a warm_up needs a token balance that covers the session length plus 120 seconds of overhead"
}
Example — automations could not be reached during a launch:
{
"type": "https://errors.kernel-api.iremotech.com/upstream_unavailable",
"title": "upstream_unavailable",
"status": 503,
"code": "upstream_unavailable",
"detail": "automations could not be reached right now and this launch may have been queued; retry the same request with a growing delay: a 409 automation_pending on the retry most likely means it was queued (an automation started from the dashboard also answers 409)"
}
5. Live stream — wss://api.iremotech.com/v1/devices/{public_id}/stream?token=<key> (scope: stream)
A WebSocket that pushes the device screen as a series of binary JPEG frames (one JPEG per WebSocket message). Open it, then decode each binary message as an image.
Authenticate by passing your key as the token query parameter (not the
Authorization header) — WebSocket handshakes from browsers can't set headers,
so the key goes in the URL. Use wss:// (TLS) so the URL isn't sent in the clear.
Optional query param: fps to cap the frame rate. A rejected handshake (bad key,
missing stream scope, unknown device, suspended account, max_active_devices
reached, too many connects) shows up as a failed connection — HTTP 403 — with no
detail; call GET /v1/devices/{public_id} with a key that also has the read
scope to see why.
Python (websockets):
import asyncio, urllib.parse, websockets
async def watch(device_id, key):
token = urllib.parse.quote(key)
url = f"wss://api.iremotech.com/v1/devices/{device_id}/stream?token={token}"
async with websockets.connect(url) as ws:
i = 0
async for message in ws: # each message is one JPEG frame (bytes)
with open(f"frame_{i:04d}.jpg", "wb") as f:
f.write(message)
i += 1
asyncio.run(watch("dev_1a2b3c4d5e6f7a8b", "irt_live_..."))
Browser / Node.js (ws):
import WebSocket from 'ws'
const url = `wss://api.iremotech.com/v1/devices/${id}/stream?token=${encodeURIComponent(key)}`
const ws = new WebSocket(url)
ws.on('message', frame => {
// `frame` is a Buffer holding one JPEG image
})
The stream self-throttles and drops stale frames under backpressure, so you always get the freshest screen rather than a growing backlog. Time spent streaming counts toward your active-minutes budget (see Limits).
Close codes
If the connection is refused or dropped, the WebSocket close code says why:
| Code | Meaning |
|---|---|
4401 |
unauthorized |
4403 |
forbidden (scope, suspended, or unpaid usage) |
4404 |
not_found |
4290 |
quota_or_limited |
4402 |
budget_exceeded — monthly spend cap reached |
1011 |
device unreachable |
Frames arrive only when the screen changes. A phone that is sitting still produces no new frames — that is normal, not a dead connection. So that the socket is never silent, the stream re-sends the last frame after a few seconds without a change (a normal binary JPEG, identical to the previous one). Keep the connection open; do not reconnect because frames stopped arriving — a reconnect costs the handshake plus the wait for the next frame, and a control sent while reconnecting only becomes visible once the new stream delivers.
5b. Live control — wss://api.iremotech.com/v1/devices/{public_id}/control?token=<key> (scope: control)
A WebSocket for live, hands-on control: send the pointer as it moves and the
phone's cursor follows in real time, exactly like the dashboard. Use it when a
person is driving the phone from your UI (a CRM screen, a support console);
keep using POST …/actions for automation.
Authenticate with the token query parameter, like the stream. Coordinates are
snapshot pixels — the same space every action uses, and the size of the
frames the live stream delivers. The first message from the server tells you
both sizes:
{"type":"ready","logical":{"w":375,"h":667},"snapshot":{"w":406,"h":720},"max_messages_per_second":120}
Messages you send (one JSON object per message):
| Message | Meaning |
|---|---|
{"type":"mouse","x":203,"y":640,"buttons":0} |
Pointer at (x, y). buttons 1 = pressed, 0 = released. A tap is buttons:1 then buttons:0; a swipe or drag is a press, moves with buttons:1, then a release. |
{"type":"scroll","x":203,"y":400,"dy":-3} |
Scroll at (x, y) by dy notches — same sign convention as the scroll action (§4), clamped to ±20 per message; a mouse wheel is about one notch per click, so send dy = ±1 per wheel event. |
{"type":"key","key":"Return"} |
One key, same vocabulary as the key action. |
{"type":"text","text":"hello"} |
Type text, same rules as the text action. The server answers {"type":"typed","skipped":[…]} with any characters the device could not type. |
{"type":"ping"} |
Optional; answered with {"type":"pong"}. |
Messages you receive: ready (once), pong, typed, and
{"type":"error","code":"…","detail":"…"} for a message that was not applied
(invalid_frame, rate_limited, device_error, hold_timeout) — the channel
stays open.
Browser example — forward pointer events from the element that shows the
live stream (img here, sized to the snapshot):
const url = `wss://api.iremotech.com/v1/devices/${id}/control?token=${encodeURIComponent(key)}`
const ws = new WebSocket(url)
let snapshot = null
ws.onmessage = (e) => {
const m = JSON.parse(e.data)
if (m.type === 'ready') snapshot = m.snapshot
}
const img = document.querySelector('#screen') // the <img> fed by the stream
img.style.touchAction = 'none' // or CSS `touch-action: none`: let the
// element keep the pointer events instead
// of scrolling/zooming the page
const pos = (ev) => {
const r = img.getBoundingClientRect()
return {
x: Math.round((ev.clientX - r.left) * snapshot.w / r.width),
y: Math.round((ev.clientY - r.top) * snapshot.h / r.height),
}
}
const send = (ev, buttons) => {
if (!snapshot || ws.readyState !== WebSocket.OPEN) return
ws.send(JSON.stringify({ type: 'mouse', ...pos(ev), buttons }))
}
let down = false
img.addEventListener('pointerdown', (ev) => { down = true; img.setPointerCapture(ev.pointerId); send(ev, 1) })
img.addEventListener('pointermove', (ev) => send(ev, down ? 1 : 0))
img.addEventListener('pointerup', (ev) => { down = false; send(ev, 0) })
img.addEventListener('pointercancel', (ev) => { down = false; send(ev, 0) })
ws.onclose = (e) => {
down = false
if (e.code === 4409) showBanner('Another session took control of this phone') // do NOT auto-reconnect
else if (e.code === 4401 || e.code === 4403) showError(e.reason) // fix the key / scopes first
else setTimeout(reconnect, backoff()) // 1011, 4290, 1006 (network or a refused handshake): retry with backoff
}
Keep the live stream (§5) open next to the channel: it is how the operator sees
the result, and ready.snapshot is exactly the size of the frames it delivers,
so the same element serves both.
What counts. Each gesture (a press-to-release, a scroll, a key, a text) is
one action in your daily actions budget — the same as the equivalent REST
action. Moving the pointer is free. While the channel is open the device counts
as in use (active minutes, max_active_devices), like a stream; a stream and
a control channel on the same device count as one device in use.
Rules.
- One control channel per device: opening a second one closes the first with
code
4409("replaced"). Reloading your page just works. - Up to 120 messages per second per connection. Above that, pointer moves are
dropped (the gesture still lands where you released) and anything else is
answered with
error rate_limited. A sustained flood closes the channel (4290). Repeated rejections in a burst share oneerrorreply, so do not expect one answer per message you send. - A message is at most 8 KiB — a larger one closes the channel with code
4400— and atextmessage at most 4096 characters, like thetextaction; a longer one is answered witherror invalid_frame. - If the key or the account is suspended mid-session, the channel closes
4290(or4401if the key was revoked) at the next check — reconnecting will not help until the account is active again. - If your client sends no further pointer, scroll, key or text message for
10 s while pressed (a
pingdoes not count), the server releases the button and sendserror hold_timeout. If your client disconnects while pressed, the button is released too. - The key travels in the URL (there is no header on a browser WebSocket). Use a
dedicated key with only the
streamandcontrolscopes and an IP allowlist for pages that talk to the API directly, or proxy the socket through your backend.
Getting the lowest latency. The phone's pointer travels to each point you
send and needs a moment to settle before a press registers. If you press right
after a jump across the screen, the press is applied once the pointer has
arrived and settled, and the release no earlier than a short minimum hold — so
the tap still registers, at the cost of that wait. Taps are fastest when the
pointer is already at the target: send pointer moves as the hand moves (as a
mouse does) rather than one jump followed immediately by a press. The first
press after connecting is the slowest case (the server does not yet know where
the pointer is). Sending a hover move as soon as ready arrives lets the pointer
settle before the operator's first tap, as long as that tap does not follow the
hover within the same instant.
If the connection is refused. A handshake the server rejects (bad or
revoked key, missing control scope, unknown device, suspended account, daily
budget or max_active_devices reached, too many connects) shows up in a
browser as a failed connection — HTTP 403 — with no close code and no detail.
To find out why, call GET /v1/devices/{public_id} and
GET /v1/devices/{public_id}/snapshot with a key that also has the read
scope (your main key; a stream+control-only key gets 403 forbidden there,
with detail "scope 'read' required"): they return the reason as a normal API
error (401/403/404/429).
Connects to one device are limited to a few per minute, so a client that
reconnects in a tight loop refuses itself.
Reconnecting. Once the channel is open, the server closes it with a code that tells you what to do:
| Code | Meaning | What to do |
|---|---|---|
4409 |
replaced — another session opened a control channel on this device | Do not reconnect automatically: two tabs reconnecting on 4409 expel each other forever. Tell the operator and let them decide. |
1011 |
device unreachable, or the server gave up writing to a client that stopped reading | Reconnect with an increasing delay (start at a second). |
4290 |
daily budget or max_active_devices reached, rate limited, flooding, or the key/account was suspended |
Reconnect with an increasing delay; if it keeps happening, check GET /v1/usage. |
4401 / 4403 |
key revoked or expired, account deactivated, or control scope removed |
Do not retry until the key, scopes or account are fixed. |
4400 |
a message over 8 KiB | Fix the client; reconnect. |
"Device not found" (4404) only ever happens at connect time, so it arrives as
a refused connection (above), never as a close code on an open channel.
A page reload or a lost network simply reconnects: the newest channel wins (§ Rules), so you never have to wait for the old one to time out.
Integration checklist
- Forward
pointerdown/pointermove/pointerup/pointercancelfrom the element that shows the stream, scaled toready.snapshot;touch-action: noneon that element. - One press =
buttons: 1, one release =buttons: 0; never leave a press without a release (the server releases it after 10 s, but the operator sees a stuck finger meanwhile). - Handle
oncloseas in the table above; never auto-reconnect on4409. - Keep the stream open alongside; open one control channel per phone per operator, when they start driving it, and close it when they stop (an open channel counts as the device being in use).
- Use a dedicated key with only
stream+controland an IP allowlist for pages that talk to the API directly, or proxy the socket through your backend. - Keep using
POST …/actionsfor anything scripted; the channel is for a human hand.
6. Upload a file (scope: upload)
There are two ways to upload. Use the ticket flow — it is the recommended path and the only way to send files larger than 100 MB (up to 300 MB).
Recommended — the upload ticket
POST /v1/devices/{public_id}/media/ticket
Uploading in two steps lets you send the file directly to the upload endpoint, bypassing the 100 MB request-size limit of the older direct-body route.
Step 1 — get a ticket:
curl -X POST "https://api.iremotech.com/v1/devices/$ID/media/ticket" \
-H "Authorization: Bearer $KEY"
{
"upload_url": "https://upload.iremotech.com/v1/devices/<...>/upload",
"ticket": "<short-lived token>",
"max_bytes": 314572800,
"expires_at": "2026-09-01T10:12:00Z"
}
Step 2 — send the raw file bytes to upload_url, authenticated with the
ticket. Append the file name as ?filename=, set
Content-Type: application/octet-stream, and send a Content-Length (chunked
transfer encoding is rejected):
curl -X POST "$UPLOAD_URL?filename=video.mp4" \
-H "Authorization: Bearer $TICKET" \
-H "Content-Type: application/octet-stream" \
--data-binary @video.mp4
A ticket authorises one upload — mint one ticket per file. A second upload
with the same ticket is rejected with 409 ticket_already_used. The upload must
start before expires_at. The upload endpoint rate-limits to
60 requests/min and 4 concurrent uploads per key — honor Retry-After
on a 429 and keep at most 4 uploads in flight.
max_bytes is set per ticket and may be lower than the 300 MB ceiling —
always read it from the response instead of assuming the maximum. You can request
a smaller limit for a ticket by sending an optional JSON body when minting it:
{ "max_bytes": 52428800 }
max_bytes must be a positive integer no greater than 314572800 (300 MB); the
returned max_bytes is what the upload endpoint enforces. It may also come back
lower than you requested when it is capped by your remaining API budget for the
period (your funded wallet balance plus the day's included upload allowance) — so
always read it from the response. An upload that exceeds the returned max_bytes
is refused with 402 upload_budget_exceeded when the ceiling was your budget (top
up to restore), or 413 payload_too_large when it was the absolute size limit.
Python:
import requests
# 1. get a ticket
t = requests.post(
f"https://api.iremotech.com/v1/devices/{device_id}/media/ticket",
headers={"Authorization": f"Bearer {key}"},
).json()
# 2. upload directly to the returned URL (no 100 MB limit)
with open("video.mp4", "rb") as f:
r = requests.post(
t["upload_url"],
params={"filename": "video.mp4"},
headers={
"Authorization": f"Bearer {t['ticket']}",
"Content-Type": "application/octet-stream",
},
data=f, # streamed, not loaded into memory
)
r.raise_for_status()
Deprecated — direct body
POST /v1/devices/{public_id}/media?filename=<name>
Sends the raw bytes through the API in a single request. Capped at 100 MB and kept only for backward compatibility — prefer the ticket flow above.
curl -X POST "https://api.iremotech.com/v1/devices/$ID/media?filename=photo.jpg" \
-H "Authorization: Bearer $KEY" \
--data-binary @photo.jpg
7. Usage — GET /v1/usage (scope: read)
curl https://api.iremotech.com/v1/usage -H "Authorization: Bearer $KEY"
{
"active_minutes": { "used": 12, "budget": 4800, "remaining": 4788 },
"actions": { "used": 340, "budget": 200000, "remaining": 199660 },
"snapshots": { "used": 15, "budget": 20000, "remaining": 19985 },
"uploads": { "used": 2, "budget": 1000, "remaining": 998 },
"max_active_devices": 10,
"resets_at": "2026-07-14T00:00:00+00:00",
"billing": {
"period": "2026-10",
"resets_at": "2026-11-01T00:00:00+01:00",
"enforcement_mode": "enforce",
"cap_micros": 10000000,
"spent_micros": 0,
"reserved_micros": 0,
"free_remaining_today": { "actions": 1000, "frames": 144000, "upload_bytes": 200000000 },
"price_book_version": 1
}
}
Budgets are for the current UTC day and reset at resets_at.
billing is null until usage-based billing is enabled for your account. Its
resets_at is the start of the next billing month (Europe/Madrid); the daily
budgets above still reset at UTC midnight.
Usage-based billing and pricing
Your API usage above a generous included (free) tier is billed monthly. The included tier is per device, per day, so it grows with your fleet.
| Metered unit | Included free / device / day | Price above the included tier |
|---|---|---|
| Actions | 500 actions | $0.10 per 1,000 actions |
| Frames (snapshots + live-stream frames) | 72,000 frames | $0.30 per 1,000 frames |
| Uploads | 100 MB | $0.10 per GB |
- The included tier each day is
per-device rate × your device count that day. Usage up to it is free; only usage above it is billed. - How you're charged. Your metered usage is drawn from your wallet balance as you use the API, and each month we issue an invoice for the month's total — which has already been collected through the month, so the invoice is a record, not a separate payment.
- Strictly prepaid. Your API spend cap equals your funded wallet balance. There is no credit buffer and no grace period: usage above the included tier can only be spent from funds you have already added. You can see your balance in the dashboard under Billing → Wallet.
- When your funds run out, billable calls above the included tier return
402 budget_exceeded(4402on the live stream). Your read-only calls, the included (free) tier, and remote access to your devices from the dashboard keep working normally. - Access is restored automatically as soon as you top up — no action is needed beyond adding funds.
- Periods run in Europe/Madrid and are invoiced after the month closes.
- The
billingblock above shows your month-to-date spend, your cap, and today's remaining included allowance per unit. Your dashboard shows today's usage against the included tier and your cost for the month.
8. Errors
Every error is an RFC 7807 problem document with Content-Type: application/problem+json:
{
"type": "https://errors.kernel-api.iremotech.com/forbidden",
"title": "forbidden",
"status": 403,
"code": "forbidden",
"detail": "scope 'control' required"
}
Integrate against code (stable), not detail (human-readable, may change).
| HTTP | code |
Meaning |
|---|---|---|
| 400/422 | invalid_action |
The request body failed validation |
| 401 | unauthorized |
Missing or invalid API key |
| 402 | budget_exceeded |
Your funded wallet balance (your API spend cap) is used up; read-only calls and remaining free allowance still work; top up to restore, honour Retry-After |
| 402 | insufficient_tokens |
A warm_up your agency's automation tokens do not cover; nothing was queued (§4b) |
| 402 | upload_budget_exceeded |
A media upload would exceed your remaining API budget for the period (your funded wallet balance plus the day's included upload allowance); the upload is refused and nothing is charged — top up to restore, then retry. This is a budget limit, distinct from the absolute size limit (413) |
| 403 | forbidden |
The key lacks the scope the endpoint needs, or the key or account is not active (suspended, revoked, expired, or the request's IP is not in the key's allowlist) |
| 403 | device_blocked |
Access to this device is temporarily blocked; the device is reachable but does not accept commands or screenshots right now |
| 404 | device_not_found |
No such device for your account |
| 404 | account_not_found |
The Instagram account is not an active account on that phone right now (§4b) |
| 404 | job_not_found |
No such automation job for your account (§4b) |
| 409 | automation_pending |
The same automation is already queued or running (§4b) |
| 409 | ticket_already_used |
Upload ticket was already used — mint a new one per file |
| 413 | payload_too_large |
Upload exceeded the absolute size limit (the ticket's max_bytes / the 300 MB ceiling). If you are within the size limit but out of budget, the API returns 402 upload_budget_exceeded instead |
| 422 | command_rejected |
Device reachable but rejected the command |
| 422 | label_limit_reached |
Editing a device would exceed your account's 200 labels (§3b) |
| 429 | rate_limited / quota_exceeded / max_active_devices_reached |
Slow down, or a limit was hit |
| 502 | upload_failed |
Upload could not be completed downstream |
| 503 | device_offline |
Device currently unreachable |
| 503 | accounting_unavailable |
Usage accounting temporarily unavailable; retry after Retry-After |
| 503 | rename_unavailable |
The device's server did not accept a new custom_name; nothing was changed (§3b) |
| 503 | upstream_unavailable |
Device settings could not be saved right now (§3b; safe to retry), or automations could not be reached (§4b; a launch is not idempotent: retry with a growing delay, and a 409 automation_pending on the retry most likely means the first launch was queued) |
| 504 | kernel_timeout |
Device did not respond in time |
| 500 | internal |
Unexpected server error |
A 403 whose body is error code: 1010
Every error the API returns is a JSON object with a code. If you get a 403 whose body is
the plain text error code: 1010 instead, the request was refused by the network layer in
front of the API, before it reached us. It is not about your API key or its scopes: it is the
User-Agent your HTTP client sent. This happens with the default User-Agent of Python's
built-in urllib (Python-urllib/3.x). Common clients such as curl, requests, httpx,
axios, fetch, Go's net/http and OkHttp are not affected.
The fix is to send your own User-Agent header:
import urllib.request
req = urllib.request.Request(
"https://api.iremotech.com/v1/devices",
headers={
"Authorization": f"Bearer {API_KEY}",
"User-Agent": "my-integration/1.0",
},
)
9. Rate limits
Requests pass through several token-bucket layers (per key, per account, per device,
per endpoint). When any of these layers is exceeded you get 429 rate_limited with:
Retry-After: seconds to wait before retrying.X-RateLimit-Remaining/X-RateLimit-Limit-Layer: which layer tripped and what's left.
The per-automation limits of §4b (status checks, warm-ups, listings) are not one of
these layers: over one of them you get 429 rate_limited with only Retry-After, which
can be minutes, or for a listing until midnight Europe/Berlin time.
Back off on 429 and honor Retry-After. The live stream and live control
channel are limited per device on connects (a few per minute); the control
channel also caps messages per connection (see §5b).
Editing a device (§3b) has two limits of its own, on top of the limits every request counts toward:
| Limit | Rate | Burst |
|---|---|---|
| Edits of one device | 10 per minute | 5 |
| Edits across your account | 5 per second | 20 |
Launching an automation (§4b) has two limits of its own too, plus the per-automation limits listed in §4b, and reading automation jobs has one:
| Limit | Rate | Burst |
|---|---|---|
| Launches on one device | 10 per minute | 3 |
| Launches across your account | 2 per second | 10 |
| Reading automation jobs across your account | 10 per second | 20 |
10. Limits (daily budgets)
Beyond rate limits, each account has daily budgets that reset at UTC midnight. The budgets are per device — the pool for your whole account is the per-device rate × your number of devices, so a larger fleet gets proportionally more headroom.
| Budget | What it measures |
|---|---|
active_minutes |
Minutes a device is in use (streaming or receiving actions) |
actions |
Number of actions |
snapshots |
Number of screenshots |
uploads |
Number of file uploads |
max_active_devices |
How many devices you may have in use at the same time |
Check GET /v1/usage to see your current usage and remaining budget. Exceeding a
daily budget returns 429 quota_exceeded (or max_active_devices_reached for
concurrency); it clears at the next UTC midnight (resets_at). Limits are
configurable per account — contact us if you need them raised.
Editing a device (§3b) does not count toward any daily budget. Launching an automation (§4b) counts as one action when the launch is accepted; reading automation jobs counts toward no budget.
11. Changes
Changes within /v1 are additive and backward-compatible. When a behaviour
change is unavoidable it is published on two pages:
- Announced changes — changes that are announced but not yet in effect, with what to do to be ready. If the API is integrated into an automated workflow, check this page at least once a week.
- Changelog — changes that are already live, newest first.