Quick Start

Get started with run(human) in under 5 minutes.

1. Get Your API Key

First, sign up and create an API key from your dashboard:

1. Go to https://runhuman.com/signin
2. Sign in with your email
3. Navigate to the "API Keys" section
4. Click "Create New API Key" and give it a name
5. Copy your API key (shown only once!)

2. Make Your First API Call

Here's a simple example testing a button click:

const response = await fetch('https://runhuman.com/api/run', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.API_KEY}`
  },
  body: JSON.stringify({
    url: 'https://example.com',
    description: 'Click the "Get Started" button and verify it works',
    outputSchema: {
      buttonWorks: {
        type: 'boolean',
        description: 'Did the button click work successfully?'
      },
      errorMessage: {
        type: 'string',
        description: 'Any error message that appeared (or "None")'
      }
    }
  })
});

const result = await response.json();
console.log(result);
// { status: 'completed', result: { buttonWorks: true, errorMessage: 'None' } }

3. Understand the Response

The API returns a JSON object with the test results:

{
  "status": "completed",
  "result": {
    "buttonWorks": true,
    "errorMessage": "None"
  },
  "costUsd": 0.0036,
  "testDurationSeconds": 2
}

Next Steps

• Learn about authentication
• Create custom output schemas
• See more examples
• Read best practices

Authentication

All API requests require authentication using API keys.

API Keys

run(human) uses API keys to authenticate requests. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Creating API Keys

1. Sign in to your dashboard
2. Navigate to "API Keys"
3. Click "Create New API Key"
4. Give your key a descriptive name (e.g., "Production", "Staging")
5. Copy the key immediately (it's only shown once)

Managing API Keys

You can manage your API keys from the dashboard:

• View keys - See all your API keys and when they were last used
• Revoke keys - Disable a key immediately if compromised
• Delete keys - Permanently remove unused keys

Example with Environment Variables

Store your API key in an environment variable:

# .env file
RUNHUMAN_API_KEY=your_api_key_here

Then use it in your code:

const API_KEY = process.env.RUNHUMAN_API_KEY;

const response = await fetch('https://runhuman.com/api/run', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  },
  // ...
});

Core Concepts

Understanding the key concepts of run(human).

Jobs

A job is a single test request. When you call the API, you create a job that gets assigned to a human tester.

Job Lifecycle

1. pending - Job created, waiting for a tester to claim it
2. in_progress - A tester has claimed the job and is working on it
3. completed - Tester finished, AI extracted the data successfully
4. failed - Job failed due to an error
5. expired - Job wasn't completed in time (10 minute timeout)

Output Schemas

An output schema defines what data you want extracted from the tester's response. It's a JSON object where each field has:

• type - The data type (string, boolean, number)
• description - What you want the tester to check

{
  "buttonWorks": {
    "type": "boolean",
    "description": "Did the button click work?"
  },
  "loadTime": {
    "type": "string",
    "description": "How long did the page take to load?"
  }
}

Natural Language Processing

Testers don't provide JSON - they describe what they see in natural language:

{
  "buttonWorks": true,
  "loadTime": "about 2 seconds"
}

The "done" Keyword

Testers must end their final message with the word "done" to indicate they're finished. This prevents premature completion if the tester has more information to share.

Pricing Model

You're charged based on execution time - the time from when a tester claims the job until they finish:

• Rate: $0.0018 per second of execution time
• No charge for time spent waiting for a tester to claim the job
• Example: A 30-second test costs $0.054

API Reference

Complete reference for all run(human) API endpoints.

Base URL

https://runhuman.com/api

Request Format

All requests must:

• Use HTTPS
• Include Content-Type: application/json
• Include Authorization: Bearer YOUR_API_KEY
• Send data as JSON in the request body

Response Format

All responses are JSON with this structure:

{
  "status": "completed" | "failed" | "pending" | "in_progress",
  "result": { /* extracted data */ },
  "costUsd": 0.0036,  // Exact cost (only when completed)
  "testDurationSeconds": 2,  // Duration in seconds (only when completed)
  "error": "error message" | null
}

HTTP Status Codes

POST /api/run

Create a test job and wait for completion (synchronous).

Request

Headers

Body Parameters

Example Request

const response = await fetch('https://runhuman.com/api/run', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`
  },
  body: JSON.stringify({
    url: 'https://example.com/login',
    description: 'Test login with email: test@example.com, password: demo123',
    outputSchema: {
      loginSuccessful: {
        type: 'boolean',
        description: 'Did the login succeed?'
      },
      errorMessage: {
        type: 'string',
        description: 'Any error message shown (or "None")'
      },
      redirectedToDashboard: {
        type: 'boolean',
        description: 'Was user redirected to dashboard after login?'
      }
    }
  })
});

const result = await response.json();

Example Response

{
  "status": "completed",
  "result": {
    "loginSuccessful": true,
    "errorMessage": "None",
    "redirectedToDashboard": true
  },
  "costUsd": 0.0054,
  "testDurationSeconds": 3,
  "error": null
}

Timeout

The request will wait up to 10 minutes for completion. If the job doesn't complete in time, you'll receive a timeout response:

{
  "status": "expired",
  "result": null,
  "error": "Job timed out after 10 minutes"
}

Pricing

Simple, transparent pricing based on actual usage.

Pay Per Second

What You Pay For

• ✅ Execution time - Time from claim to completion
• ❌ Not waiting time - Time before a tester claims the job
• ❌ Not failed jobs - No charge if the job fails

Example Costs

Volume Discounts

Contact us at hey@runhuman.com for enterprise pricing and volume discounts.

Support

We're here to help!

Get Help

• Email: hey@runhuman.com
• GitHub: Open an issue
• Status: Check system status

Response Times

• Critical issues: Within 1 hour
• General support: Within 24 hours
• Feature requests: Within 1 week