---
title: "Start creative tests"
method: POST
path: "/api/v1/research/creative-tests/start"
tags: ["research"]
---

# Start creative tests

`POST /api/v1/research/creative-tests/start`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/research/creative-tests/start`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Test a creative with an exact selected customer-version roster: interpret the creative, then launch one ordinary Research campaign. Name the creative by attachments uploaded with research.study-attachments (images, PDFs, text, MP3 or WAV audio, MP4 or WebM video), or, as a signed-in member, by the artifactId of a Studio creative or package, whose files Research imports under this request. First impressions use natural baseline reactions; buying scenarios prepare separate explicit situational context for every selected person before launch. Name metrics to rate every creative on each of them with one question on one shared scale, which the results' scorecard compares, and platforms to show the creative as people would meet it there. Preparation calls use Alpha credits and interviews use Research. With artifactId, brief is what to learn, in the member's words; Research names the creative by its title. Before anything is paid for, the start refuses an audience or seller it cannot use, more customers than a study interviews, files past a study's attachment bound, and an organization whose plan would refuse the test's interviews (research_creative_test_quotes_get answers the same first); pass that quote's expectedPrice to refuse a start whose interview price changed since. A same-key retry of an admitted test answers it with the exact frozen selection and imported files, without reading the creative again; read research_creative_tests_get_v2 for progress and research_results_get_v7 for the launched run's results.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- ResearchCreativeTestsStartRequest
  - `name` string, required
  - `brief` string, required: What to learn from the creative. With artifactId, Research names the selected creative before it; with attachments, the whole brief.
  - `sellerProfileId` string, uuid, nullable, required
  - `contentLanguage` 'en' | 'fr' | 'es' | 'de' | 'pt' | 'ja' | 'it' | 'nl' | 'sv' | 'cs' | 'pl' | 'tr' | 'ru' | 'zh-Hans' | 'ko' | 'ar', required
  - `audience` object, required
    - `audienceProfileId` string, uuid, required
    - `targetedGroupIds` string[], nullable, required
    - `targetedCustomerIds` string[], nullable, required
    - `targetInterviewCount` integer, required
  - `audienceNote` string: Anything more about who the people taking part are, in the member's own words; the Designer reads it after the brief.
  - `studyMode` union, required
    - object
      - `kind` 'first_impressions', required
    - object
      - `kind` 'buying_scenario', required
      - `direction` string, required
  - `metrics` string[]: What to rate each creative on. Each becomes one rating question per creative, which the results' scorecard compares. Omit to let the study choose its own questions.
  - `chooseMetrics` true: Let the study's Designer choose, from the brief, which metrics to rate each creative on (or none), as many as fit one study. Takes no metrics.
  - `platforms` string[]: Where the creative might run; the study shows it as people would meet it there. Platform fit needs at least one.
  - `attachments` object[]: Files already uploaded with research.study-attachments. Omit when artifactId names the creative.
    - `artifactId` string, required
    - `filename` string, required
    - `mediaType` 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'video/mp4' | 'video/webm' | 'audio/mpeg' | 'audio/wav', required
    - `byteLength` integer, required
  - `artifactId` string, uuid: An exact Studio creative artifact or package the signed-in member may read; Research imports its files under this request's Idempotency-Key. Members only; an API key passes attachments.
  - `expectedPrice` object: The expectedPrice research_creative_test_quotes_get answered for this audience: the start is refused, before anything is paid for, if the interviews it would run no longer price at it, and so is the launch, reserving nothing (failure launch, code price_changed), if they no longer do when they are reserved.
    - `productSlug` string, required
    - `dimensionKey` string, required
    - `unitPriceCents` integer, required
    - `quantity` integer, required
    - `totalCents` integer, required

## Response `202`

Accepted: the durable run started. Follow it with `GET /api/v1/platform/runs-v2/{id}`.

- ResearchCreativeTestsStartResponse
  - `name` string, required
  - `attachments` object[], required
    - `artifactId` string, required
    - `filename` string, required
    - `mediaType` 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'video/mp4' | 'video/webm' | 'audio/mpeg' | 'audio/wav', required
    - `byteLength` integer, required
  - `preparationRunId` string, uuid, required
  - `status` 'preparing' | 'unsupported' | 'failed' | 'launched', required: A test cancelled after launch (its campaign deleted, or its run stopped) reads failed here; research_creative_tests_get_v2 reads it cancelled.
  - `campaignId` string, uuid, nullable, required
  - `runId` string, uuid, nullable, required
  - `message` string, nullable, required
  - `studyMode` union, required
    - object
      - `kind` 'first_impressions', required
    - object
      - `kind` 'buying_scenario', required
      - `direction` string, required
  - `metrics` string[], required: What each creative is rated on, as the start named them or the Designer chose them; empty when the study chose its own questions, and until the Designer has chosen.
  - `platforms` string[], required: Where the creative might run.
  - `phase` 'reading_creative' | 'preparing_participants' | 'interviewing' | 'analyzing' | 'results' | 'failed' | 'unsupported', required
  - `selection` object[], required
    - `customerId` string, uuid, required
    - `customerVersionId` string, uuid, required
    - `version` integer, required
    - `contentFingerprint` string, required
    - `displayName` string, nullable, required
  - `plannedInterviewCount` integer, required
  - `preparation` object, required
    - `required` integer, required
    - `completed` integer, required
    - `failed` integer, required
  - `interviews` object, required
    - `completed` integer, required
    - `failed` integer, required
  - `interpretation` ResearchInterpretation, nullable, required
    - `brand` object, required
      - `value` string, required
      - `basis` 'customer_fact' | 'caller_fact' | 'creative_claim' | 'explicit_assumption' | 'unknown', required
    - `category` object, required
      - `value` string, required
      - `basis` 'customer_fact' | 'caller_fact' | 'creative_claim' | 'explicit_assumption' | 'unknown', required
    - `offering` object, required
      - `value` string, required
      - `basis` 'customer_fact' | 'caller_fact' | 'creative_claim' | 'explicit_assumption' | 'unknown', required
    - `intendedAudience` object, required
      - `value` string, required
      - `basis` 'customer_fact' | 'caller_fact' | 'creative_claim' | 'explicit_assumption' | 'unknown', required
    - `claims` object[], required
      - `value` string, required
      - `basis` 'customer_fact' | 'caller_fact' | 'creative_claim' | 'explicit_assumption' | 'unknown', required
    - `uncertainties` string[], required
  - `scenario` object, nullable, required
    - `condition` string, required
    - `respondentExposure` string, required
    - `limitations` string[], required

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/5241805fe425?raw)