Recommended workflow

Read usage first

Call get_usage with an empty arguments object.

{}

Copy credits_left, commentMaxLength, likeMin, and find_enabled. If credits_left is too low, stop and tell the user to open Billing.

Get a video URL

If the user already gave you a YouTube or TikTok URL, use it.

If they did not, and find_enabled is true, call find_videos:

{
  "platform": "youtube",
  "terms": ["ai coding agents"],
  "idempotency_key": "find-1"
}

Copy id. Call get_status with that id until cards has URLs, then pick one url. If you get CONFLICT, poll job_id from the error instead of starting a second search.

Post the comment

Call post_comment. Keep text at or under commentMaxLength. Keep idempotency_key at least 8 characters. Reuse it if the tool times out. Do not add likes.

{
  "video_url": "VIDEO_URL",
  "text": "Useful breakdown of this.",
  "idempotency_key": "comment-1"
}

Copy id. That is the thread id.

Poll until identity is present

Call get_status with the thread id. Wait a few seconds and call it again until identity is an object, not null. Reads do not count toward the write rate limit.

{
  "id": "THREAD_ID"
}

On YouTube, copy youtube_like_url (or comment_id). On TikTok, copy video_url and username. For a reply on either platform, copy video_url and username.

Like or reply

Use a new idempotency key. Set like quantity to likeMin or higher.

YouTube like

{
  "url": "https://www.youtube.com/watch?v=VIDEO&lc=COMMENT_ID",
  "quantity": 25,
  "idempotency_key": "like-1"
}

TikTok like

{
  "video_url": "https://www.tiktok.com/@user/video/VIDEO",
  "username": "posted_name",
  "quantity": 25,
  "idempotency_key": "like-1"
}

Reply (both platforms)

{
  "video_url": "VIDEO_URL",
  "username": "posted_name",
  "text": "Agree on the pricing point.",
  "idempotency_key": "reply-1"
}

Do not send lc on reply. Do not send cid or share_comment_id.