find_videos

The MCP tool name is find_videos. HTTP is POST /api/v1/finds with Authorization: Bearer rmr_....

Starts a paid search and returns a job id. It does not paste a video and does not post. Poll get_status on id until cards has URLs, then pick one and call post_comment.

Request

Set HOST to https://rumora.ai in production. Replace rmr_YOUR_TOKEN with the full secret from API keys. Keep idempotency_key at least 8 characters and reuse it if this request times out.

curl -sS -X POST "$HOST/api/v1/finds" \
  -H "Authorization: Bearer rmr_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "youtube",
    "terms": [
      "ai coding agents"
    ],
    "idempotency_key": "find-1"
  }'

You should see JSON that includes id, type, status, credits_charged, next_step. If you see "error", match code in Errors.

Response

{
  "id": "JOB_ID",
  "type": "find",
  "status": "queued",
  "credits_charged": 50,
  "next_step": "Poll get_status until cards appear or the job fails. Empty finds refund the same credits as the web app."
}

Errors

• UNAUTHORIZED: Mint a key on API keys. Send Authorization: Bearer rmr_...
• PARSE: Fix the field named in message. Call get_usage for live max length.
• FORBIDDEN: Open Billing and start a paid plan, or paste a URL and post without Find.
• PAYMENT_REQUIRED: Open checkout_url from the error body. Buy a plan or an add-on pack, then retry with the same idempotency_key.
• HELD: Contact support. Mutating commands stay blocked until the hold clears.
• CONFLICT: Poll get_status on the job_id in the error body. Wait until that job finishes.
• RATE_LIMIT: Wait, then retry with the same idempotency_key. Reads are not counted.

The JSON error envelope is documented in Errors.

Credits

50 credits per keyword. Empty finds refund the same amount as the web app.

Next

Poll get_status on id until cards appear. A second open Find job returns CONFLICT with job_id. Poll that id instead of starting another search.

A full copy-paste job that uses this command is in Recipes. Identity and polling are explained in Comment identity and Status and polling.