Execution Model

Phonefarm exposes a process-oriented public API, but the underlying runtime is a layered system.

The Public Model

For callers, the lifecycle is:

Submit a request.
Receive an accepted response.
Observe process.updated callbacks.
Poll the process record for current state.
Cancel with a process-aware endpoint if needed.

The Internal Flow

Under the hood, the flow is:

public request
  -> capability request row
  -> planned actions
  -> child queue items
  -> claimed work on a phone
  -> isolated run container
  -> executor action(s)
  -> process sync
  -> callback + pollable state

Key Objects

Term	Meaning
Process	The public execution object returned to callers. Backed by `capability_requests`.
Capability	A higher-level unit of work such as `keyword_warmup` or `maintenance`.
Queue item	An internal execution record that the worker can claim and run.
Run container	An isolated worker container for one claimed queue item on one phone.
Callback	A best-effort push notification with normalized process state.

Primary Public Entrypoints

Use these for new integrations:

POST /capability-requests/enqueue
POST /maintenance/requests
GET /processes/{process_id}
POST /processes/{process_id}/cancel

Compatibility Entrypoints

These older endpoints work directly with queue items:

POST /ingest
POST /cancel

Use them only if you need direct post-video queue-item behavior.

Routing Modes

Capability requests accept a target with one routing mode:

Routing mode	Meaning
`direct`	Target a specific `phone_id` and `account_id` for immediate direct execution readiness.
`queue`	Create work that will be materialized and claimed later.
`group`	Fan out across explicit `phone_ids` and or `account_ids`.

Not every capability supports every routing mode. See Capability Registry.

Run Modes

Run mode	Meaning
`manual`	Allowed for all currently implemented public capabilities.
`unattended`	Allowed only for capabilities that are both permitted and live verified.

Important: fyp_warmup is live-verified for unattended watch-only use, but only when like_probability, save_probability, and comment_probability are each explicitly 0. fyp_comment_growth and maintenance remain manual-only.

Callbacks Versus Polling

Callbacks are useful for event-driven systems, but they are not the source of truth:

callbacks are best-effort
callback failure does not fail the originating API request
polling GET /processes/{process_id} is the authoritative view

Getting Started

Concepts

API

OpenAPI Reference

Guides

Reference

Execution Model

Execution Model

The Public Model

The Internal Flow

Key Objects

Primary Public Entrypoints

Compatibility Entrypoints

Routing Modes

Run Modes

Callbacks Versus Polling

Read Next

​Execution Model

​The Public Model

​The Internal Flow

​Key Objects

​Primary Public Entrypoints

​Compatibility Entrypoints

​Routing Modes

​Run Modes

​Callbacks Versus Polling

​Read Next

Execution Model

The Public Model

The Internal Flow

Key Objects

Primary Public Entrypoints

Compatibility Entrypoints

Routing Modes

Run Modes

Callbacks Versus Polling

Read Next