Developers

Developer docs

Run product page tests, UI A/B tests and the Assistant from your own code with the REST API and the Python SDK 0.3.0.

API base URL
https://qyzkdesign.com/api/v1

Quick start

1. Create an API key

Sign up (we email you a code to verify your address), then create a key on the API keys page of the dashboard. Keys start with fl_; send them as Authorization: Bearer fl_... and keep them secret. A key is shown only once: if you did not copy it, revoke it and create a new one.

Create an API key

2. Install the Python SDK

The SDK (package facetlab, version 0.3.0, Python 3.8 or later) is not on PyPI yet. Install or upgrade it from GitHub:

Code example
pip install -U git+https://github.com/qyzk/facetlab-sdk-public.git

SDK source on GitHub

3. Run a product page test

estimate checks readiness, audience size and credits and creates nothing. create checks the images, creates the test, uploads one image per variant and starts it. wait polls until the test is completed, failed or cancelled.

Code example
from facetlab import FacetLabClient

client = FacetLabClient(api_key="fl_...")   # create a key at https://qyzkdesign.com/dashboard/api-keys

spec = {
    "name": "Shoe cabinet page test",
    "market": "tiktok_us",                    # <platform>_<us|uk|jp> (uk = Europe, jp = Asia). Platforms: tiktok, amazon, temu, shein,
                                              # walmart, shopee, etsy, own_site, other (other needs platform_label)
    "product": {"name": "White 3-Tier Foldable Shoe Cabinet",
                "use": "Entryway shoe storage",
                "dimensions": "17.3 x 13.8 x 20.87 in"},
    "pricing": {"current_price": 37.69, "shipping": "Free shipping shown"},
    "scenario": {"shopper_intent": "browsing"},
    "question": {"primary": "Would you buy this shoe cabinet at the shown price?"},
    "arms": [{"id": "A", "label": "Original page"},      # A is the control
             {"id": "B", "label": "Adjusted layout"}],
    "persona_count": 25,
    "sessions_per_arm": 5,
}

estimate = client.product_tests.estimate(spec)   # creates nothing
print(estimate["ready"], estimate["credits"], estimate["data_gaps"])

test = client.product_tests.create(spec, images={"A": "a.png", "B": "b.png"})   # uploads and starts
done = client.product_tests.wait(test["id"])

if done["status"] == "completed":
    results = done["results"]
    for arm_id, arm in results["arms"].items():
        print(arm_id, arm["buy_rate"]["value"], arm["buy_rate"]["ci95"])
    for c in results["comparisons"]:
        print(c["arm"], "vs A:", c["difference"], c["stability"])
    print(done["report_urls"]["en"])   # signed HTML report, valid for 1 hour
else:
    print(done["status"], done["error_message"])

Set scenario.shopper_intent to "browsing" unless your traffic already intends to buy. The API default, "in_market", assumes every shopper already wants this kind of product, so buy rates run high and differences between variants can disappear.

By default every variant shares one set of product facts and only the screenshot differs. Shoppers judge price, shipping and features from each screenshot. pricing.current_price is still required and goes into the report; proposed_price, key_features and shopper_problem are informational and not shown to shoppers. To compare different products, not just page designs (such as a 2-tier and a 3-tier shoe rack), give each variant its own facts with arms[].product and arms[].pricing, such as name, size, material and price, so each variant's AI shoppers see the right facts.

AI simulation for pre-testing, not a sales forecast.

client.product_tests methods

Table
MethodWhat it does
estimate(spec)Readiness, data gaps, eligible personas, credits and ETA. Creates nothing.
create(spec, images, idempotency_key=None)Creates the test, uploads one image per variant and starts it. Pass idempotency_key to retry safely; the SDK makes one if you do not.
wait(test_id, poll_interval=20, timeout=1800)Polls until the test is finished: every 20 s, for up to 30 minutes by default.
get(test_id, include_personas=False)One test. include_personas=True returns every persona, not only the representative ones.
list(partner_product_id=None, limit=20, cursor=None)Your tests, newest first, with cursor paging. Filter by partner_product_id.
clone(test_id, overrides, images=None, idempotency_key=None)Re-test with changes. Variants without a new image reuse the parent test's image.
cancel(test_id)Cancels a test that has not finished.
markets_audience(market)Audience filter options for a market, with persona counts.

UI A/B tests, balance and the Assistant

Check your balance

client.account() (REST: GET /api/v1/account) returns your free tests left, your prepaid balance in US dollars, your rates per persona per variant, the rate of your next test and your largest test (max_personas). run_experiment and product_tests.create check it before uploading and raise InsufficientFundsError when the test cannot be paid; the server checks the exact cost again when the test starts.

Code example
acct = client.account()
print(acct["free_tests"])       # {"used": 1, "limit": 2, "remaining": 1} (None on a plan)
print(acct["balance"])          # 25.0 (US dollars)
print(acct["next_test_rate"])   # 0.8 (US dollars per persona per variant, without a plan)
print(acct["max_personas"])     # 100 (largest test: 500 on Base, 2,000 on Pro)

Run a UI A/B test

Two screenshots of the same page, control and treatment. run_experiment checks your balance, uploads both screenshots, starts the test and waits for the result. Both screenshots together must stay under about 3 MB.

Code example
result = client.run_experiment(
    control_image="control.png",
    treatment_image="treatment.png",
    locale="usa",                     # "usa", "europe" or "asia"
    persona_count=25,                 # up to 100 without a plan, 500 on Base, 2,000 on Pro; billed as persona_count x 2
    context="Sign-up page: bigger free-trial banner",
    positive_decision="Start the free trial",
    negative_decision="Leave the page",
)
print(result.winner, result.lift, result.confidence)

Use the Assistant

Describe the test in plain language. The Assistant asks for anything missing and drafts the plan; reply.draft() tells you which images to upload. Nothing runs until you call start, which is paid like any test. When the Assistant asks which kind of test you mean, answer with send(conv, "", workflow="product_test") or "ui_ab_test".

Code example
conv = client.agent.start_conversation()
reply = client.agent.send(conv, "Compare my original shoe cabinet page with a "
                                "benefit-led version on TikTok Shop US, 25 personas, $37.69.")
print(reply.text)

draft = reply.draft()            # None until the Assistant has what it needs: reply with send()
if draft:
    client.agent.upload(conv, draft, {"A": "original.png", "B": "benefit.png"})
    client.agent.start(draft)    # paid like any test
    print(client.product_tests.wait(draft.draft_id)["status"])

REST endpoints for UI A/B tests, the balance and the Assistant

Table
MethodWhat it does
GET /api/v1/accountFree tests left, balance and the next test's rate.
POST /api/sdk/experiments/createCreates and starts a UI A/B test from two base64 screenshots (control_image, treatment_image, locale, persona_count, context).
GET /api/sdk/experiments/{id}Status, and the results once completed.
POST /api/sdk/experiments/{id}/startStarts a UI A/B draft the Assistant prepared, after its screenshots are uploaded.
POST /api/agent/conversationsStarts a conversation with the Assistant; returns {"id"}.
POST /api/agent/conversations/{id}/messagesSends {"text"} (optionally "workflow"). The reply streams as server-sent events: text, card (plans, upload requests, results) and a final done.
POST /api/agent/conversations/{id}/uploadsUpload URLs for a draft: {"draft_id", "workflow", "content_types"}. PUT each image to its URL with that Content-Type.

Product Tests API v1

The full reference for the REST API that the SDK wraps. Call it directly from any language with an API key.

A Product Test compares 2-6 versions ("arms") of a product page, listing image or creative on a given market. Virtual consumers (personas) from that market's audience pool each run several simulated shopping sessions per arm and decide whether to buy. You get buy rates, arm-vs-control comparisons, concerns and persona-level detail.

Base URL: https://qyzkdesign.com/api/v1/product-tests

This is an intent simulation, not a sales forecast. Results come from AI virtual consumers. Use them to form hypotheses and plan real validation. They do not predict real orders or sales. Every results object carries an is_simulation: true flag and a bilingual disclaimer; please keep it visible wherever you show results.

1. Authentication

Code example
Authorization: Bearer fl_...
  • User keys are created at /dashboard/api-keys. Requests act as that user and see only that user's tests.
  • Partner keys (issued by FacetLab to integration partners) act as the partner. Two optional headers scope requests:
    • X-Team-Id: when sent, create/list/get only see tests created with the same team id.
    • X-End-User-Id: records the partner's end user.
    • Both: 1-128 characters from A-Z a-z 0-9 _ . : @ -. A present but invalid header returns 400 invalid_team_id / 400 invalid_end_user_id. When absent, the partner-wide view applies.
  • Missing, malformed or revoked key: 401 unauthorized. A test that is not yours is indistinguishable from a missing one (404 not_found).

All bodies are JSON; errors use the shape in section 10.

2. Flow

  1. POST /estimate : check readiness, audience size, credits and quota. Free, no side effects.
  2. POST / with an Idempotency-Key : creates the test (awaiting_upload) and returns upload_urls.
  3. PUT each arm's image to its upload_urls[arm].url with exactly the listed Content-Type.
  4. POST /{id}/start : reserves credits and queues the run.
  5. Poll GET /{id} until status is completed, failed or cancelled (typically 5-15 minutes; see eta_minutes). Every 15-30 s is plenty.
  6. Read results (and report_urls) from the completed test.
Code example
BASE=https://qyzkdesign.com/api/v1/product-tests
AUTH="Authorization: Bearer $FACETLAB_KEY"

curl -s -X POST $BASE -H "$AUTH" -H "Idempotency-Key: my-shop-2026-10-13-0001" \
     -H "Content-Type: application/json" -d @spec.json            # -> id, upload_urls
curl -s -X PUT "<upload_urls.A.url>" -H "Content-Type: image/png" --data-binary @a.png
curl -s -X PUT "<upload_urls.B.url>" -H "Content-Type: image/png" --data-binary @b.png
curl -s -X POST $BASE/pt_.../start -H "$AUTH"
curl -s $BASE/pt_... -H "$AUTH"

The Python SDK (facetlab >= 0.2.0, FacetLabClient(...).product_tests) wraps this whole flow, including upload validation, start and polling.

3. Request body (the test spec)

Canonical example (POST /estimate and POST / take the same body):

Code example
{
  "name": "TikTok US shoe cabinet - page layout",
  "market": "tiktok_us",
  "product": {
    "name": "White 3-Tier Foldable Shoe Cabinet",
    "url": "https://www.tiktok.com/view/product/1731093726010380869",
    "platform_product_id": "1731093726010380869",
    "variant": "White, 3 tiers",
    "use": "Enclosed shoe storage for entryways",
    "dimensions": "17.3 x 13.8 x 20.87 in (outer W x D x H)",
    "key_features": ["Foldable", "3 enclosed tiers"],
    "limitations": []
  },
  "pricing": {
    "current_price": 37.69,
    "proposed_price": null,
    "shipping": "Free shipping shown",
    "tax": "unknown",
    "delivery": "unknown"
  },
  "scenario": {
    "shopper_problem": "Shoes cluttering a small entryway",
    "entry_point": "feed_content",
    "usage_context": "Apartment entryway",
    "shopper_intent": "browsing"
  },
  "audience": {
    "description": "US adults who shop on TikTok Shop",
    "filters": {
      "gender": ["female"],
      "urbanicity": ["urban", "suburban"],
      "average_purchase_price": { "min": 10, "max": 60 }
    }
  },
  "question": {
    "primary": "Would you buy this shoe cabinet at the shown price?",
    "follow_ups": ["Did you notice whether shipping is free?"]
  },
  "arms": [
    { "id": "A", "label": "Original page", "change_summary": null, "content_type": "image/png" },
    { "id": "B", "label": "Adjusted layout", "change_summary": "Price area and spec grouping reorganized", "content_type": "image/png" }
  ],
  "persona_count": 25,
  "sessions_per_arm": 5,
  "external_ref": { "partner_product_id": "sku-1042", "opportunity_id": null }
}

What shoppers see. By default every arm shares one set of product facts and only the screenshot differs. Shoppers judge the price, shipping, name and features from what is visible in each arm's screenshot, plus the seller details variant, dimensions, inner_dimensions, material and limitations. Fields marked informational below are kept for the report but are not shown to shoppers. To compare different products rather than page designs (for example a 2-tier and a 3-tier shoe rack), give each arm its own facts with arms[].product and arms[].pricing; see "Comparing different products" below.

Unknown top-level keys are ignored; unknown keys inside audience.filters are rejected (the error suggests the closest field name).

Table
FieldRules
namerequired, 1-200 chars
marketrequired, see section 4
currencyoptional; if given must equal the market's currency (currency_mismatch). Derived from the market otherwise.
material_languageoptional, up to 20 chars; defaults to the market's locale (en-US, en-GB, ja-JP)
product.namerequired, up to 300 chars
product.* (optional text, up to 300; url 500)url, platform_product_id, asin, variant, use, material, dimensions, inner_dimensions
product.key_features, product.limitationsup to 10 strings each, up to 200 chars each. key_features is informational (shoppers read features from the screenshot); limitations is shown to shoppers.
pricing.current_pricepositive number in the market currency. Required to start (blocking gap). Used for the report; shoppers judge the price shown in each screenshot.
pricing.proposed_priceoptional positive number. Informational: not shown to shoppers.
pricing.shipping, tax, deliveryfree text, default "unknown"
scenario.entry_pointfeed_content, search, comparison, product_page (default). Informational: recorded for the report, does not yet change decisions (same for shopper_problem and usage_context)
scenario.shopper_intentbrowsing (recommended: the shopper lands on the page without a plan to buy) or in_market (API default: every persona is assumed to already want this kind of product, so buy rates run high and variant differences can disappear; use only for purchase-intent traffic)
scenario.shopper_problem, usage_contextoptional text, informational. At least one of product.use / scenario.shopper_problem is required (blocking gap otherwise).
audience.descriptionoptional, up to 500 chars (informational)
audience.filterssee section 5
question.primaryrequired, up to 300 chars; follow_ups: up to 3
arms2-6 entries, ids exactly A, B, C... in order. A is the control; every other arm is compared against A. Each: label (1-120), change_summary (optional, up to 300), content_type (image/png default, image/jpeg, image/webp).
arms[].productoptional per-arm product facts, any of name, variant, use, material, dimensions, inner_dimensions (text, up to 300 chars) and key_features, limitations (1-10 strings, up to 200 chars each). Other keys are rejected (invalid_spec).
arms[].pricingoptional per-arm pricing, any of current_price (positive number), shipping and delivery (text, up to 200 chars). Other keys (proposed_price, tax) are rejected.
persona_countinteger, at least 10, default 25; at most the owner's plan size (100 without a plan, 500 on Base, 2,000 on Pro; partner keys by the tier on the key), else 403 tier_limit
sessions_per_arminteger 3-10, default 5
external_refpartner_product_id and opportunity_id (up to 128 chars). partner_product_id is returned as partner_product_id and can filter the list.

Missing optional facts such as dimensions, material, inner dimensions, shipping or delivery produce non-blocking (limiting) data_gaps; results are then reported with narrower conclusions.

Comparing different products

Each arm can describe its own product, so a test can compare different products, not just page designs. Each arm's AI shoppers see that arm's facts.

  • Merge, field by field. An arm's facts are the shared product and pricing with that arm's product / pricing applied per field. A provided value wins; an omitted, null or blank one falls back to the shared value. Lists (key_features, limitations) replace the shared list when provided; they are not appended.
  • Send only what differs. Omit any field you don't want to override. Don't send placeholders such as "unknown": a provided value is used as is. Keys outside the lists above are rejected.
  • The control. The shared product and pricing are the control's facts. Arm A may carry overrides too, but keeping A's facts at the top level is clearest.
  • Different products. An arm is a different product when any of its merged product values or its pricing.current_price differs from arm A's. If any arm is, scope_warnings adds different_products: "Variants are different products; differences reflect the product, its price and its page together." Read those comparisons as product + price + page together, not as a page-design effect.
  • Readiness per arm. Data gaps are computed on each arm's merged facts. A gap every arm has keeps its plain field (product.dimensions). A gap only some arms have is reported once per affected arm as arms.<ID>.<field> (for example arms.B.product.material), its message prefixed with the arm id and label ("B · 2-tier bamboo rack: Material unknown: ..."). Severity is unchanged, so an arm whose merged facts have no current_price is a blocking gap.
  • Unchanged. Credits, quota, statistics (every arm is still compared against A), audience and market are the same as for a page-design test. Without arms[].product / arms[].pricing, a test behaves exactly as before.

Example: a 3-tier plastic rack (the control, shared facts) against a 2-tier bamboo rack.

Code example
{
  "name": "Shoe rack: 3-tier plastic vs 2-tier bamboo",
  "market": "tiktok_us",
  "product": {
    "name": "3-Tier Plastic Shoe Rack",
    "variant": "Black, 3 tiers",
    "use": "Entryway shoe storage",
    "material": "Plastic",
    "dimensions": "20.9 in tall"
  },
  "pricing": { "current_price": 37.69, "shipping": "Free shipping shown" },
  "scenario": { "shopper_intent": "browsing" },
  "question": { "primary": "Would you buy this shoe rack at the shown price?" },
  "arms": [
    { "id": "A", "label": "3-tier plastic rack" },
    { "id": "B", "label": "2-tier bamboo rack",
      "product": { "name": "2-Tier Bamboo Shoe Rack", "variant": "Natural, 2 tiers",
                   "material": "Bamboo", "dimensions": "14 in tall" },
      "pricing": { "current_price": 29.99 } }
  ]
}

Arm B's shoppers see the bamboo rack's name, variant, material, height and $29.99, and inherit use and shipping from the shared facts. POST /estimate returns the different_products scope warning, and results.test.arms[] echoes each arm's product / pricing overrides.

4. Markets

Table
PlatformMarketsAudience pool
TikTok Shoptiktok_us (US), tiktok_uk (UK), tiktok_jp (Asia)new, non-Prime shoppers
Amazonamazon_us (US), amazon_uk (UK), amazon_jp (Asia)new Prime + veteran Prime shoppers

Currencies: US USD, UK GBP, Asia JPY. Any other value returns 422 market_not_supported (details list the supported codes).

5. Audience filters

audience.filters narrows the market's pool. Fields combine with AND. Empty lists, null bounds and empty ranges are ignored.

  • Categorical (a non-empty list of allowed values; any listed value matches): age, gender, income, education, industry, home_ownership, pet_ownership, parental_status, relationship_status, urbanicity, cohort.
  • Numeric ranges ({"min": n, "max": n}, inclusive, either bound optional, min <= max; personas lacking the field never match): income_min, average_purchase_price, median_purchase_price, max_purchase_price, average_monthly_spending, avg_purchases_per_month, total_purchases. Money fields are in the market currency.

The valid categorical values and numeric distributions are discoverable through GET /audience. If fewer eligible personas than persona_count remain, creation fails with 422 audience_too_small.

6. Endpoints

GET /audience?market=tiktok_us

Filter menu for a market (de-duplicated pool).

Code example
{
  "market": "tiktok_us", "currency": "USD",
  "fields": { "age": [["0-10", "10-20"], ["20-30"], ["30-40"]], "urbanicity": [["Suburban"], ["Urban"], ["Rural"]] },
  "numeric": { "average_purchase_price": { "count": 3000, "min": 3.2, "p10": 9.5, "p50": 24, "p90": 61, "max": 410 } }
}

fields maps each offered categorical field to its options; each option is a list of raw values to send together in audience.filters (e.g. "age": ["0-10", "10-20"]). Values are grouped so every option covers at least 50 personas (adjacent ranges are merged, small categories combined); fields with a single option are omitted. industry and cohort are not offered. numeric gives count/min/p10/p50/p90/max per numeric field (nulls when empty).

POST /estimate

Body: the spec. Never creates anything and needs no Idempotency-Key.

Code example
{
  "ready": true,
  "data_gaps": [
    { "field": "product.inner_dimensions", "severity": "limiting",
      "message_en": "Inner dimensions unknown: we can see whether shoppers ask, but cannot conclude what fits inside.",
      "message_zh": "..." }
  ],
  "scope_warnings": [{ "code": "overall_variant", "message_en": "Differences reflect each page variant as a whole, not any single element.", "message_zh": "..." }],
  "audience": { "pool_size": 3120, "eligible": 812, "enough": true },
  "credits": 50,
  "eta_minutes": { "typical": 6, "max": 15 },
  "quota": { "used": 0, "limit": 150, "remaining": 150 }
}

ready is true only when there is no blocking gap (including free-tier limit gaps) and audience.enough. It does not check the quota; compare credits with quota.remaining.

POST /

Headers: Idempotency-Key (required, 8-128 chars of A-Za-z0-9_.:-). Body: the spec. Does not charge credits. 201:

Code example
{
  "id": "pt_0b8f3f0e-5f0a-4a8c-9a55-3f2f6f1c2b11",
  "status": "awaiting_upload",
  "credits": 50,
  "eta_minutes": { "typical": 6, "max": 15 },
  "data_gaps": [],
  "scope_warnings": [{ "code": "overall_variant", "message_en": "...", "message_zh": "..." }],
  "upload_urls": {
    "A": { "url": "https://...presigned...", "content_type": "image/png" },
    "B": { "url": "https://...presigned...", "content_type": "image/png" }
  }
}

Failure modes: 403 tier_limit, 422 needs_info (blocking gaps in details.data_gaps), 422 audience_too_small, 422 invalid_spec / invalid_arms / market_not_supported / currency_mismatch, 400 idempotency_key_required. Rejected requests (4xx) do not store the key.

Upload images

PUT the file bytes to upload_urls[arm].url. URLs are valid for 1 hour and the Content-Type header must exactly equal the content_type returned for that arm (the signature binds it; a mismatch is rejected by storage). To get fresh URLs for a test still in awaiting_upload, repeat the create call with the same Idempotency-Key and body (see section 8).

Limits per image:

  • Formats: PNG, JPEG, WebP. At most 5 MB.
  • Pixel caps: JPEG 80 MP, opaque PNG 45 MP, PNG with transparency 25 MP, WebP 12 MP (any WebP).
  • The file's real format should match the declared content_type.

POST /{id}/start

No body. Requires every arm image to be uploaded and valid; for a free-plan user's key, also requires a free test left (403 free_tier_limit, nothing reserved). Then it reserves credits against the monthly quota and queues the run (and counts one free test for a free-plan user): { "id": "pt_...", "status": "queued" }. Calling it again on a test that has already started returns its current status (safe to retry).

Errors: 409 images_missing (details.missing lists arm ids), 409 images_invalid (details.invalid: over 5 MB or wrong content type), 402 quota_exceeded, 404 not_found. Pixel-cap violations are detected by the pipeline and surface as a failed test with error_message, so validate dimensions before uploading.

GET /{id}

Returns the summary below plus spec, arm_images (signed image URLs, valid 1 hour) and, once completed, results and report_urls (en, zh HTML reports, signed, valid 1 hour). Add ?include=personas to get all personas in results.personas; by default only the up-to-6 representative ones are included.

Code example
{
  "id": "pt_0b8f...", "name": "TikTok US shoe cabinet - page layout", "status": "completed",
  "market": "tiktok_us", "platform_name": "TikTok Shop", "country_name": "United States",
  "arm_count": 2, "progress": { "finished": 25, "total": 25 },
  "credits": 50, "billable": true,
  "parent_test_id": null, "partner_product_id": "sku-1042",
  "buy_rate_a": 0.42, "best_arm": "B",
  "error_message": null, "warning_message": null,
  "created_at": "2026-10-13T08:00:00.000Z", "completed_at": "2026-10-13T08:06:10.000Z",
  "spec": { "...": "stored spec incl. data_gaps, scope_warnings, parent_test_id" },
  "arm_images": { "A": "https://...", "B": "https://..." },
  "results": { "...": "see section 7" },
  "report_urls": { "en": "https://...", "zh": "https://..." }
}

progress is null until the run has a shard count; total is the number of personas. billable says whether credits stay spent (see section 9). Error text is scrubbed of internal storage paths.

GET /

Lists your tests, newest first. Query: partner_product_id, limit (1-100, default 20), cursor. Returns { "data": [ <summary>, ... ], "next_cursor": "..." | null } (no spec or results). A bad cursor returns 400 invalid_cursor.

POST /{id}/clone

Creates a follow-up round from an existing test (re-test). Headers: Idempotency-Key (required). Body: optional partial spec. Objects product, pricing, scenario, audience, question and external_ref are merged key-by-key over the parent's spec; other fields (and arms, if given) replace it. If arms is omitted, all parent arms are reused with reuse_parent_image: true (including any arms[].product / arms[].pricing), so you do not upload those images again. For a new arm image set reuse_parent_image: false (and upload it); reuse_parent_image: true is only valid for arm ids that exist in the parent. Response is the same as create (upload_urls only lists arms that need an upload; if none does, call start directly). The new test records parent_test_id and may add scope warnings (market_changed, price_changed, variant_changed). Errors add 409 parent_images_missing when the parent's image is no longer available. If you change market, currency and material language are re-derived.

POST /{id}/cancel

Allowed in awaiting_upload, queued or processing. Returns { "id": "pt_...", "status": "cancelled", "billable": false }. Finished tests return 409 not_cancellable. Refund rules in section 9.

7. Status values

Table
statusMeaning
awaiting_uploadCreated; waiting for images and start. Nothing is charged.
queuedStarted; credits reserved.
processingPersonas are being simulated (progress advances).
completedresults and report_urls available.
failedThe run failed; see error_message.
cancelledCancelled by you.

completed, failed and cancelled are terminal. Personas that fail individually are counted in results.sample.personas_failed; warning_message may carry a notice.

8. Idempotency

  • Required on POST / and POST /{id}/clone; 8-128 chars from A-Za-z0-9_.:-. Use a fresh unique key per logical test.
  • Scope: your owner identity (and X-Team-Id for partners) plus the key. Keys expire after 7 days.
  • Same key + same body: no new test; the original is returned with "idempotent_replay": true (summary shape; plus fresh upload_urls while it is still awaiting_upload). Safe to retry after timeouts or to refresh expired upload URLs. For clone the "body" is the parent id plus overrides.
  • Same key + different body: 409 idempotency_conflict.
  • Same key while the first request is still being processed: 409 idempotency_in_progress; retry shortly.
  • If creation itself fails after the key was claimed, the key is released so you can retry.

9. Pricing, quota and refunds

  • 1 credit = 5 sessions x 1 persona x 1 arm. credits = persona_count x number_of_arms x ceil(sessions_per_arm / 5). Example: 25 personas, 2 arms, 5 sessions = 50 credits; with 10 sessions = 100.
  • Free tests: 2 free tests in total, shared by the web app, the API and the Assistant. A key created in the dashboard acts as its user, so each successful start counts one free test like a start in the app (a retried or concurrent start of the same test is not counted again). A free test covers up to 100 personas, 2 arms and 5 sessions per arm; a larger test, and every test after the free ones, is paid from the prepaid balance (402 insufficient_funds with the cost in details.required), or 403 free_tier_limit while billing is off. Partner keys are not counted.
  • Prepaid price: billed per persona per arm (5 sessions): units = persona_count x number_of_arms x sessions_per_arm / 5, rounded up, times the rate on the pricing page ($0.80 without a plan; lower on Base and Pro).
  • Sizes: at most 100 personas per test without a plan, 500 on Base and 2,000 on Pro (403 tier_limit on create, a blocking data_gaps entry on estimate); 3-10 sessions per arm and 2-6 arms on every plan. Credits remain a monthly guard (400 for free-tier users by default) for tests not paid from the balance; partner keys use the tier on the key.
  • The monthly quota is per owner and per UTC calendar month. Credits are reserved on start, not on create. A single test larger than the monthly limit can never start.
  • Cancel: cancelling in awaiting_upload costs nothing. Cancelling a started test before any persona has finished refunds the credits (billable: false). If at least one persona had finished, credits are kept (billable: true).
  • Failure: a test that fails after starting with no completed personas is refunded automatically, exactly once (billable: false on the next read). A failed test where some personas completed remains billable.
  • GET fields credits and billable always show the current position.

10. Errors

Code example
{ "error": { "code": "audience_too_small", "message": "Only 7 personas match the audience filters",
             "message_zh": "...", "details": { "pool_size": 3120, "eligible": 7, "enough": false } } }
Table
HTTPcodeMeaning
400invalid_jsonBody is empty, malformed or not a JSON object
400idempotency_key_requiredMissing or malformed Idempotency-Key
400invalid_cursorBad list cursor
400invalid_team_id, invalid_end_user_idMalformed partner header
401unauthorizedMissing, invalid or revoked key
402quota_exceededMonthly credits would be exceeded on start
403tier_limitMore personas than the plan allows (details.data_gaps)
403free_tier_limitAll 2 free tests are used (details.limit), on start
404not_foundTest does not exist or is not yours
409idempotency_conflictKey reused with a different body
409idempotency_in_progressFirst request with this key still running
409images_missing / images_invalidArm images not uploaded, over 5 MB, or wrong type
409parent_images_missingRe-test cannot reuse the parent's image
409not_cancellableTest already finished
422invalid_specSchema violation; details.fieldErrors / formErrors list them
422invalid_armsArm ids not A,B,... in order; reuse_parent_image misuse
422market_not_supported, currency_mismatchBad market / currency
422needs_infoBlocking data gaps (details.data_gaps)
422audience_too_smallFewer eligible personas than persona_count
500internal_errorUnexpected; retry later
503feature_disabledProduct Tests are not enabled for this deployment; every endpoint returns this until they are

11. results.json reference

Returned as results in GET /{id} when completed. All rates are 0-1.

Table
FieldDescription
schema_version"1"
test_idTest id
is_simulationAlways true
disclaimer{en, zh} simulation notice (not a sales forecast)
testEcho of the spec: name, market, platform_name, country_name, currency, product, pricing, question, audience, arms[] (spec arm, including any product / pricing overrides, plus is_control), parent_test_id
sample.personas_planned / personas_completed / personas_failedPersona counts
sample.sessions_per_armSessions per persona per arm
sample.sessions_unparsedSessions whose answer could not be read; excluded from all rates
sample.models_usedModel ids that produced valid sessions
arms.<id>.buy_rate{value, ci95:[lo,hi]}: mean over personas of each persona's buy share; 95% persona-level bootstrap interval
arms.<id>.buy_sessions / valid_sessionsCounts of buy decisions / parsed sessions
arms.<id>.personas_majority_buyPersonas who bought in more than half of their sessions
arms.<id>.top_concerns[]Up to 5 {category, sessions, share_of_non_buy} from non-buy sessions
arms.<id>.top_buy_reasons[]Up to 3 {category, sessions, share_of_buy}
arms.<id>.common_questions[]Up to 5 questions shoppers asked most
comparisons[]One per non-control arm: arm, vs: "A", difference (arm minus A, mean of per-persona differences), ci ([lo,hi]), ci_level (95%, Bonferroni-adjusted when there are several treatments), stability, scope: "overall_variant"
comparisons[].stabilityclear (CI excludes 0), directional (CI includes 0 but difference >= 0.05), no_difference, insufficient (fewer than 10 personas)
segments[]Buy rate per demographic group with at least 3 personas: {dimension, value, personas, buy_rate:{<arm>: rate or null}}. Dimensions: cohort, age, gender, income, home_ownership, pet_ownership, parental_status, relationship_status, urbanicity
personas[]{persona_id, profile, representative, arms:{<id>:{buy_rate, decisions[], primary_reason, primary_concern, questions[]}}}. Without ?include=personas, only entries with representative: true (up to 6, mixing control buyers and non-buyers)
data_gaps, scope_warningsFrom the spec: read conclusions within them
definitions{en, zh} text for buy_rate, ci, stability, sessions_unparsed
narrative{en, zh} reserved; currently null

GET /{id} also returns buy_rate_a (control buy rate) and best_arm at top level for convenience.

Interpretation notes: differences describe each page variant as a whole, not a single element; a directional result is a lean, not a finding; always carry the disclaimer and data_gaps along.

Limits and errors

  • Product page tests: 2–6 variants (A is the control), 10 or more personas (up to your plan’s maximum) and 3–10 sessions per variant.
  • Free tests: 2 in total, shared by the app, the API and the Assistant (a start over the API counts like one in the app). A free test covers a UI A/B test or a product page test with up to 100 personas, 2 variants and 5 sessions per variant. Larger tests (more personas, variants or sessions), and every test after the free ones, are paid from your prepaid balance, even while you have free tests left; with too little balance a start returns insufficient_funds (402). Base and Pro subscribers don’t use free tests.
  • Prepaid balance: API keys act as your account, so tests started with client.run_experiment or client.product_tests are paid from your balance when they start, per persona per variant: units = persona_count × variants × sessions_per_arm ÷ 5, rounded up to a whole number; a UI A/B test has 2 variants, so units = persona_count × 2. Rates per unit: $0.80 without a plan, up to 50 tests a month; Base $0.50 for the first 10 tests a month then $0.55, up to 50; Pro $0.35 for the first 50 then $0.40, up to 1,000 (plan_limit (403) after that). Example: a 100-persona UI A/B test counts 200 persona-variants. Too little balance returns insufficient_funds (402) with the cost (required) and your balance; top up on the Billing page. Largest test: 100 personas without a plan, 500 on Base and 2,000 on Pro, the same in the app, the API, the SDK and the Assistant. Over the API, a larger UI A/B persona_count is lowered to the limit; a larger product page test returns tier_limit (403).
  • Credits: persona_count × variants × ceil(sessions_per_arm ÷ 5). 25 personas, 2 variants and 5 sessions use 50 credits. Credits are reserved when the test starts; tests paid from your balance are limited by the balance and your plan’s tests, not by credits.
  • A test that fails or is cancelled before any persona finishes is refunded: its credits, and its charge if it was paid from your balance. Once a persona has finished, the test stays charged.
  • Images: PNG, JPEG or WebP, up to 5 MB each, and at most 80 megapixels for JPEG, 45 for PNG, 25 for transparent PNG and 12 for WebP. The SDK checks these before uploading.
  • A product page test usually takes 5–15 minutes (see eta_minutes). Polling every 15–30 s is plenty.

Errors

The API returns errors as {"error": {"code", "message", "message_zh", "details"}}. The SDK raises FacetLabError (or a subclass: InsufficientFundsError, LimitError, AuthenticationError) with .code, .message and .details.

Code example
from facetlab import FacetLabError, InsufficientFundsError

try:
    test = client.product_tests.create(spec, images={"A": "a.png", "B": "b.png"})
except InsufficientFundsError as e:
    print(f"Top up first: needs ${e.required}, balance ${e.balance}")
except FacetLabError as e:
    print(e.code, e.message)   # e.g. "audience_too_small"
    print(e.details)           # e.g. {"pool_size": 19195, "eligible": 7, "enough": False}

Common codes: unauthorized (401), insufficient_funds and quota_exceeded (402), tier_limit, free_tier_limit and plan_limit (403), needs_info and audience_too_small (422), and invalid_image from the SDK's local checks.

All error codes

Questions about the API or the SDK? Email qyzkai@gmail.com.