API Referencefarm-profiles

Update a farm profile

Updates the bio and/or profile_picture_url stored for a farm profile. Provide either or both; omitted fields are left unchanged.

Rate limit: 30 requests per minute per team.

Authentication

X-API-Keystring
API Key authentication via header

Path parameters

profile_idstringRequiredformat: "uuid"

Request

This endpoint expects an object.
biostring or nullOptional

New account bio/about text to set on the profile. Omit to leave unchanged.

profile_picture_urlstring or nullOptional
HTTPS URL of a new image to set as the account's profile picture. Omit to leave unchanged.

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 nullOptional

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

phone_idstring or nullOptional

Cloud-phone identifier hosting this profile.

statusenumOptionalDefaults 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 ~3-day schedule of warmup tasks), between runs. Not postable and not terminal — oscillates with warming until enough runs complete.
  • ready — at least 3 successful warmup tasks have completed over a span of at least 3 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.
  • banned — the platform banned the account. Terminal. The profile stays in your records but is removed from your monthly billing quantity, with prorated credits applied for the unused portion of the month.

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 or banned.

warmup_countinteger or nullOptional

Number of successful warmup runs completed so far. null until the phone is provisioned. Compare against warmups_required to gauge progress toward ready.

warmups_requiredintegerOptionalDefaults to 3

Successful warmup runs required, spanning at least 3 days, before the profile becomes ready.

last_warmup_atdatetime or nullOptional

ISO-8601 timestamp (UTC) of the most recent warmup run. null before the first run.

platformslist of strings or nullOptional

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

biostring or nullOptional

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 nullOptional

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 objectsOptional

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

Errors

400
Bad Request Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error