> Full machine-readable index: https://polis.ai/llms.txt

[Polis](https://polis.ai) · [All docs](https://polis.ai/docs) · [llms.txt](https://polis.ai/llms.txt) · [llms-full.txt](https://polis.ai/llms-full.txt)

# Test options reference

The detailed companion to [How to run a test](https://polis.ai/docs/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](https://polis.ai/docs/pricing).

## Full report schema

`polis_report` returns:

```json
{
  "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](https://polis.ai/docs/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](https://polis.ai/docs/overview.md): The concept, inputs, and what you get back.
- [Agent quickstart](https://polis.ai/docs/quickstart.md): Connect, get a key, run a test, read the report.
- [How to run a test](https://polis.ai/docs/run-a-test.md): The workflow, a worked example, and how to read the report.
- [Test options reference](https://polis.ai/docs/test-options.md) (you are here): Every input, every variation, and the full report schema.
- [MCP tools](https://polis.ai/docs/mcp-tools.md): Every tool, its inputs, and cost.
- [Pricing & billing](https://polis.ai/docs/pricing.md): Polis tokens, plans, free trial, metered usage, spend limit.
- [Discovery & well-known endpoints](https://polis.ai/docs/discovery.md): How agents and clients discover Polis.

[Polis docs index](https://polis.ai/docs) · [Full machine-readable index (llms.txt)](https://polis.ai/llms.txt) · [Everything inlined (llms-full.txt)](https://polis.ai/llms-full.txt)