Test options reference

The detailed companion to How to run a test. Every polis_test (and polis_estimate) input and what it changes.

content_type

How the content is framed to the personas. This changes the viewing context the personas are put in, which changes how they react.

content_type	What it is	Framing
`text`	Any raw copy	Generic short read
`tweet`	A tweet or short post	Encountered in a fast feed, low attention, high skepticism
`linkedin`	A LinkedIn post	Professional feed, scroll context
`markdown`	A long-form article or doc	Arrived to read; judged in the first screens
`url`	A public web page	Landing page they just opened

For text, tweet, linkedin, markdown pass the content in content. For url pass url instead.

url_mode (url only)

url_mode	What happens	Use it for	Cost
`copy` (default)	Polis scrapes the page text and tests the message	Testing the words, value prop, and offer	Standard per-persona
`visual`	Polis screenshots the page; vision-capable personas react to the actual design and layout	Testing the design, hierarchy, and first impression	~3x per persona (vision models + image)

visual runs can return structuralNotes (layout advice). copy runs do not.

audience

Optional. A short description of who you are targeting (for example "early-stage B2B founders evaluating analytics tools"). If you omit it, Polis infers the realistic audience from the content, including adjacent and accidental viewers. Set it when the content alone would not reveal the intended audience, or when you want to test against a specific segment.

persona_count

How many synthetic personas to simulate. Range 10 to 1000, default 100. More personas means tighter, more reliable segments and friction, and more cost (it scales roughly linearly). Rough guidance:

10 to 50 — fast gut check, cheap, directional only.
100 — standard test, good signal for most decisions.
300 to 500 — high-confidence read before a launch or paid campaign.
1000 — maximum resolution; mind your spend limit.

Always polis_estimate first; cost scales with this number. See Pricing & billing.

Full report schema

polis_report returns:

{
  "run_id": "string",
  "status": "complete",
  "ready": true,
  "content_type": "tweet",
  "url": "string | null",
  "audience": "string | null",
  "personas_reacted": 100,
  "stats": {
    "decisions": { "stay": 0, "scroll": 0, "click": 0, "save": 0 },
    "mean_intent": 0.0,
    "model_distribution": { "model": 0 }
  },
  "archetypes": [
    { "name": "string", "description": "string", "weight": 0.0 }
  ],
  "synthesis": {
    "segments": [ { "name": "string", "share": 0.0, "summary": "string" } ],
    "topFriction": [ { "point": "string", "severity": 0, "evidence": "string" } ],
    "rewrite": "string",
    "structuralNotes": ["string"]
  },
  "sample_reactions": [
    {
      "archetype": "string",
      "first_glance": "string",
      "decision": "stay|scroll|click|save",
      "noticed_first": "string",
      "friction": "string",
      "quote": "string",
      "intent": 0
    }
  ]
}

archetypes is the audience panel Polis generated (the segments it expected to find). synthesis is the deliverable. See How to run a test for what each field means and how to act on it.

Failure and refunds

If a run fails before producing a report (for example a URL that cannot be fetched), polis_status and polis_report return the error and the tokens are refunded automatically. Trial and inactive accounts can only run tests that fit within their remaining token balance; a run needing metered overage returns subscription_required with the plan options.

All docs

What Polis is: The concept, inputs, and what you get back.
Agent quickstart: Connect, get a key, run a test, read the report.
How to run a test: The workflow, a worked example, and how to read the report.
Test options reference (you are here): Every input, every variation, and the full report schema.
MCP tools: Every tool, its inputs, and cost.
Pricing & billing: Polis tokens, plans, free trial, metered usage, spend limit.
Discovery & well-known endpoints: How agents and clients discover Polis.

Polis docs index · Full machine-readable index (llms.txt) · Everything inlined (llms-full.txt)