Documentation

Home › API & MCP

API & MCP

Post microtasks for real people, review submissions and check your balance from code with the REST API, or let Claude, ChatGPT, Cursor and your own agents do it through the MCP server.

MCP Server

Connect Claude, ChatGPT, Cursor, Codex or your own agent to RapidWorkers. The AI can look up prices, post microtasks for real people and review the work, and it shows you the cost before anything is charged.

Server URL
https://www.rapidworkers.io/api/mcp/
Transport
Streamable HTTP
Sign-in
OAuth 2.1 or API key
Tools
22

New to MCP? See what the RapidWorkers MCP server can do. Prefer plain HTTP? The REST API reference follows below.

Connect your client

Apps that support sign-in open a RapidWorkers login window the first time you use them. For the others, create an API key in the dashboard. Each setup shows where the key goes: in place of YOUR_RAPIDWORKERS_API_KEY, or in the RAPIDWORKERS_API_KEY environment variable.

Claude (web, desktop, mobile)

Sign in with RapidWorkers
Add to Claude
  1. Open Claude, go to Customize, then Connectors, and choose Add custom connector.
  2. Name it RapidWorkers and paste https://www.rapidworkers.io/api/mcp/ as the URL.
  3. Click Connect and sign in with your RapidWorkers account to approve access.

Authentication

Sign in with RapidWorkers (OAuth)

Claude, ChatGPT and most desktop clients open a RapidWorkers sign-in page and ask you to approve the permissions below. There is nothing to copy, and the app only gets the permissions you approve.

API key

For clients without sign-in, scripts and autonomous agents. Send the key as a bearer token. An API key has full access to the account, the same as the REST API.

HTTP
Authorization: Bearer YOUR_RAPIDWORKERS_API_KEY

Permissions (OAuth scopes)

ScopeAllows
account:readRead your balance, transactions and account status
jobs:readRead your jobs, surveys, AI tasks and their submissions
jobs:writeCreate, extend and cancel jobs, surveys and AI tasks (spends balance)
submissions:reviewApprove or reject submissions and block workers (pays workers)
deposit:createCreate deposit checkout links for you to pay
  • Revoke an API key or disconnect a signed-in app at any time on the API Management page of your dashboard. Access stops immediately.
  • Never put a key in a URL or query string. Send it only in the Authorization header, and keep config files that contain a key out of version control.

Tools

22 tools. Read-only tools never change anything. Tools marked Spends money charge your balance or pay workers, and clients that respect tool hints ask you before running them.

Account & platform

ToolWhat it doesPermissionAccess
get_accountGet accountBalance, deposit status, AI task access and commission rate.Permission: account:readRead-only
get_platform_infoGet platform rules and optionsLimits, fees, job categories, prefilled job types, AI task types, survey builder options and country codes.Permission: Any connectionRead-only
list_transactionsList transactionsThe latest deposits, charges, refunds and payouts.Permission: account:readRead-only
get_deposit_linkCreate deposit linkA hosted card or crypto checkout link for a human to pay ($20 minimum).Permission: deposit:createChanges data

Jobs, surveys & AI tasks

ToolWhat it doesPermissionAccess
preview_job_costPreview job costExact cost (pay × workers + commission + pin) and a quote id, before anything is charged.Permission: jobs:readRead-only
create_jobCreate jobPost a custom microtask for real people, with an optional AI-generated image; the cost is charged from the balance.Permission: jobs:writeSpends money
create_prefilled_jobCreate prefilled jobOne-link jobs for common tasks such as likes, follows, shares or reviews.Permission: jobs:writeSpends money
create_surveyCreate surveyBuild a questionnaire that real people answer on RapidWorkers, with screening questions and quality checks; the cost is charged from the balance.Permission: jobs:writeSpends money
create_ai_taskCreate AI data taskCollect photos, audio, video or text from real people for AI training, with an optional AI-generated example image.Permission: jobs:writeSpends money
request_ai_task_accessRequest AI task accessAsk the RapidWorkers team to enable AI data tasks on the account.Permission: jobs:writeChanges data
list_jobsList jobsYour jobs, surveys or AI tasks with status, progress and pending submissions.Permission: jobs:readRead-only
get_jobGet jobFull details of one job, survey or AI task.Permission: jobs:readRead-only
extend_jobAdd workers to a jobAdd more worker slots to a job; the extra cost is charged from the balance.Permission: jobs:writeSpends money
cancel_jobCancel jobStop a job and refund the unused budget (a $0.20 fee applies to live jobs).Permission: jobs:writeSpends money

Review & workers

ToolWhat it doesPermissionAccess
list_submissionsList submissionsWorker submissions with proof text, image links and worker stats, or survey responses with their answers and quality score.Permission: jobs:readRead-only
get_survey_resultsGet survey resultsPer-question counts, percentages, averages, NPS and text samples for a survey.Permission: jobs:readRead-only
approve_submissionApprove submissionApprove a submission and pay the worker, with an optional tip.Permission: submissions:reviewSpends money
reject_submissionReject submissionReject a submission with a reason the worker can see.Permission: submissions:reviewChanges data
approve_all_pendingApprove all pending submissionsApprove and pay every pending submission on a job at once, or only the survey responses with a good quality score.Permission: submissions:reviewSpends money
block_workerBlock workerStop a worker from taking your jobs; their pending submissions are rejected.Permission: submissions:reviewChanges data
unblock_workerUnblock workerAllow a blocked worker to take your jobs again.Permission: submissions:reviewChanges data
list_blocked_workersList blocked workersWorkers you have blocked.Permission: jobs:readRead-only

AI-generated images

create_job, create_prefilled_job, create_survey and create_ai_task take an optional image_prompt (20 to 4,000 characters) describing one image to show workers next to the instructions. RapidWorkers turns it and the job details into a detailed design brief and generates the image with AI at no extra cost. Jobs show it with their images, surveys with their intro, and AI tasks attach it as an example of what to submit.

Until the image is attached the job waits as pending_image, hidden from workers, then goes live automatically, usually within a minute or two. If generation fails, it goes live without the image. get_job returns it in image_urls, or in reference_file_urls for AI tasks.

Surveys

create_survey posts a questionnaire that people answer on RapidWorkers: choice, dropdown, rating (stars, agreement or NPS), matrix, ranking, text, number, date and consent questions, plus text blocks, up to 5 screening questions, show_if display logic and platform attention checks. Questions are keyed q_1, q_2 and so on by position. Pay is at least $0.50 per response, and screened-out people are not paid.

The other tools take kind: "survey". list_submissions returns each response with its answers, quality score and band. approve_all_pending can approve only the good band. get_survey_results returns the totals for every question.

Resources & prompts

Resources are read-only documents a client can load into the conversation. Prompts are ready-made workflows that show up as prompt suggestions or slash commands in clients that support them.

Resources

URIContents
rapidworkers://platformPlatform rules and options (application/json)
rapidworkers://guideAgent quickstart (text/markdown)

Prompts

PromptWhat it does
post_social_boostBoost a social postPick a prefilled job type, preview the cost and post it.
review_pending_submissionsReview pending submissionsCheck proofs against the brief and approve or reject each.
collect_training_dataCollect AI training dataPlan and post an AI data-collection task.

Rules & errors

The MCP server follows the same rules as the website and the REST API.

  • $0.05minimum pay per task ($0.10 for AI data tasks, $0.50 per survey response)
  • 10workers minimum per job
  • $20minimum deposit, needed once before you post
  • Costpay × workers + commission, plus $10 to pin a job

Confirm before spending

  1. preview_job_cost returns the exact total, whether your balance covers it and a quote_id that is valid for 10 minutes.
  2. The AI shows you the total and waits for your go-ahead.
  3. The create tool runs with that quote_id, confirm: true and an idempotency_key. A retry with the same key returns the first result instead of posting the job twice.
JSON
{
  "quote_id": "<quote_id from preview_job_cost>",
  "confirm": true,
  "idempotency_key": "signup-test-2026-11-07"
}

Errors

Tool errors come back as a normal result with isError: true, so the model can read the message and fix the call.

SituationWhat you get
No key or sign-in, or an expired oneHTTP 401 with a WWW-Authenticate header that points to the sign-in metadata. OAuth clients start the sign-in from it.
A permission you did not approveTool error: "This connection lacks the jobs:write permission; reconnect and approve it."
Pay, quantity or balance below the rulesTool error that names the fix, such as "Pay rate must be at least $0.05", or the shortfall and a pointer to get_deposit_link.
Quote expired or the job changed after the previewTool error. Call preview_job_cost again and confirm the new total.
Too many requestsLimits are per account, not per key: 1,000 requests an hour shared by all your API keys (MCP and REST API together), and a separate 1,000 an hour shared by all signed-in apps. Wait and retry.

Agent code

Call the server from your own agent through a model API, or test it from the terminal. Keep the API key in an environment variable, such as RAPIDWORKERS_API_KEY, and require approval for tools that spend money.

Claude API (Python)

python
import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://www.rapidworkers.io/api/mcp/",
        "name": "rapidworkers",
        "authorization_token": os.environ["RAPIDWORKERS_API_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "rapidworkers"}],
    messages=[{
        "role": "user",
        "content": "Get 20 people to test the signup flow at https://example.com and report bugs. Show me the cost before posting.",
    }],
)
print(response.content)

Reads the key from the RAPIDWORKERS_API_KEY environment variable. Set it to your API key first.

OpenAI Responses API (tool config)

json
{
  "type": "mcp",
  "server_label": "rapidworkers",
  "server_url": "https://www.rapidworkers.io/api/mcp/",
  "headers": {
    "Authorization": "Bearer YOUR_RAPIDWORKERS_API_KEY"
  },
  "require_approval": "always"
}

MCP Inspector (test from the terminal)

bash
npx @modelcontextprotocol/inspector --cli https://www.rapidworkers.io/api/mcp/ \
  --transport http --header "Authorization: Bearer $RAPIDWORKERS_API_KEY" --method tools/list

Reads the key from the RAPIDWORKERS_API_KEY environment variable. Set it to your API key first.

Authentication Header

Include your API key in every request using the X-API-Key header:

HTTP
X-API-Key: your_api_key_here

Rate limit: 1,000 requests per hour per account, shared by all your API keys

Endpoints

Standard Endpoints

Creates a new job/campaign with specified details. Requires multipart/form-data content type. Set approve_once_full to true to automatically approve all submissions and pay workers once the job reaches its total availabilities.

Content-Type:multipart/form-data

titlestringrequired
descriptionstringrequired
pay_ratedecimalrequired
total_availabilitiesintegerrequired
proof_required_descriptionstringrequired
categorystringrequired
sub_categorystring
campaign_imagesfile

repeat the field for up to 10 images; JPG, PNG or WEBP, max 1MB each

campaign_imagefile

a single image; counts toward the 10

image_promptstring

20 to 4000 characters. A detailed description of one image we generate with AI and add to the job after it is created; counts toward the 10

countriesarray

Omit to include all countries

excluded_countriesarray

Only when open to all countries: ISO codes to leave out, e.g. IN, BD

approve_once_fullboolean

default: false. When true, all submissions are automatically approved and workers paid once the job reaches its total availabilities

python
import requests

# Create a job without image
job_data = {
    "title": "Complete a Survey",
    "description": "Fill out our 5-minute customer satisfaction survey",
    "pay_rate": "2.50",
    "total_availabilities": "100",
    "proof_required_description": "Submit a screenshot of the completion page",
    "category": "Survey",
    "sub_category": (None, "Customer Feedback"),
    "countries": (None, '["US", "CA", "GB"]'),  # Omit to include all countries
}
response = requests.post(
    "https://api.rapidworkers.io/jobs/add",
    headers={"X-API-Key": "your_api_key_here"},
    files=job_data
)
job = response.json()
print(f"Job created: {job['job']['public_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job": {
    "public_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Test Job",
    "status": "Active",
    "pay_rate": "5.00",
    "total_availabilities": 10
  },
  "deduction_details": {
    "total_cost": "50.00",
    "commission": "5.00",
    "total_deducted": "55.00",
    "new_balance": "945.00"
  }
}

400—Invalid data or insufficient balance

401—Invalid or missing API key

403—Job rejected by legitimacy check

Retrieves your current account balance.

Content-Type:application/json

JSON
{} // Empty body
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/account/get_balance",
    headers={"X-API-Key": "your_api_key_here"}
)
print(f"Balance: {response.json()['balance']}")
JSON
// 200 OK
{
  "balance": "1000.00"
}

401—Invalid or missing API key

404—User not found

Approves a worker's submission for your campaign.

Path Parameters

campaign_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Great work!", // Optional
  "tip": "2.00" // Optional: $0.01-$50.00 from your balance, paid to the worker in full with no fee
}
python
import requests

campaign_id = "your_campaign_public_id"
submission_id = 456

response = requests.post(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/{submission_id}/approve/",
    headers={"X-API-Key": "your_api_key_here"},
    json={"notes": "Great work!"}
)
print(f"Submission approved: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "Submission approved successfully",
  "submission": {
    "id": 123,
    "userId": 12345, // Worker public ID
    "userName": "Maria G.", // First name and last-name initial; employers never see a worker's email or full name
    "status": "Approved",
    "amount_paid": "5.00"
  }
}

400—Submission already processed, insufficient funds, or invalid tip

403—You don't own this campaign

404—Submission not found

Rejects a worker's submission with a reason.

Path Parameters

campaign_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Does not meet requirements" // Required
}
python
import requests

campaign_id = "your_campaign_public_id"
submission_id = 456

response = requests.post(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/{submission_id}/reject/",
    headers={"X-API-Key": "your_api_key_here"},
    json={"notes": "Screenshot does not show completion page"}
)
print(f"Submission rejected: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "Submission rejected",
  "submission": {
    "id": 123,
    "userId": 12345, // Worker public ID
    "userName": "Maria G.", // First name and last-name initial; employers never see a worker's email or full name
    "status": "Rejected",
    "notes": "Does not meet requirements"
  }
}

400—Missing rejection reason

403—You don't own this campaign

404—Submission not found

Approve all pending submissions for a campaign at once.

Path Parameters

campaign_idUUID

Content-Type:application/json

JSON
{
  "notes": "Bulk action notes" // Optional
}
python
import requests

campaign_id = "your_campaign_public_id"

# Bulk approve all pending
response = requests.post(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/bulk_action/",
    headers={"X-API-Key": "your_api_key_here"},
    json={"notes": "All submissions verified"}
)
print(f"Bulk action result: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "All submissions approved successfully.",
  "submissions": [
    { "id": 123, "status": "Approved", "userName": "Maria G." },
    { "id": 124, "status": "Approved", "userName": "Ken T." }
  ]
}

403—You don't own this campaign

404—No pending submissions found

Retrieves all campaigns owned by the authenticated user, with optional status filtering.

statusstring

"Active", "Pending", "Completed", "Canceled"

languagestring

default: "en"

python
import requests

# List all campaigns
response = requests.get(
    "https://api.rapidworkers.io/api/campaigns/",
    headers={"X-API-Key": "your_api_key_here"}
)
campaigns = response.json()
for campaign in campaigns["results"]:
    print(f"{campaign['jobTitle']} - {campaign['jobStatus']}")

# Filter by status
response = requests.get(
    "https://api.rapidworkers.io/api/campaigns/?status=Active",
    headers={"X-API-Key": "your_api_key_here"}
)
JSON
// 200 OK
[
  {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "jobTitle": "Complete a Survey",
    "jobCategory": "Survey",
    "jobPay": "2.50",
    "jobLocation": "In",
    "jobCreatedAt": "2025-01-15T10:30:00Z",
    "jobStatus": "Active",
    "jobInstancesCompleted": 45,
    "jobTotalAvailabilities": 100,
    "jobSuccessRate": "40%",
    "description": "Fill out our customer satisfaction survey",
    "canceled": false,
    "remainingAvailabilities": 55,
    "pendingSubmissions": 12,
    "approvedSubmissions": 40,
    "rejectedSubmissions": 5
  }
]

401—Invalid or missing API key

Retrieves detailed information about a specific campaign including submission counts and remaining availability.

Path Parameters

campaign_idUUID
languagestring

default: "en"

python
import requests

campaign_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/campaigns/detail/{campaign_id}/",
    headers={"X-API-Key": "your_api_key_here"}
)
campaign = response.json()
print(f"Remaining slots: {campaign['remaining_availabilities']}")
print(f"Pending: {campaign['pending_submissions']}")
JSON
// 200 OK
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "jobTitle": "Complete a Survey",
  "jobCategory": "Survey",
  "jobPay": "2.50",
  "jobLocation": "In",
  "jobCreatedAt": "2025-01-15T10:30:00Z",
  "jobStatus": "Active",
  "jobInstancesCompleted": 45,
  "jobTotalAvailabilities": 100,
  "jobSuccessRate": "40%",
  "description": "Fill out our customer satisfaction survey",
  "canceled": false,
  "remainingAvailabilities": 55,
  "pendingSubmissions": 12,
  "approvedSubmissions": 40,
  "rejectedSubmissions": 5
}

401—Invalid or missing API key

403—You don't own this campaign

404—Campaign not found

Retrieves all submissions for a specific campaign with worker metadata, optional status filtering, and pagination.

Path Parameters

campaign_idUUID
statusstring

"Pending", "Approved", "Rejected"

searchstring

search by worker name

pageinteger

default: 1

rowsPerPageinteger

default: 1000

languagestring

default: "en"

python
import requests

campaign_id = "123e4567-e89b-12d3-a456-426614174000"

# List all submissions
response = requests.get(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/",
    headers={"X-API-Key": "your_api_key_here"}
)
data = response.json()
for sub in data["results"]["submissions"]:
    print(f"#{sub['submissionId']} - {sub['status']} - Age: {sub['worker_account_age_days']}d")

# Filter pending only
response = requests.get(
    f"https://api.rapidworkers.io/api/campaigns/{campaign_id}/submissions/?status=Pending",
    headers={"X-API-Key": "your_api_key_here"}
)
JSON
// 200 OK
{
  "count": 45,
  "next": null,
  "previous": null,
  "results": {
    "submissions": [
      {
        "submissionId": 123,
        "userId": "abc-def-123",
        "userName": "Maria G.", // First name and last-name initial; employers never see a worker's email or full name
        "userAvatar": "https://...",
        "campaignId": "123e4567-e89b-12d3-a456-426614174000",
        "campaignTitle": "Complete a Survey",
        "status": "Pending",
        "country_name": "United States",
        "submittedAt": "2025-01-16T14:30:00Z",
        "proof_text": "Completed the survey as requested",
        "images": [
          { 
            "id": "img_1", 
            "url": "https://...", 
            "thumbnailUrl": "https://..." 
          }
        ],
        "notes": null,
        "workerAccountAgeDays": 120,
        "workerApprovalRate": "85%",
        "workerTotalCompleted": 47
      }
    ],
    "pagination": {
      "totalCount": 45,
      "pageCount": 1,
      "currentPage": 1,
      "rowsPerPage": 1000
    }
  }
}

401—Invalid or missing API key

403—You don't own this campaign

404—Campaign not found

Blocks a worker from submitting proofs to any of your campaigns. Blocked workers will not see your campaigns in their job list.

Content-Type:application/json

JSON
{
  "worker_id": 12345 // Worker public ID
}
python
import requests

worker_id = 12345

response = requests.post(
    "https://api.rapidworkers.io/api/workers/block/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"worker_id": worker_id}
)
print(f"Worker blocked: {response.json()}")
JSON
// 201 Created
{
  "success": true,
  "message": "Worker blocked successfully",
  "worker_id": 12345
}

400—Missing worker_id, self-block attempt, or worker already blocked

401—Invalid or missing API key

404—Worker not found

Unblocks a previously blocked worker, allowing them to see and submit proofs to your campaigns again.

Content-Type:application/json

JSON
{
  "worker_id": 12345
}
python
import requests

worker_id = 12345

response = requests.post(
    "https://api.rapidworkers.io/api/workers/unblock/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"worker_id": worker_id}
)
print(f"Worker unblocked: {response.json()}")
JSON
// 200 OK
{
  "success": true,
  "message": "Worker unblocked successfully",
  "worker_id": 12345
}

400—Missing worker_id or worker is not blocked

401—Invalid or missing API key

404—Worker not found

Retrieves the list of all workers you have blocked.

Request
No request body required.
python
import requests

response = requests.get(
    "https://api.rapidworkers.io/api/workers/blocked/",
    headers={"X-API-Key": "your_api_key_here"}
)
blocked = response.json()
for worker in blocked:
    print(f"Blocked: {worker['worker_name']} (ID: {worker['worker_id']})")
JSON
// 200 OK
[
  {
    "worker_id": 12345,
    "worker_name": "Maria G.", // First name and last-name initial
    "blocked_at": "2025-01-15T10:30:00Z"
  }
]

401—Invalid or missing API key

Creates a survey that workers answer on RapidWorkers: choice, rating, NPS, matrix, ranking, text, number and date questions, with optional screening questions, display logic and attention checks. Minimum pay is $0.50 per response. Workers who are screened out are not paid. Every problem with the questions is listed in one answer.

Content-Type:application/json

JSON
{
  "title": "Car owner survey", // Required, up to 200 characters
  "description": "A few questions about your car. It takes about 3 minutes.", // Required: the intro workers read (up to 5,000 characters)
  "pay_rate": "0.50", // Required (minimum: 0.50 per response)
  "total_availabilities": 200, // Required (10-20000); "quantity" works too
  "length_in_minutes": 3, // Optional: estimated from the questions when left out
  "countries": ["US", "GB"], // Required. ["All"] for every country, or ISO codes like ["US", "GB"]
  "excluded_countries": [], // Optional, only with ["All"]
  "audience": { "min_age": 18, "max_age": 65, "native_languages": ["en"] }, // Optional: also genders, education, occupations (codes in /api/platform/info/ under survey_builder)
  "settings": { "block_paste": false }, // Optional: true stops pasting into text answers
  "image_prompt": "A friendly illustration of a driver answering a short survey on a phone", // Optional: one image we generate with AI and show with the intro
  "questions": [ // Required: 1-60 items, at most 50 questions. Keys are q_1, q_2, ... by position (text blocks count)
    { "type": "single_choice", "label": "Do you drive at least once a week?", "options": ["Yes", "No"],
      "screener": true, "disqualify": ["No"] }, // Screening questions come first (up to 5); screened-out workers are not paid
    { "type": "rating", "label": "How likely are you to recommend your car brand?", "scale": { "preset": "nps" } },
    { "type": "long_text", "label": "What would make you recommend it?", "max_length": 1000,
      "show_if": [{ "question": "q_2", "operator": "lte", "value": 6 }] }, // Shown only when the answer to q_2 is 6 or less
    { "type": "multiple_choice", "label": "Which features matter most?", "options": ["Price", "Safety", "Comfort"],
      "allow_other": true, "none_option": "None of these", "max_choices": 2, "randomize_options": true },
    { "type": "matrix", "label": "How much do you agree?", "rows": ["It is reliable", "It is cheap to run"],
      "scale": { "preset": "agree_5" } }, // Presets: stars_5, agree_5, agree_7, nps (rating only) or custom (min, max, min_label, max_label)
    { "type": "attention_check", "template": "select_option" } // Templates: select_option, agree_scale, nonsense_statement
    // type: single_choice | multiple_choice | dropdown | rating | matrix | ranking | short_text | long_text
    //       | number | date | consent | statement | attention_check
  ]
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/custom-surveys/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "title": "Car owner survey",
        "description": "A few questions about your car. It takes about 3 minutes.",
        "pay_rate": "0.50",
        "total_availabilities": 200,
        "countries": ["US", "GB"],
        "questions": [
            {"type": "single_choice", "label": "Do you drive at least once a week?",
             "options": ["Yes", "No"], "screener": True, "disqualify": ["No"]},
            {"type": "rating", "label": "How likely are you to recommend your car brand?",
             "scale": {"preset": "nps"}},
            {"type": "long_text", "label": "What would make you recommend it?",
             "show_if": [{"question": "q_2", "operator": "lte", "value": 6}]},
            {"type": "attention_check", "template": "select_option"}
        ]
    }
)
survey = response.json()
print(f"Survey created: {survey['task_id']}")
JSON
// 201 Created
{
  "message": "Survey created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active", // "pending_review" during moderation, "pending_image" while its image is generated
  "survey": { "taskPublicId": "123e4567-...", "title": "Car owner survey", "status": "Active", "questionCount": 6, "lengthInMinutes": 3 }
}

// 400 when the questions are not valid: every problem is listed
{
  "error": "Question 4: add 2 to 20 options (and 1 more problem)",
  "code": "invalid_survey",
  "details": [{ "question": "q_4", "field": "options", "message": "Question 4: add 2 to 20 options" }, ...]
}

// Cancel, extend and review responses with the AI-task endpoints and this task_id:
// /api/ai-tasks/{task_id}/cancel/, /extend/, /submissions/{submission_id}/approve/, /reject/ and /submissions/bulk_approve/

400—Invalid survey (every problem listed in details), insufficient balance, or no deposit on the account

401—Invalid or missing API key

409—The X-Quote-Id quote expired or does not match this survey

Lists your surveys, newest first, with response counts, quality bands and the median completion time.

pageinteger

default: 1

page_sizeinteger

default: 50, max 100

python
import requests

response = requests.get(
    "https://api.rapidworkers.io/api/custom-surveys/mine/",
    headers={"X-API-Key": "your_api_key_here"}
)
for survey in response.json()["results"]:
    print(survey["title"], survey["counts"]["pending"], "pending")
JSON
// 200 OK, newest first
{
  "count": 3,
  "results": [
    {
      "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
      "taskType": "custom_survey",
      "title": "Car owner survey",
      "status": "Active",
      "pay": "0.50",
      "lengthInMinutes": 3,
      "questionCount": 6,
      "totalAvailabilities": 200,
      "completedCount": 48,
      "slotsOpen": 150,
      "inProgress": 2,
      "countries": ["US", "GB"],
      "createdAt": "2026-11-09T10:00:00Z",
      "counts": { "started": 61, "screenedOut": 11, "submitted": 48, "pending": 20, "approved": 26, "rejected": 2, "autoRejected": 1 },
      "quality": { "good": 40, "check": 5, "likelyBad": 1 },
      "medianSeconds": 174,
      "referenceFiles": [{ "id": 7, "name": "image.png", "contentType": "image/png", "size": 182044, "url": "https://..." }] // The image made from image_prompt, if any
    }
  ]
}

401—Invalid or missing API key

Retrieves one of your surveys with its questions (keys, option ids, screening and display logic), audience, settings and response counts.

Path Parameters

survey_idUUID
Request
No parameters
python
import requests

survey_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/custom-surveys/{survey_id}/",
    headers={"X-API-Key": "your_api_key_here"}
)
survey = response.json()
for question in survey["questions"]:
    print(question["key"], question["label"])
JSON
// 200 OK: the list fields above, plus
{
  "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Car owner survey",
  "status": "Active",
  "description": "A few questions about your car. It takes about 3 minutes.",
  "reservedAmount": "115.00",
  "paidOutAmount": "13.00",
  "questions": [
    {
      "key": "q_1",
      "type": "single_choice",
      "label": "Do you drive at least once a week?",
      "required": true,
      "page": 1,
      "screener": true,
      "options": [{ "id": "o1", "label": "Yes" }, { "id": "o2", "label": "No" }],
      "disqualify": ["o2"],
      "showIf": []
    },
    {
      "key": "q_3",
      "type": "long_text",
      "label": "What would make you recommend it?",
      "page": 2,
      "showIf": [{ "question": "q_2", "operator": "lte", "value": 6, "questionLabel": "How likely are you to recommend your car brand?", "valueLabel": "6" }]
    }
  ],
  "audience": { "minAge": 18, "maxAge": 65, "genders": [], "nativeLanguages": ["en"], "education": [], "occupations": [] },
  "settings": { "blockPaste": false, "reservationMinutes": null },
  "canEdit": false,
  "editBlockedReason": "has_responses"
}

401—Invalid or missing API key

404—Survey not found

Returns a survey's results for each question: answer counts and percentages, averages, NPS, rankings, number ranges and the latest written answers, plus the response funnel and quality bands.

Path Parameters

survey_idUUID
includestring

"valid" = pending and approved, the default; "approved"; "all" adds rejected

python
import requests

survey_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/custom-surveys/{survey_id}/results/",
    headers={"X-API-Key": "your_api_key_here"},
    params={"include": "valid"}
)
for question in response.json()["questions"]:
    print(question["key"], question["label"], question["answered"], "answered")
JSON
// 200 OK. Screened-out workers never count as responses
{
  "survey": { "taskPublicId": "123e4567-...", "title": "Car owner survey", "status": "Active", "totalAvailabilities": 200 },
  "include": "valid",
  "funnel": { "started": 61, "screenedOut": 11, "submitted": 48, "pending": 20, "approved": 26, "rejected": 2, "autoRejected": 1 },
  "timing": { "medianSeconds": 174, "effectiveHourlyPay": "10.34" },
  "quality": { "good": 40, "check": 5, "likelyBad": 1 },
  "questions": [
    {
      "key": "q_2", "type": "rating", "label": "How likely are you to recommend your car brand?", "answered": 46, "skipped": 0,
      "distribution": [{ "value": 10, "count": 18, "percent": 39.1 }],
      "mean": 7.9, "median": 8,
      "nps": { "score": 24, "promoters": 22, "passives": 13, "detractors": 11 }
    },
    {
      "key": "q_4", "type": "multiple_choice", "label": "Which features matter most?", "answered": 46, "skipped": 0,
      "options": [{ "id": "o2", "label": "Safety", "count": 31, "percent": 67.4 }],
      "other": { "count": 3, "samples": ["Boot space"] }
    },
    {
      "key": "q_3", "type": "long_text", "label": "What would make you recommend it?", "answered": 11, "skipped": 35,
      "total": 11, "samples": [{ "submissionId": 912, "text": "Cheaper servicing and a longer warranty." }]
    }
  ]
}

401—Invalid or missing API key

403—You don't own this survey

404—Survey not found

Lists a survey's responses, newest first, with each answer as text, the quality score, band and flags, and whether it was rejected automatically. Filter by status and quality band.

Path Parameters

survey_idUUID
statusstring

"pending", "approved", "rejected" or "all"

bandstring

quality band: "good", "check" or "likely_bad"

pageinteger

default: 1

page_sizeinteger

default: 25, max 100

python
import requests

survey_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/custom-surveys/{survey_id}/responses/",
    headers={"X-API-Key": "your_api_key_here"},
    params={"status": "pending", "band": "likely_bad"}
)
for row in response.json()["results"]:
    print(row["submissionId"], row["qualityScore"], [flag["code"] for flag in row["qualityFlags"]])
JSON
// 200 OK, newest first
{
  "count": 48,
  "page": 1,
  "pageSize": 25,
  "results": [
    {
      "submissionId": 912,
      "workerId": 10457, // The worker_id that /api/workers/block/ takes
      "status": "Pending",
      "autoRejected": false,
      "reasonCode": "", // attention_failed, too_fast or duplicate_device when rejected automatically
      "createdAt": "2026-11-09T11:02:13Z",
      "durationSeconds": 181,
      "country": "United States",
      "qualityScore": 80,
      "qualityBand": "good", // good (70-100), check (40-69) or likely_bad (under 40)
      "qualityFlags": [{ "code": "pasted_text", "severity": "moderate", "detail": "Most of the answer to Q3 was pasted", "question": "q_3" }],
      "answers": [
        { "key": "q_1", "type": "single_choice", "label": "Do you drive at least once a week?", "value": "o1", "display": "Yes" },
        { "key": "q_5", "type": "matrix", "label": "How much do you agree?", "value": { "r1": 4, "r2": 2 }, "display": "It is reliable: 4\nIt is cheap to run: 2" }
      ]
    }
  ]
}

// Approve or reject a response with /api/ai-tasks/{survey_id}/submissions/{submissionId}/approve/ or /reject/

401—Invalid or missing API key

403—You don't own this survey

404—Survey not found

Creates an AI data task (image, video, audio or text collection, data labeling). Workers upload files straight to private storage; you review and approve each submission. Accepts JSON, or multipart/form-data when attaching reference images.

Content-Type:application/json

JSON
{
  "task_type": "image_collection", // Required: image_collection | video_collection | audio_collection | text_collection | custom_data_collection
  "capture_mode": "both", // Optional, audio/video tasks only: both | upload | record (how workers provide files)
  "title": "Submit 10 photos of your face", // Required
  "description": "<p>Take 10 clear photos from different angles...</p>", // Required, HTML allowed
  "submission_instructions": "Front, left, right, up, down and 5 more angles. No filters.", // Required
  "required_file_count": 10, // Required (1-200). Exact count for image/video/audio tasks, maximum for others
  "pay_rate": "0.50", // Required (minimum: 0.10)
  "total_availabilities": 100, // Required (10-20000)
  "length_in_minutes": 10, // Optional
  "countries": ["All"], // Required. ["All"] for every country, or ISO codes like ["US", "GB"]
  "excluded_countries": ["IN", "BD"], // Optional, only with ["All"]: every country except these
  "reference_upload_ids": [12, 13], // Optional: sample/instructional media uploaded via /api/ai-tasks/reference-uploads/
  "submission_fields": [ // Required for custom_data_collection only: the worker form, in display order (max 30)
    { "type": "select", "label": "Category", "required": true, "options": ["Electricity", "Insurance"] },
    // Dependent dropdown: its options follow the answer to an earlier plain dropdown.
    // parent_key is that dropdown's position as "field_<n>" (the first field is field_1).
    // options_by_parent needs a list (1-1000 options) for every parent option, 5000 options in total.
    // Workers can only submit an option listed under the parent option they chose.
    { "type": "select", "label": "Biller / Company Name", "required": true, "parent_key": "field_1",
      "options_by_parent": { "Electricity": ["B.E.S.T Mumbai", "TP Ajmer Distribution Ltd"], "Insurance": ["HDFC Life Insurance"] } },
    { "type": "image", "label": "Bill screenshot", "required": true, "min_files": 1, "max_files": 1, "help_text": "Upload the original SMS screenshot" },
    { "type": "consent", "label": "I consent to share this data", "required": true }
    // type: short_text | long_text | select | datetime | consent | image | audio | video
  ]
}

// Alternatively send multipart/form-data with up to 30 reference_images (JPG, PNG or WEBP, 5MB each)
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/ai-tasks/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "task_type": "image_collection",
        "title": "Submit 10 photos of your face",
        "description": "<p>Take 10 clear photos of your face from different angles.</p>",
        "submission_instructions": "Front, left, right, up, down and 5 more angles. No filters.",
        "required_file_count": 10,
        "pay_rate": "0.50",
        "total_availabilities": 100,
        "length_in_minutes": 10,
        "countries": ["All"]
    }
)
task = response.json()
print(f"Task created: {task['task_id']}")
JSON
// 201 Created
{
  "message": "AI task created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Active"
}

400—Invalid data, insufficient balance, or no deposit on the account

401—Invalid or missing API key

403—AI tasks are not enabled for this account yet

Lists every AI task you have created with submission counts.

Request
No parameters
python
import requests

response = requests.get(
    "https://api.rapidworkers.io/api/ai-tasks/mine/",
    headers={"X-API-Key": "your_api_key_here"}
)
for task in response.json()["tasks"]:
    print(task["title"], task["pendingSubmissions"], "pending")
JSON
// 200 OK
{
  "tasks": [
    {
      "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
      "taskType": "image_collection",
      "title": "Submit 10 photos of your face",
      "pay": "0.50",
      "countries": ["All"],
      "lengthInMinutes": 10,
      "requiredFileCount": 10,
      "referenceImages": [],
      "completedCount": 12,
      "totalAvailabilities": 100,
      "pendingSubmissions": 3,
      "status": "Active",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

401—Invalid or missing API key

Retrieves one AI task, including its submission rules and reference images.

Path Parameters

task_idUUID
Request
No parameters
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/",
    headers={"X-API-Key": "your_api_key_here"}
)
task = response.json()["task"]
print(f"Approved: {task['approvedSubmissions']} / {task['totalAvailabilities']}")
JSON
// 200 OK
{
  "task": {
    "taskPublicId": "123e4567-e89b-12d3-a456-426614174000",
    "taskType": "image_collection",
    "title": "Submit 10 photos of your face",
    "description": "<p>Take 10 clear photos...</p>",
    "submissionInstructions": "Front, left, right, up, down and 5 more angles.",
    "pay": "0.50",
    "countries": ["All"],
    "requiredFileCount": 10,
    "referenceImages": ["https://.../example.jpg"],
    "rules": {
      "allowedTypes": ["image/heic", "image/heif", "image/jpeg", "image/png", "image/webp"],
      "maxBytes": 15728640,
      "exactCount": true,
      "textRequired": false,
      "fileCount": 10
    },
    "completedCount": 12,
    "totalAvailabilities": 100,
    "pendingSubmissions": 3,
    "approvedSubmissions": 9,
    "rejectedSubmissions": 1,
    "reservedAmount": "50.00",
    "paidOutAmount": "4.50",
    "status": "Active",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

401—Invalid or missing API key

404—Task not found

Lists submissions for an AI task with the worker's written response and expiring download links for each uploaded file. Links are valid for 1 hour; request again for fresh ones.

Path Parameters

task_idUUID
statusstring

Pending, Approved, Rejected

python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/",
    headers={"X-API-Key": "your_api_key_here"},
    params={"status": "Pending"}
)
for submission in response.json()["submissions"]:
    for file in submission["files"]:
        data = requests.get(file["url"]).content  # download while the link is valid
        open(file["name"], "wb").write(data)
JSON
// 200 OK
{
  "task": { "taskPublicId": "123e4567-...", "title": "Submit 10 photos of your face", "status": "Active" },
  "submissions": [
    {
      "submissionId": 42,
      "userId": 1234,
      "userName": "Jane D.", // First name and last-name initial; employers never see a worker's email or full name
      "countryName": "Canada",
      "status": "Pending",
      "paymentStatus": "Not_Paid",
      "amountPaid": null,
      "textResponse": "",
      "notes": "",
      "fileCount": 10,
      "files": [
        {
          "id": 501,
          "name": "front.jpg",
          "contentType": "image/jpeg",
          "size": 2451234,
          "url": "https://bucket.s3.amazonaws.com/private/ai-tasks/...?X-Amz-Expires=3600&..." // Valid for 1 hour
        }
      ],
      "isBlocked": false,
      "submittedAt": "2025-01-16T08:12:00Z"
    }
  ]
}

401—Invalid or missing API key

403—You don't own this task

404—Task not found

Approves an AI task submission and pays the worker from the task's reserved funds.

Path Parameters

task_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Great photos, thank you", // Optional
  "tip": "2.00" // Optional: $0.01-$50.00 from your balance, paid to the worker in full with no fee
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
submission_id = 42
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/{submission_id}/approve/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"notes": "Great photos, thank you"}
)
print(response.json()["message"])
JSON
// 200 OK
{
  "success": true,
  "message": "Submission approved",
  "submission": {
    "submissionId": 42,
    "status": "Approved",
    "paymentStatus": "Paid",
    "amountPaid": "0.50"
  }
}

400—Not enough reserved funds for this task, not enough balance for the tip, or invalid tip

401—Invalid or missing API key

403—You don't own this task

404—Submission not found

Rejects an AI task submission with a reason. The worker can fix the issues and submit again.

Path Parameters

task_idUUID
submission_idinteger

Content-Type:application/json

JSON
{
  "notes": "Photos are blurry, please retake in better light" // Required
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
submission_id = 42
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/{submission_id}/reject/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"notes": "Photos are blurry, please retake in better light"}
)
print(response.json()["message"])
JSON
// 200 OK
{
  "success": true,
  "message": "Submission rejected",
  "submission": {
    "submissionId": 42,
    "status": "Rejected",
    "notes": "Photos are blurry, please retake in better light"
  }
}

400—Missing rejection reason, or submission already approved

401—Invalid or missing API key

403—You don't own this task

404—Submission not found

Issues presigned S3 URLs for sample or instructional media (images, video, audio). Upload the bytes with PUT, then pass the returned upload ids as reference_upload_ids when creating a task.

Content-Type:application/json

JSON
{
  "files": [
    { "name": "sample.mp4", "content_type": "video/mp4", "size": 18422311 }, // Images up to 15MB, audio 50MB, video 500MB
    { "name": "front.jpg", "content_type": "image/jpeg", "size": 2451234 }
  ]
}
python
import requests

with open("sample.mp4", "rb") as f:
    data = f.read()

issued = requests.post(
    "https://api.rapidworkers.io/api/ai-tasks/reference-uploads/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"files": [{"name": "sample.mp4", "content_type": "video/mp4", "size": len(data)}]}
).json()["uploads"][0]

requests.put(issued["url"], data=data, headers=issued["headers"]).raise_for_status()
upload_id = issued["uploadId"]  # pass in reference_upload_ids when creating the task
JSON
// 201 Created
{
  "uploads": [
    {
      "uploadId": 12,
      "name": "sample.mp4",
      "url": "https://bucket.s3.amazonaws.com/private/ai-task-references/...?X-Amz-Expires=3600&...",
      "headers": { "Content-Type": "video/mp4" }
    }
  ]
}

// PUT each file's bytes to its url with exactly those headers, then pass the uploadIds
// as reference_upload_ids when creating the task. URLs expire after 1 hour.

400—Unsupported type or file too large

401—Invalid or missing API key

429—Too many pending uploads

Approves every pending submission on an AI task and pays each worker.

Path Parameters

task_idUUID

Content-Type:application/json

JSON
{
  "notes": "Thanks everyone", // Optional
  "quality_bands": ["good"] // Optional, surveys only: approve only the Pending responses in these quality bands
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/submissions/bulk_approve/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={}
)
print(response.json()["message"])
JSON
// 200 OK
{
  "success": true,
  "message": "12 submission(s) approved",
  "approved": 12,
  "error": null,
  "pendingLeft": 3 // Only with quality_bands: Pending responses in other bands, left for you to review
}

400—Not enough reserved funds, or quality_bands on a task that is not a survey (code invalid_request)

401—Invalid or missing API key

403—You don't own this task

404—Task not found

Adds slots to an AI task. Charged at the task's pay rate plus commission. A completed task becomes active again.

Path Parameters

task_idUUID

Content-Type:application/json

JSON
{
  "additional_availabilities": 50 // Required. Charged at pay_rate x 50 plus commission
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/extend/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={"additional_availabilities": 50}
)
print(response.json()["task"]["totalAvailabilities"])
JSON
// 200 OK
{
  "message": "Task extended",
  "task": { "taskPublicId": "123e4567-...", "totalAvailabilities": 150, "status": "Active" }
}

400—Insufficient balance, task not active, or over the 20,000 limit

401—Invalid or missing API key

403—You don't own this task

404—Task not found

Edits an AI task the way campaigns are edited: the task is canceled and its unspent funds refunded, and a new version with your changes replaces it (charged fresh). Send every field, as when creating. Allowed while the task is pending or active, has no submissions waiting for review, and has been edited fewer than 10 times.

Path Parameters

task_idUUID

Content-Type:application/json

JSON
// The same fields as creating a task (all of them, not just the changes), plus:
{
  "task_type": "image_collection",
  "title": "Submit 10 photos of your face",
  "description": "<p>Take 10 clear photos from different angles...</p>",
  "submission_instructions": "<p>Front, left, right, up, down and 5 more angles.</p>", // HTML allowed
  "required_file_count": 10,
  "pay_rate": "0.50",
  "total_availabilities": 100,
  "length_in_minutes": 10,
  "countries": ["All"],
  "keep_reference_ids": [41, 42] // Optional: ids of the task's current reference files to keep (from the task detail)
}
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
task = {
    "task_type": "image_collection",
    "title": "Submit 10 photos of your face",
    "description": "<p>Take 10 clear photos of your face from different angles.</p>",
    "submission_instructions": "Front, left, right, up, down and 5 more angles. No filters.",
    "required_file_count": 10,
    "pay_rate": "0.60",
    "total_availabilities": 100,
    "length_in_minutes": 10,
    "countries": ["All"]
}
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/edit/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json=task
)
print(f"New version: {response.json()['task_id']}")
JSON
// 200 OK
{
  "message": "AI task updated successfully",
  "task_id": "9b2f6c1e-...", // The new version's id: use it from now on
  "status": "Active",
  "times_edited": 1
}

400—Invalid data, insufficient balance, submissions waiting for review, task not pending or active, or 10 edits reached

401—Invalid or missing API key

403—You don't own this task

404—Task not found

Stops an AI task and refunds funds not held by pending submissions. Pending submissions can still be approved and paid.

Path Parameters

task_idUUID
Request
No parameters
python
import requests

task_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.post(
    f"https://api.rapidworkers.io/api/ai-tasks/{task_id}/cancel/",
    headers={"X-API-Key": "your_api_key_here"}
)
print(f"Refunded: {response.json()['refund']}")
JSON
// 200 OK
{
  "message": "Task canceled",
  "refund": "37.50",
  "task": { "taskPublicId": "123e4567-...", "status": "Canceled" }
}

400—Task already canceled

401—Invalid or missing API key

403—You don't own this task

404—Task not found

Prefilled Job Endpoints

Simplified endpoints for common social media engagement tasks. Only requires a link and quantity. All prefilled jobs have automatic approval enabled: submissions are automatically approved and workers paid once the job reaches its total availabilities.

Create a simplified job for getting Facebook post likes. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://facebook.com/post/123", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/facebook-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://facebook.com/post/123",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for getting Facebook post shares. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://facebook.com/post/123", // Required
  "quantity": 25, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/facebook-shares/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://facebook.com/post/123",
        "quantity": 25  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "1.25"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Creates a ready-made AI training task where each worker submits photos of their own face from different angles. Only requires the number of workers. Default: 10 photos per worker at $0.10.

Content-Type:application/json

JSON
{
  "quantity": 50, // Required: number of workers (10-20000)
  "rate": "0.25", // Optional (default: 0.10, minimum: 0.10)
  "required_file_count": 10, // Optional (default: 10, maximum: 200) photos per worker
  "extra_instructions": "Wear no glasses in any photo.", // Optional, appended to the standard instructions
  "countries": ["US", "GB"] // Omit for all countries
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/ai-image-collection/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "quantity": 50,  # Minimum: 10
        "required_file_count": 10,
        "extra_instructions": "Wear no glasses in any photo."
    }
)
task = response.json()
print(f"Task created: {task['task_id']}")
JSON
// 201 Created
{
  "message": "Job created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Active",
  "total_cost": "12.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

403—AI tasks are not enabled for this account yet

Creates a ready-made AI training task where each worker records short voice clips in their browser. Only requires the number of workers. Default: 5 clips per worker at $0.10.

Content-Type:application/json

JSON
{
  "quantity": 50, // Required: number of workers (10-20000)
  "rate": "0.25", // Optional (default: 0.10, minimum: 0.10)
  "required_file_count": 5, // Optional (default: 5, maximum: 200) clips per worker
  "capture_mode": "both", // Optional: both | upload | record
  "extra_instructions": "Read these sentences aloud: ...", // Optional, appended to the standard instructions
  "countries": ["US", "GB"] // Omit for all countries
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/ai-audio-collection/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "quantity": 50,  # Minimum: 10
        "required_file_count": 5,
        "extra_instructions": "Read these sentences aloud: The quick brown fox..."
    }
)
task = response.json()
print(f"Task created: {task['task_id']}")
JSON
// 201 Created
{
  "message": "Job created successfully",
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "Active",
  "total_cost": "12.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

403—AI tasks are not enabled for this account yet

Create a simplified job for getting Instagram post likes. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://instagram.com/ABC123", // Required
  "quantity": 100, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/instagram-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://instagram.com/ABC123",
        "quantity": 100  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "5.00"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for gaining Instagram followers. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://instagram.com/username", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/instagram-followers/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://instagram.com/username",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for getting Twitter/X post likes. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://twitter.com/user/status/123", // Required
  "quantity": 75, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/twitter-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://twitter.com/user/status/123",
        "quantity": 75  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "3.75"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for gaining Twitter/X followers. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://twitter.com/username", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/twitter-followers/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://twitter.com/username",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for getting Twitter/X retweets. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://twitter.com/user/status/123", // Required
  "quantity": 30, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/twitter-retweets/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://twitter.com/user/status/123",
        "quantity": 30  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "1.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for getting Trustpilot reviews. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://trustpilot.com/review/example.com", // Required
  "quantity": 20, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/trustpilot-reviews/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://trustpilot.com/review/example.com",
        "quantity": 20  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "1.00"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for getting 9GAG upvotes. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://9gag.com/gag/abc123", // Required
  "quantity": 50, // Required (minimum: 6)
  "countries": ["US", "GB"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/9gag-upvotes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://9gag.com/gag/abc123",
        "quantity": 50  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "2.50"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Create a simplified job for getting YouTube video likes. Only requires a link and quantity. Auto-pricing: $0.05 per job. Submissions are automatically approved once the job is full.

Content-Type:application/json

JSON
{
  "link": "https://youtube.com/watch?v=abc123", // Required
  "quantity": 100, // Required (minimum: 6)
  "countries": ["US", "CA"], // Omit to include all countries
  "language": "en", // Optional
  "approve_once_full": false // Optional (default: false). Set true to auto-approve all submissions once job is full
}
python
import requests

response = requests.post(
    "https://api.rapidworkers.io/api/jobs/youtube-likes/",
    headers={"X-API-Key": "your_api_key_here", "Content-Type": "application/json"},
    json={
        "link": "https://youtube.com/watch?v=abc123",
        "quantity": 100  # Minimum: 10
    }
)
job = response.json()
print(f"Job created: {job['job_id']}")
JSON
// 201 Created
{
  "success": true,
  "message": "Job created successfully",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_cost": "5.00"
}

400—Invalid data, insufficient balance, or quantity below minimum (10)

401—Invalid or missing API key

Error Handling

All API errors follow a consistent format:

JSON
{
  "error": "Error message describing what went wrong"
}

Common HTTP Status Codes:

Status CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request data
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
429Rate LimitedRate limit exceeded (1,000/hour)
500Server ErrorServer-side error