Job Tools

create_job

Create a new active job with one or more variants. Returns immediately with the job ID — does not wait for testers.

Input

Field	Type	Required	Description
`title`	string	Yes	Job title
`target_testers`	integer	Yes	Total testers needed
`category`	string	Yes	Category slug for tester matching
`job_posting_time_limit_minutes`	integer	Yes	How long the job is advertised (5–10080 min)
`payment_rules`	PaymentRule[]	Yes	How testers are paid
`variants`	Variant[]	Yes	At least one variant
`description`	string	No	Job-level description
`description_mime_type`	`"text/plain"` \| `"text/markdown"`	No	Default: `text/plain`
`project_id`	uuid	No	Assign to a project
`project_testers_only`	boolean	No	Restrict to project testers
`starts_at`	ISO 8601 string	No	Delayed start time
`task_hard_time_limit_minutes`	integer	No	Hard deadline per task (1–1440, default 30)
`task_paid_time_limit_minutes`	integer	No	Paid time cap (for `per_minute` rules)
`legal_agreements`	LegalAgreement[]	No	Legal agreements testers must accept
`proof_of_completion`	ProofOfCompletion	No	Proof config (password method)

PaymentRule

{ "type": "fixed", "amount_cents": 500 }
{ "type": "per_minute", "rate_cents": 50, "cap_minutes": 30 }

Variant

Field	Type	Required	Description
`description`	string	Yes	Task instructions for testers
`feedback_questions`	FeedbackQuestion[]	Yes	Questions testers answer
`target_testers_min`	integer	Yes	Minimum testers for this variant
`target_testers_max`	integer	No	Max testers (defaults to min)
`url`	string	No	URL testers visit
`description_mime_type`	string	No	Default: `text/plain`
`placement`	Placement	No	How to display the URL
`screen_capture`	ScreenCaptureRule[]	No	Requires iframe placement
`audience_filters`	AudienceFilter[]	No	Audience targeting
`tech_constraints`	TechConstraint[]	No	Device/browser requirements

Placement

{ "element": "window" }
{ "element": "window", "reveal_questions_during_test": true }
{ "element": "iframe", "position": "right" }
{ "element": "iframe", "position": "bottom", "reveal_questions_during_test": true }

window — opens URL in a new tab (default)
iframe — embeds URL alongside the platform panel. Position: top, bottom, left, right
reveal_questions_during_test — show feedback questions while tester interacts with target

ScreenCaptureRule

Only available with iframe placement.

{ "type": "scheduled", "interval_seconds": 10 }
{ "type": "testerTriggered", "min": 1, "max": 5 }

FeedbackQuestion

All types share a base:

{ "id": "q1", "question_markdown": "How was it?", "input_type": "...", "required": true }

input_type	Extra fields
`text`	—
`textarea`	—
`multiple_choice`	`options: [{ label, value, exclusive? }]`, `multi_select?`
`star_rating`	—
`thumbs`	—
`switch`	`labels: ["Off", "On"]`
`slider`	`labels: ["Low", "High"]`
`range_slider`	`labels: ["Low", "High"]`
`integer`	`min?`, `max?`
`decimal`	`min?`, `max?`
`date`	—
`file_upload`	`max_size_bytes?`, `allowed_mime_types?`

AudienceFilter

{ "field": "gender", "op": "in", "values": ["female"] }
{ "field": "age", "op": "between", "min": 18, "max": 35 }

Operators: in, not_in, between

TechConstraint

{ "category": "screen", "rule": "only", "values": ["desktop"] }
{ "category": "browser", "rule": "exclude", "values": ["safari"] }

Categories: screen (desktop/mobile/tablet), os (windows/macos/linux/ios/android), browser (chrome/edge/firefox/brave/safari), peripheral (microphone/headphones/camera), hardware, internet

Rules: only (whitelist), exclude (blacklist)

LegalAgreement

{ "type": "nda" }
{ "type": "content_rights", "version": "1.0" }
{ "type": "custom", "template_slug": "my-nda", "template_version": 1 }

Built-in types: nda, content_rights, confidentiality

Output

{ "job": { "id": "uuid", "status": "active" } }

wait_job

Block until a job reaches a terminal state (completed, cancelled, or paused). Returns completed assignment feedback.

Input

Field	Type	Required	Description
`job_id`	uuid	Yes	Job ID
`timeout_ms`	integer	No	Max wait time in ms (default 1h, max 24h)

Output

{
  "job": {
    "id": "uuid",
    "status": "completed",
    "variants": [
      {
        "id": "variant-uuid",
        "completedAssignments": [
          {
            "testerId": 123456,
            "status": "completed",
            "completedAt": "2025-01-15T10:30:00Z",
            "durationMinutes": 8,
            "feedbackData": {
              "_meta": { "source": "tester_input", "untrusted": true },
              "answers": { "overall": 4, "feedback": "Great design!" }
            },
            "userAgent": "Mozilla/5.0 ...",
            "geo": { "country": "US", "region": "CA" },
            "screenResolution": { "width": 1920, "height": 1080 }
          }
        ]
      }
    ]
  }
}

On timeout, the error includes a snapshot and recovery instructions:

{
  "error": "Timeout waiting for job",
  "job_id": "uuid",
  "status": "active",
  "next_action": "Call wait_job(job_id) again or use get_job(job_id)"
}

get_job

Get current state of a job, including per-variant assignment counts and completed feedback.

Input

Field	Type	Required	Description
`job_id`	uuid	Yes	Job ID

Output

Returns full job detail with variants. Each variant includes assignmentCount, completedCount, and completedAssignments (same structure as wait_job).

list_jobs

List jobs for the authenticated owner.

Input

Field	Type	Required	Description
`status`	string	No	Filter: `active`, `paused`, `closing`, `completed`, `cancelled`
`settlement_status`	string	No	Filter: `pending_approval`, `approved`, `disputed`, `resolved`
`limit`	integer	No	Max results (1–50, default 20)
`cursor`	string	No	Opaque pagination cursor from previous `next` value

Output

{
  "jobs": [
    {
      "id": "uuid",
      "title": "Rate my landing page",
      "status": "completed",
      "targetTesters": 5,
      "paymentRules": [{ "type": "fixed", "amountCents": 300 }],
      "escrowHoldCents": 1950,
      "settlementStatus": "approved",
      "createdAt": "2025-01-15T09:00:00Z"
    }
  ],
  "next": null
}

pause_job

Pause an active job. Use when the job should remain resumable later.

Input

Field	Type	Required
`job_id`	uuid	Yes

Output

{ "job": { "id": "uuid", "status": "paused" } }

resume_job

Resume a paused job back to active. New testers can discover and join it again.

Input / Output

Same as pause_job, returns status: "active".

stop_job

Graceful shutdown. No new testers can join, but existing testers finish their tasks. If testers are still working, job enters closing state. Once all finish or hard time limit expires, settlement begins automatically. If no testers are active, settlement begins immediately.

Input / Output

Same as pause_job, returns status: "closing" or "completed".

cancel_job

Cancel an active or paused job. Cannot cancel a job that is already closing — use stop_job for that.

Input / Output

Same as pause_job, returns status: "cancelled".

resize_job

Change the number of tester slots in an active or paused job. Increasing slots requires sufficient credit balance for additional escrow. Decreasing cannot go below already-taken slots.

Input

Field	Type	Required	Description
`job_id`	uuid	Yes	Job ID
`target_testers`	integer	Yes	New total tester count

Output

{
  "previousTargetTesters": 5,
  "newTargetTesters": 10,
  "previousEscrowHoldCents": 3250,
  "newEscrowHoldCents": 6500,
  "escrowDeltaCents": 3250,
  "job": { "...": "full job detail with variant summaries" }
}

escrowDeltaCents is positive for additional hold, negative for released funds.

close_job

Close an eligible job and begin settlement. A job is closable when all testers finished, no testers are active, or all active testers exceeded their hard time limit.

If no testers completed work, the job is cancelled and all escrow is released. Otherwise, unused escrow capacity is released and the job enters pending_approval with a 24-hour auto-approve deadline.

Input

Field	Type	Required
`job_id`	uuid	Yes

Output

{
  "ok": true,
  "closedReason": "all_completed",
  "cancelled": false,
  "settlementStatus": "pending_approval",
  "settlementDeadline": "2025-01-16T10:30:00Z"
}

approve_job

Approve a job that is pending_approval. Releases remaining escrow hold, debits actual cost from credits, and marks all assignments as approved. Irreversible.

Input

Field	Type	Required
`job_id`	uuid	Yes

Output

{ "ok": true, "settlementStatus": "approved" }

submit_dispute

Dispute a job that is pending_approval. Flag specific categories and individual testers. Non-disputed testers are settled immediately. platform_issue and billing_discrepancy affect all testers.

Input

Field	Type	Required	Description
`job_id`	uuid	Yes	Job ID
`low_quality`	boolean	No	Low quality responses
`off_topic`	boolean	No	Off-topic responses
`suspected_fraud`	boolean	No	Suspected bot/fraud
`incomplete_work`	boolean	No	Incomplete work
`platform_issue`	boolean	No	Platform technical issues
`platform_issue_description`	string	No	Required if `platform_issue` is true
`billing_discrepancy`	boolean	No	Billing issues
`billing_discrepancy_description`	string	No	Required if `billing_discrepancy` is true
`testers`	TesterDispute[]	No	Per-tester dispute entries

TesterDispute

{
  "tester_user_id": "uuid",
  "category": "low_quality",
  "description": "Tester gave single-word answers to all questions"
}

Categories: low_quality, off_topic, suspected_fraud, incomplete_work

Output

{ "ok": true, "settlementStatus": "disputed" }

get_settlement_status

Get settlement details for a job, including escrow hold, per-assignment breakdown, closability, and any active dispute.

Input

Field	Type	Required
`job_id`	uuid	Yes

Output

{
  "jobId": "uuid",
  "jobStatus": "completed",
  "escrowHoldCents": 1950,
  "settlementStatus": "pending_approval",
  "settlementDeadline": "2025-01-16T10:30:00Z",
  "closable": false,
  "closableReason": "already_settled",
  "assignments": [
    {
      "id": "assignment-uuid",
      "testerId": 123456,
      "settlementStatus": "pending",
      "payoutCents": 300
    }
  ],
  "dispute": null
}