API docs

The PhoneRun API lets your own tools see your team's phones, hand a person a link that opens one, and read the activity log and monthly usage. It answers in JSON. It does not tap, type or post on a phone: a person still does the work in the browser, as the acceptable use rules ask.

Keys

The owner or a manager makes a key on the account page, under API keys. The key is shown once. Send it on every request:

Authorization: Bearer pr_...

A key acts for its team with a manager's reach over phones. It cannot change the team, folders or billing. Revoke a key on the account page and it stops working at once. A team has up to 10 keys.

List phones

GET https://phonerun.dev/api/v1/phones
GET https://phonerun.dev/api/v1/phones?online=1

The phones your team rents right now. With online=1 each phone also says whether it is online, which takes a moment longer.

{ "phones": [
  { "id": 12, "label": "PR-01", "folder": "Coffee roaster", "plan": "monthly", "ends_at": null, "online": true }
] }

List folders

GET https://phonerun.dev/api/v1/folders
{ "folders": [ { "id": 3, "name": "Coffee roaster" } ] }

Open a phone

POST https://phonerun.dev/api/v1/phones/12/open

Answers with a link that opens the phone in a browser, the same as the Open phone button. The link works for 8 hours, or until the rental ends if that is sooner. Give it to the person who will use the phone. The open goes in the activity log under the key's name. One key can open phones up to 120 times an hour.

{ "url": "https://hub.phonerun.dev/view?d=...&grant=...", "expires_at": "2026-11-17T06:30:00.000Z" }

Activity log

GET https://phonerun.dev/api/v1/activity?limit=100

The latest events, newest first, up to 500. Actions include opened, closed (with the session length), moved, and changes to the team, folders and keys. It never holds what was done on a phone.

{ "events": [
  { "at": "2026-11-16T21:10:04.000Z", "actor": "dana@agency.com", "action": "closed", "phone": "PR-01", "detail": "48 minute session" }
] }

Usage

GET https://phonerun.dev/api/v1/usage?month=2026-11

Sessions and seconds on the phones in a month, by phone and by person. A session counts in the month it started, in UTC. Without month it is this month. The same report is on the account page, with a CSV to download.

{ "month": "2026-11", "sessions": 14, "seconds": 40210,
  "phones": [ { "phone": "PR-01", "sessions": 9, "seconds": 28800 } ],
  "people": [ { "person": "dana@agency.com", "sessions": 6, "seconds": 21000 } ] }

Errors

A wrong or revoked key gets 401. A phone that is not on your team gets 404. Too many opens get 429. Each error has a plain error message.

Example

curl -H "Authorization: Bearer $PHONERUN_KEY" https://phonerun.dev/api/v1/phones

Questions or something missing? Write to support@phonerun.dev.

Last updated November 16, 2026.