Reference

Complete technical specification for Runhuman. Integration guides link here for shared details.

Job Lifecycle

Every test moves through these states, matching the chips on the Jobs dashboard:

Status	Description	Terminal
Pending	Job created; the platform is preparing it for testers	No
Queued	Released to testers, awaiting claim	No
Working	A tester has claimed the job and is actively testing	No
Completed	Tester submitted results and AI extraction succeeded	Yes
Cancelled	Tester or admin ended the job before submitting results	Yes
Expired	No tester claimed in time, or the claimed tester ran out the clock	Yes
Failed	Test could not produce a result (AI extraction failed, platform error, or the target URL wasn’t reachable)	Yes

Terminal statuses will not change. Non-terminal statuses should be polled until resolution.

Output Schema

Define the structure of data you want extracted from the tester’s response.

Format

{
  [fieldName: string]: {
    type: "boolean" | "string" | "number" | "array" | "object";
    description: string;
    example?: any;
  }
}

Example

{
  "loginWorks": {
    "type": "boolean",
    "description": "Does login work with valid credentials?"
  },
  "errorMessage": {
    "type": "string",
    "description": "What error appears for invalid password?"
  },
  "issuesFound": {
    "type": "array",
    "description": "List of any UI/UX issues discovered"
  }
}

Keep schemas simple. Testers describe findings in natural language, and AI extracts structured data matching your schema.

Cost

Tests are billed per second at $0.0085/second.

Duration	Cost
60 seconds	$0.51
120 seconds	$1.02
300 seconds (5 min)	$2.55
600 seconds (10 min)	$5.10

Duration is rounded up using Math.ceil(). A test lasting 61 seconds costs the same as 62 seconds. Cost is stored at full precision, not rounded to cents.

Request Parameters

These parameters apply to all job creation endpoints (POST /api/jobs, POST /api/run).

Parameter	Type	Required	Description
projectId	string	Conditional	Project ID. Required unless using an org-scoped API key with `githubRepos` for auto-creation
organizationId	string	No	Organization ID. Used with PATs when `projectId` is not provided
url	string	Conditional	URL for the tester to visit. Required for simple jobs; optional with `prNumbers`, `issueNumbers`, or `template`
description	string	Conditional	Instructions for the tester. Required for simple jobs; optional with `prNumbers`, `issueNumbers`, or `template`
outputSchema	object	No	JSON Schema defining data to extract. If omitted, only success/explanation returned
resultsTemplate	string	No	MDForm template for free-form text reports (alternative to `outputSchema`)
template	string	No	Template name to use as base configuration. See Templates.
templateContent	string	No	Raw template content (markdown with YAML frontmatter). See Templates.
targetDurationMinutes	number	No	Time limit in minutes. Default: 30. Range: 1-120. Total with extensions must not exceed 120
maxExtensionMinutes	number	No	Total extension time in minutes. Default: 15
maxExtensionCount	number	No	Number of extensions. Default: 3. Set to 0 to disable extensions
additionalValidationInstructions	string	No	Custom instructions for AI result validation
deviceClass	string	No	Device class: `"desktop"` or `"mobile"`
githubRepos	string[]	No	GitHub repos (`["owner/repo"]`). Required when using `prNumbers` or `issueNumbers`
githubRepo	string	No	Single GitHub repo (`"owner/repo"`). Use `githubRepos` for multiple

additionalValidationInstructions

Use this parameter to guide how AI interprets results:

{
  "additionalValidationInstructions": "Ignore minor UI glitches in the header. Focus only on whether the order was placed and confirmation number displayed."
}

deviceClass

Control the browser viewport for testing different devices:

Device Class	Dimensions
desktop	1600x900
mobile	375x812 (portrait)

Response Fields

Job status responses (GET /api/jobs/:jobId) return these fields:

Field	Type	Description
id	string	Unique job identifier
status	string	Job status (see Job Lifecycle)
result	object	Extracted data matching your outputSchema
result.success	boolean	Whether extraction succeeded
result.explanation	string	AI’s interpretation of the test
result.data	object	Structured data matching your schema
error	string	Error message (if job failed)
reason	string	Failure reason category
claimedAt	string	Timestamp when tester claimed the job
completedAt	string	Timestamp when job completed
costUsd	number	Total cost in USD
testDurationSeconds	number	Time the tester spent
extractedIssues	array	AI-extracted issues with titles, descriptions, severity, reproduction steps, suggested labels, and related existing issues (see Extracted Issues below)
testerResponse	string	Raw natural language feedback before extraction
testerAlias	string	Anonymized tester name (e.g., “Phoenix”)
testerAvatarUrl	string	Avatar image URL for UI display
testerData	object	Captured testing artifacts
jobUrl	string	Full URL to view job on the dashboard
projectName	string	Name of the project this job belongs to
keyMoments	array	Key moments from test execution timeline
targetDurationMinutes	number	Configured time limit for the test
maxExtensionMinutes	number	Total extension time in minutes
maxExtensionCount	number	Number of extensions allowed
extensionsUsed	number	Number of extensions the tester has used
responseDeadline	string	Timestamp when tester response is due

Fields like result, costUsd, testerResponse, and testerData only appear when status is completed.

Tester Data

The testerData object contains artifacts captured during the test session:

{
  testDurationSeconds: number;
  consoleMessages: Array<{
    type: string;       // "log", "error", "warn", etc.
    message: string;
    timestamp: string;
  }>;
  networkRequests: Array<{
    url: string;
    method: string;     // "GET", "POST", etc.
    status?: number;    // HTTP status code
    timestamp: string;
  }>;
  clicks: Array<{
    x: number;
    y: number;
    timestamp: string;
    element?: string;   // Element selector if available
  }>;
  videoUrl?: string;      // URL to session recording
}

Extracted Issues

The extractedIssues field contains AI-extracted issues from the tester’s findings. Each issue includes structured data and optional related issue detection (when a GitHub repo is linked).

interface ReproductionStep {
  text: string;                     // Step description
  videoOffsetSeconds?: number;      // Video offset in seconds for this step
}

interface ExtractedIssue {
  title: string;                    // Short issue title
  description: string;              // Detailed description of the finding
  severity: 'critical' | 'high' | 'medium' | 'low';
  expectedBehavior: string;         // What should have happened (grounded in the tester's task)
  actualBehavior: string;           // What actually happened (grounded in telemetry)
  affectedArea: string;             // Specific element + route, e.g. "Login button at /login"
  evidenceCitations: EvidenceCitation[];  // Timestamped citations from session telemetry
  reproductionSteps: ReproductionStep[];  // Numbered steps to reproduce with optional video timestamps
  videoOffsetSeconds?: number;      // Video offset when the bug is most visible
  suggestedLabels: string[];        // Suggested GitHub labels (e.g., ["bug", "ui"])
  relatedEvidence?: RelatedEvidence[];  // Stage-4 telemetry decorations grouped by category
  relatedSentryEventIds?: string[];  // IDs of Sentry events linked to this issue
  relatedIssues?: RelatedIssueInfo[];  // Existing issues that match this finding
}

interface EvidenceCitation {
  timestamp: string;                // ISO timestamp of the cited event
  source: 'console' | 'network' | 'sentry' | 'page_state' | 'voice' | 'chat' | 'crash' | 'interaction';
  summary: string;                  // One-line summary of what the citation shows
  videoOffsetSeconds: number | null;  // Video offset for this citation, or null if outside the recording
}

interface RelatedEvidence {
  category: 'network' | 'console' | 'crash' | 'page_state' | 'sentry';
  timestamp: string;                // ISO timestamp of the evidence
  summary: string;                  // One-line summary
  detail?: string;                  // Optional deeper detail (e.g. network failure reason)
}

interface RelatedIssueInfo {
  issueNumber: number;              // GitHub issue number
  title: string;                    // Issue title
  state: 'open' | 'closed';        // Current issue state
  relation: 'duplicate' | 'related';  // How this issue relates
  confidence: number;               // 0.0–1.0 confidence score
  reason: string;                   // Why this issue is related
}

Example

{
  "extractedIssues": [
    {
      "title": "Checkout button unresponsive on mobile",
      "description": "The 'Place Order' button does not respond to taps on mobile Safari.",
      "severity": "high",
      "expectedBehavior": "Tapping 'Place Order' submits the cart and navigates to the order-confirmation page.",
      "actualBehavior": "Tapping 'Place Order' produces no visible response and the user stays on /checkout.",
      "affectedArea": "'Place Order' button (button[data-testid='checkout-submit']) at /checkout on mobile Safari",
      "evidenceCitations": [
        { "timestamp": "2026-04-20T15:02:11.400Z", "source": "console", "summary": "TypeError: submitOrder is not a function", "videoOffsetSeconds": 68 },
        { "timestamp": "2026-04-20T15:02:11.480Z", "source": "interaction", "summary": "click on 'Place Order' button, no navigation followed", "videoOffsetSeconds": 68 }
      ],
      "reproductionSteps": [
        { "text": "Open the site on mobile Safari", "videoOffsetSeconds": 12 },
        { "text": "Add items to cart", "videoOffsetSeconds": 35 },
        { "text": "Navigate to checkout", "videoOffsetSeconds": 52 },
        { "text": "Tap 'Place Order' — nothing happens", "videoOffsetSeconds": 68 }
      ],
      "videoOffsetSeconds": 68,
      "suggestedLabels": ["bug", "mobile"],
      "relatedEvidence": [
        { "category": "console", "timestamp": "2026-04-20T15:02:11.400Z", "summary": "TypeError: submitOrder is not a function", "detail": "Thrown at CheckoutPage.tsx:142" }
      ],
      "relatedSentryEventIds": ["b3f4c92d1a8e4f5c"],
      "relatedIssues": [
        {
          "issueNumber": 42,
          "title": "Checkout button broken on Safari",
          "state": "closed",
          "relation": "duplicate",
          "confidence": 0.85,
          "reason": "Same Safari checkout button issue, previously fixed but appears to have regressed"
        },
        {
          "issueNumber": 99,
          "title": "Mobile tap targets too small",
          "state": "open",
          "relation": "related",
          "confidence": 0.45,
          "reason": "Related mobile interaction issue with touch targets"
        }
      ]
    }
  ]
}

When the project has a linked GitHub repository with access, the AI compares each extracted issue against existing GitHub issues:

duplicate (confidence > 70%): The finding matches an existing issue. Use this to comment on the existing issue instead of creating a duplicate.
related (confidence 30–70%): The finding is similar but distinct. Mention these when creating a new issue for additional context.

Issues with confidence below 30% are not included.

API Endpoints

POST /api/run

Synchronous endpoint. Creates a job and waits for completion, blocking up to 60 minutes.

Request:

{
  "url": "https://example.com",
  "description": "Test the checkout flow",
  "outputSchema": {
    "checkoutWorks": { "type": "boolean", "description": "Order placed successfully?" }
  }
}

Response (200):

{
  "id": "job_abc123",
  "status": "completed",
  "result": {
    "success": true,
    "explanation": "Checkout completed successfully",
    "data": { "checkoutWorks": true }
  },
  "costUsd": 0.396,
  "testDurationSeconds": 220,
  "testerResponse": "I completed the checkout...",
  "testerAlias": "Phoenix",
  "testerAvatarUrl": "https://...",
  "testerData": { "..." : "..." }
}

Response (408): Test did not complete within 60 minutes.

POST /api/jobs

Asynchronous endpoint. Creates a job and returns immediately.

Response (201):

{
  "jobId": "job_abc123",
  "message": "Job created successfully. Use GET /api/jobs/:jobId to check status."
}

When prNumbers or issueNumbers are provided, the job starts in preparing status while AI generates the test plan:

{
  "jobId": "job_abc123",
  "message": "Job created with status preparing. AI is generating the test plan.",
  "testability": { "testable": true, "reason": "..." }
}

GET /api/jobs/:jobId

Retrieves full job details including conversation history. Requires authentication.

Response:

{
  "id": "job_abc123",
  "status": "completed",
  "result": {
    "success": true,
    "explanation": "Checkout completed successfully",
    "data": { "checkoutWorks": true }
  },
  "costUsd": 0.54,
  "testDurationSeconds": 300,
  "testerResponse": "I completed the checkout flow...",
  "testerAlias": "Phoenix",
  "testerAvatarUrl": "https://...",
  "testerData": { "..." : "..." },
  "jobUrl": "https://runhuman.com/dashboard/proj_abc/jobs/job_abc123",
  "projectName": "My Web App",
  "keyMoments": []
}

See Response Fields for the complete field reference.

GET /api/jobs/:jobId/status

Lightweight status check. Returns the same fields as GET /api/jobs/:jobId but without conversation history. Does not require authentication — useful for webhooks and external polling.

MCP Tools

For full MCP documentation, see the MCP guide. Below is a summary of available tools.

Runhuman exposes 7 MCP tools:

Tool	Description
`list_organizations`	List organizations the user belongs to
`list_projects`	List projects, optionally filtered by organization
`create_job`	Create a custom QA test job
`run_template`	Create a job from a pre-configured template
`wait`	Poll for job completion (automatic retry)
`get_job`	Quick status check without waiting
`list_templates`	List available templates for a project

Error Codes

HTTP Status	Meaning
400	Bad request. Invalid parameters.
401	Unauthorized. Invalid or missing API key/PAT.
403	Forbidden. Insufficient permissions.
404	Not found. Resource does not exist.
408	Timeout. Synchronous request exceeded 60 minutes.
500	Server error.

All errors return this format:

{
  "error": "Error type",
  "message": "Detailed description"
}

Authentication

Include your API key or Personal Access Token in the Authorization header:

Authorization: Bearer YOUR_API_KEY_OR_PAT

Two token types:

API Keys — Organization-scoped. Get from your organization’s API Keys page in the Dashboard.
Personal Access Tokens (PATs) — User-scoped. Create from Settings > Tokens.

See the REST API guide for details on when to use each type.

Reference

Job Lifecycle

Output Schema

Format

Example

Cost

Request Parameters

additionalValidationInstructions

deviceClass

Response Fields

Tester Data

Extracted Issues

Example

How Related Issues Work

API Endpoints

POST /api/run

POST /api/jobs

GET /api/jobs/:jobId

GET /api/jobs/:jobId/status

MCP Tools

Error Codes

Authentication