Audiences

Every scoring request needs an audience. It is what the persona is built from, and it conditions every score in the response. Send exactly one of audience or audience_id — not both.

Inline audiences

Define the audience in the request. Only name is required.

{
  "audience": {
    "name": "Millennial pet owners",
    "description": "Dog owners aged 25-34, mid-income, active on Instagram",
    "demographics": {
      "ageRange": "25-34",
      "incomeLevel": "50k-75k",
      "priceSensitivity": "moderate",
      "shoppingIntent": "researching",
      "platformFatigue": "high"
    }
  }
}

Inline is the right choice for one-off runs and for agents generating audiences on the fly.

Saved audiences

Reference an audience already created in your Kettio account:

{ "audience_id": "aud_7c2b0d7e" }

A 404 means the ID does not exist or is not owned by the authenticated account.

Saved audiences are the better choice when you are comparing results over time. An inline audience that drifts between runs quietly invalidates the comparison, because scores are conditioned on the audience.

Demographics

All demographics fields are optional, and sensible defaults are applied. They shape the persona’s attitude and behavior rather than filtering anything.

Field	Accepted values
`ageRange`	`18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+`
`incomeLevel`	`under-25k`, `25k-50k`, `50k-75k`, `75k-100k`, `100k-150k`, `150k+`
`adSkepticism`	`very-low`, `low`, `moderate`, `high`, `very-high`
`trustBaseline`	`very-low`, `low`, `moderate`, `high`, `very-high`
`priceSensitivity`	`very-low`, `low`, `moderate`, `high`, `very-high`
`categoryFamiliarity`	`none`, `casual`, `knowledgeable`, `expert`
`shoppingIntent`	`browsing`, `researching`, `comparing`, `ready-to-buy`
`urgency`	`none`, `low`, `moderate`, `high`, `urgent`
`brandFamiliarity`	`unaware`, `heard-of`, `familiar`, `loyal`
`platformFatigue`	`low`, `medium`, `high`, `very-high`

Writing a description that does work

description is free text and it carries real weight — it is the part of the audience the persona reads directly.

Useful

“Women considering GLP-1 support who need credible purchase proof”Names the buying situation and the objection to overcome.

Not useful

“Our target customers”Carries no information the persona can act on.

Describe the purchase situation, not the demographic profile — the structured demographics fields already cover the profile.

Changing the audience between runs changes what is being measured. If you are comparing two sets of creative, hold the audience fixed across both.

Get started

Guides

Concepts

MCP server

Changelog

Inline audiences

Saved audiences

Demographics

Writing a description that does work

Useful

Not useful

​Inline audiences

​Saved audiences

​Demographics

​Writing a description that does work

Useful

Not useful

Inline audiences

Saved audiences

Demographics

Writing a description that does work