Human Signal

Human Signal is a survey-style mode for asking real people a single, focused question and getting a quantified answer back in hours. It’s designed for moments when you don’t need a full Study with long Interviews — you just need to know whether a tagline lands, which option people prefer, or how a claim is read. Each Human Signal run creates a lightweight Study under the hood, recruits Participants, collects short Responses, and returns a structured result with a headline metric, supporting reasons, and minority objections.

When to use Human Signal vs. a full Study

The two modes solve different problems. Pick based on the question you’re trying to answer.

	Human Signal	Full Study
Best for	Quick gut-check on one artifact	Deep exploration of a topic
Format	Short survey-style Responses	Multi-question Interviews (voice or chat)
Sample size	3-200 Participants	Typically 10-50 Participants
Turnaround	1-24 hours (you set the budget)	Days
Output	Headline metric + reasons + objections	Transcripts, themes, full report
How you launch	Human Signal API or unified MCP Panel workflow	Studio UI or MCP

Use Human Signal when you have a specific artifact (a tagline, a claim, a button label, two competing options) and you want a number plus a few sentences of “why.” Use a full Study when you want open-ended discovery, long-form conversation, or multiple linked questions per Participant.

Human Signal is exposed through the API. Over MCP, use the unified Panel-study workflow described below; there is no separate ask_humans tool. There is no separate Human Signal tab in the dashboard — completed runs appear alongside your other Studies and link to a dashboard URL returned in the response.

The three modes

Every Human Signal run has a mode that shapes how the question is asked and how Responses are aggregated.

preference

Compare 2-5 options and find out which one people prefer. Requires an options list. Best for taglines, naming, layouts, value props.

claim

Test whether people believe or agree with a single statement. Best for marketing claims, pricing assertions, or positioning lines.

message

Check whether a message is clear and what people think it means. Best for onboarding copy, error messages, or feature descriptions.

Asking a question

Human Signal is invoked through the REST API. From an AI assistant connected to the User Intuition MCP server, use the same supported study and Panel tools as any other research workflow. The legacy ask_humans tool is not registered.

MCP (Panel study)
REST API
Dry run

From any MCP-aware client connected to the User Intuition MCP server:

{
  "tool": "create_study",
  "arguments": {
    "name": "Meal-kit tagline preference",
    "recruiting_method": "panel",
    "interview_format": "chat",
    "language": "en"
  }
}

Next call customize_study with the returned study_id and the user’s request—for example, “Learn which of these two taglines resonates more with busy parents and why.” Relay any returned question to the user and send their answer back through customize_study.After get_study confirms the plan is persisted and provisioned, call launch_panel with target: 25, incident_rate: 100, country_code: "US", and dry_run: true. Show the returned cost and timeline, get the user’s approval, then repeat the launch with dry_run: false. Track fieldwork with get_study and list_interviews; once enough Interviews are complete, use generate_report and get_study_report.

POST /api/human-signal/ask

{
  "mode": "claim",
  "text": "Our app saves the average user 3 hours a week.",
  "audience": "general",
  "n": 50,
  "voice": false,
  "time_budget_hours": 6,
  "redact_pii": true
}

Authenticate with a bearer token (Clerk JWT or a User Intuition API key). The response includes a study_id you can use to poll for results.

Set dry_run: true to get a cost and ETA estimate without creating a Study or charging your wallet:

{
  "mode": "preference",
  "text": "Pick a button label.",
  "options": ["Get started", "Try it free"],
  "n": 25,
  "dry_run": true
}

Returns estimated_cost, eta_hours_range, and any validation_warnings.

Key request fields

Field	Description
`mode`	`preference`, `claim`, or `message`
`text`	The artifact under test (1-5000 characters)
`options`	2-5 strings, required when `mode = "preference"`
`context`	Background shown to the AI moderator (not to Participants)
`audience`	`general` (recruit from the panel) or `custom` (you supply emails)
`emails`	Up to 200 addresses for `custom` audience
`screeners`	Up to 3 screening questions for `general` audience
`n`	Target sample size, 3-200
`voice`	`true` for voice Interviews, `false` for chat (default)
`time_budget_hours`	1-24; how long fielding stays open before partial results are returned
`locale`	Language/region tag, e.g. `en-US`
`include_transcripts`	Include raw Response transcripts in results
`redact_pii`	Strip PII from results (default `true`)

Getting results back

GET /api/human-signal/{study_id}/results returns the current status and, once available, the structured result.

creating

The Study record exists and the AI moderator and Interview script are being generated.

queued / fielding

Recruitment and Participant Responses are in flight. progress.completed ticks up as Responses arrive.

complete or partial

Fielding finished. complete means the target n was hit; partial means the time_budget_hours expired before reaching n. Either way, results contains the analyzed output.

failed or cancelled

The run stopped before producing a usable result. failure_reason and cost_incurred are populated.

The results object contains a headline metric appropriate to the mode (e.g. percentage preferring each option), the top reasons Participants gave, and any minority objections. Transcripts are included only when include_transcripts: true was set.

Listing your runs

GET /api/human-signal/ returns a paginated list of your Human Signal Studies, each with a short summary and (for completed runs) a headline_metric. Filter by status and created_after as needed.

Editing and cancelling

Human Signal Studies are editable while they are still creating, queued, or fielding. PATCH /api/human-signal/{study_id} accepts any subset of the original request fields. Note these behaviors:

Changing content fields (text, mode, options, context, audience) regenerates the moderation guide in the background. The response sets regenerating: true.
If the Study is already fielding and Responses have been collected, you’ll get a warning that earlier Responses were collected under the previous guide and may not be directly comparable.
You cannot reduce n below the number of already-completed Interviews.
Changing n or voice recalculates estimated_cost.

POST /api/human-signal/{study_id}/cancel stops a running Study. Cost incurred so far (based on completed Interviews) is captured and returned as cost_incurred; nothing further is charged.

Studies in complete, partial, or cancelled status cannot be cancelled or edited.

Expiry and partial results

Every Human Signal run has a time_budget_hours (1-24, default 3). A scheduled job sweeps for Studies whose budget has expired while still fielding. When that happens:

The Study transitions to partial.
Whatever Responses have been collected are analyzed and returned in results.
You are charged only for Interviews that actually completed.

This means setting a tight time_budget_hours is safe — you’ll always get something back, even if the panel didn’t fill in time.

Pricing

Human Signal uses the same wallet and credit system as the rest of User Intuition. Cost is computed per completed Participant and depends on:

Whether the run is chat or voice (voice is more expensive)
Your plan’s effective per-Participant rate

Before a Study is created, your wallet balance is checked against the estimated cost. If it’s short, the API returns an insufficient_credits response with the deficit and a top-up URL — no Study is created and no funds are held. Use dry_run: true to preview the cost first. For exact rates, see your plan details in the billing settings.

Limits

Limit	Value
`text` length	1-5,000 characters
`options` count (preference mode)	2-5
`n` (sample size)	3-200
`time_budget_hours`	1-24
`screeners`	Max 3, general audience only
`emails` (custom audience)	Max 200

Getting Started

Study Types

Creating a Study

Recruiting Participants

Managing Your Study

Reviewing Your Results

Integrations

Resources

When to use Human Signal vs. a full Study

The three modes

preference

claim

message

Asking a question

Key request fields

Getting results back

Listing your runs

Editing and cancelling

Expiry and partial results

Pricing

Limits

Next steps

Human Signal over MCP

Full Studies

​When to use Human Signal vs. a full Study

​The three modes

preference

claim

message

​Asking a question

​Key request fields

​Getting results back

​Listing your runs

​Editing and cancelling

​Expiry and partial results

​Pricing

​Limits

​Next steps

Human Signal over MCP

Full Studies

When to use Human Signal vs. a full Study

The three modes

Asking a question

Key request fields

Getting results back

Listing your runs

Editing and cancelling

Expiry and partial results

Pricing

Limits

Next steps