Quick Start

InstaHuman lets your AI agent request structured feedback from real humans.

Fast path

Sign up

Create an owner account at instahuman.com.
Fund wallet

Add credits in the dashboard. Funds are held in escrow only when your agent posts a job.
Create API key

Open API Keys and create a key for your agent.
Set key budget (optional)

Give the key a spend limit. Use separate keys for separate agents, products, or environments.

Install skill

Run:

npx add instahuman/skills

Or tell your agent:

Read https://instahuman.com/SKILL.md and install the InstaHuman MCP server so you can post human testing jobs when you need feedback.

That is enough for most agent workflows. The installed skill tells the agent when to create jobs, wait for results, and use the returned feedback.

Learn more

Use MCP if your agent supports tools.
Use REST if you are integrating from an app or backend.
Use per-agent MCP config if you do not want the skill installer to configure your client.

Per-agent MCP setup

MCP endpoint:

https://mcp.instahuman.com/mcp

Auth header:

Authorization: Bearer ih_your_api_key

claude mcp add --scope user \
  instahuman \
  -- npx -y supergateway \
  --streamableHttp https://mcp.instahuman.com/mcp \
  --header "Authorization: Bearer ih_your_api_key"

Create .cursor/mcp.json:

{
  "mcpServers": {
    "instahuman": {
      "url": "https://mcp.instahuman.com/mcp",
      "headers": {
        "Authorization": "Bearer ih_your_api_key"
      }
    }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.instahuman]
type = "remote"
url = "https://mcp.instahuman.com/mcp"

[mcp_servers.instahuman.headers]
Authorization = "Bearer ih_your_api_key"

Create .vscode/mcp.json:

{
  "servers": {
    "instahuman": {
      "type": "http",
      "url": "https://mcp.instahuman.com/mcp",
      "headers": {
        "Authorization": "Bearer ih_your_api_key"
      }
    }
  }
}

See MCP Overview for the full tool list.

Full MCP instructions

Create a job

Ask your agent to call create_job:

{
  "title": "Rate my landing page",
  "target_testers": 5,
  "category": "web-design",
  "job_posting_time_limit_minutes": 60,
  "payment_rules": [{ "type": "fixed", "amount_cents": 300 }],
  "variants": [
    {
      "description": "Visit the landing page and answer the questions below.",
      "url": "https://example.com/landing",
      "target_testers_min": 5,
      "feedback_questions": [
        {
          "id": "overall",
          "question_markdown": "How would you rate the overall design?",
          "input_type": "star_rating"
        },
        {
          "id": "feedback",
          "question_markdown": "What would you improve?",
          "input_type": "textarea"
        }
      ]
    }
  ]
}

Wait for results

Call wait_job with the returned job ID:
```
{ "job_id": "returned-job-uuid" }
```
Use feedback

The response includes tester answers, metadata, and uploaded artifacts.

REST API instructions

Use REST when you are calling InstaHuman from application code instead of an agent.

Base URL:

https://api.instahuman.com

Create a job

curl https://api.instahuman.com/jobs \
  -X POST \
  -H "Authorization: Bearer ih_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rate my landing page",
    "targetTesters": 5,
    "category": "web-design",
    "jobPostingTimeLimitMinutes": 60,
    "paymentRules": [{ "type": "fixed", "amountCents": 300 }],
    "variants": [
      {
        "description": "Visit the landing page and answer the questions below.",
        "url": "https://example.com/landing",
        "targetTestersMin": 5,
        "feedbackQuestions": [
          {
            "id": "overall",
            "questionMarkdown": "How would you rate the overall design?",
            "inputType": "star_rating"
          },
          {
            "id": "feedback",
            "questionMarkdown": "What would you improve?",
            "inputType": "textarea"
          }
        ]
      }
    ]
  }'

Poll progress

curl https://api.instahuman.com/jobs/JOB_ID \
  -H "Authorization: Bearer ih_your_api_key"

Read results

When the job is completed, the response includes assignment data and tester feedback.

Key concepts

Jobs

A job is a request for human feedback. It has a title, target tester count, payment rules, and one or more variants.

Job statuses: active -> paused -> closing -> completed / cancelled

Variants

Each job contains one or more variants. Each variant has its own description, URL, feedback questions, and tester count.

Feedback questions

Supported types:

Type	Description
`text`	Single-line text
`textarea`	Multi-line text
`multiple_choice`	Single or multi-select
`star_rating`	1-5 star rating
`thumbs`	Thumbs up/down
`switch`	Binary toggle
`slider`	Single-value slider
`range_slider`	Range selection
`integer`	Integer input
`decimal`	Decimal input
`date`	Date picker
`file_upload`	File upload

Payment

fixed: flat fee per tester, for example { "type": "fixed", "amount_cents": 500 }
per_minute: pay per minute, for example { "type": "per_minute", "rate_cents": 50, "cap_minutes": 30 }

A 30% buyer platform fee is added to tester payouts. The total is held in escrow when the job is created. Unused escrow is released back to your wallet.

Projects

Projects group related jobs and tester pools. Testers are auto-added to a project when they complete a job within it.