API Referencefarm-profiles

Get a farm profile

Fetch a single farm profile by its profile_id, including its phone status and email.

Rate limit: 200 requests per minute per team.

Authentication

X-API-Keystring
API Key authentication via header

Path parameters

profile_idstringRequiredformat: "uuid"

Response

Successful Response
profile_idstring
Unique profile identifier.
profile_namestring

Internal display name for the profile. Set via account_name at creation; defaults to username.

tiktok_usernamestring

The TikTok handle linked to this profile. Mutable — may change if the handle is renamed on TikTok.

created_atdatetime or null

Profile creation time as an ISO-8601 timestamp (UTC). null until provisioning records it.

phone_idstring or null

Cloud-phone identifier hosting this profile.

statusenumDefaults to configuring

Lifecycle status of the profile.

  • configuring — phone is being provisioned and the social account is being set up.
  • retrying — initial setup hit a snag; we’re auto-recovering on the backend. No action needed.
  • cold — accounts are logged in but lack the history needed to start posting; no warmup runs have happened yet.
  • warming — a warmup task is actively running on the phone (~15–30 minutes). Returns to warm when it finishes.
  • warm — resting state during the warmup phase (a ~1-week schedule of warmup tasks), between runs. Not postable and not terminal — oscillates with warming until enough runs complete.
  • ready — at least 7 successful warmup tasks have completed over a span of at least 7 days; the profile is now postable. Maintenance warmups may still cycle it back through warming and return it to ready.
  • following: a follow task is actively running on the phone. Transient; returns to its prior resting state (cold/warm/ready) when it finishes.
  • posting: a post is actively uploading/publishing on the phone. Transient; returns to its prior resting state when it finishes.
  • failed — recovery exhausted; this profile won’t be salvaged. Terminal. Create a new profile to try again.
  • deactivated — profile is no longer active. Terminal.

Transitions: configuring → cold → warming ↔ warm → ready. Once ready, maintenance runs flip it through warming and back to ready. following and posting are transient busy states any active profile can briefly enter and then leave. configuring may pass through retrying and back, or terminate at failed. Any state can transition to deactivated.

platformslist of strings or null

Two-element array: [social_platform, auth_method], e.g. ['tiktok', 'sms'] (default), ['tiktok', 'google'], or ['tiktok', 'outlook'].

biostring or null

Account bio/about text set on the profile. null until the phone is provisioned, or if none was provided at creation.

profile_picture_urlstring or null

HTTPS URL of the image set as the account’s profile picture. null until the phone is provisioned, or if none was provided at creation.

accountslist of objects

Platform accounts on this phone (TikTok, plus its linked email for email-backed accounts). Empty array until the phone is provisioned.

Errors

404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error