MCP documentation

whoamiread-only

Return the mimi account the API key belongs to, its credit balance (100 credits = 1 USD) and its limits: what is left of each budget (requests a minute, follow-ups and chat questions an hour, files read by the vision step an hour) and when each resets, plus the key's own limits: its scopes (read, run, share), its spend cap in credits (null for none) and what it has spent and holds. Study runs, web research and website tests have no daily cap and no cap on how many run at once; credits and the key's spend cap are their only limits. Call it first to check a key works.

No parameters.

describe_audienceread-only

Find the real audience cohorts that fit a plain-language description of who should weigh in ("moms in the US into meal prep", "men 18-24 into sneakers"). Returns cohort keys ranked by fit, how mimi read the description (gender, ages, place, topics) and a one-line reason per match. Use the keys in create_study.

search_audiencesread-only

Search mimi's catalogue of real audience cohorts (people grouped by what they watch and comment on) by keyword, family (interest, creator, US panel), gender and age. Returns keys, labels, sizes and whether each cohort can be used in a new study. Prefer describe_audience for a natural-language brief.

get_audienceread-only

Read one audience cohort by key: its label, summary, size, what its members talk about and, where available, verbatim comments that show how they speak.

list_studiesread-only

List the account's studies, newest first, with each one's goal, status and one-line result when it has finished.

upload_mediamakes changes

Get a short-lived URL to upload one image, video, audio or PDF file (40 MB at most) that the audience should see with a creative. POST the file's bytes to uploadUrl with the file's Content-Type; it answers {"storageId": ...}. Then pass {storageId, filename, mimeType, sizeBytes} in create_study's media. Unused uploads are deleted after a day.

create_studymakes changes

Create a study and (by default) start its run: real audience cohorts react to a creative, compare 2-6 versions, or answer survey questions. Attach the creative's images, video, audio or PDFs with media (upload each file first with upload_media). Give the audience as cohort keys or as a plain description mimi matches for you. A run usually takes about a minute, several minutes with web research; follow it with get_study or get_results using waitSeconds. Costs credits (100 credits = 1 USD): the most it can cost is held when it starts and you pay only what it used. quote_study prices a draft before it runs. Send an idempotencyKey to retry safely: the same key and request return the first study (replayed: true), never start a second run and are not charged again, and the same key with a different request is refused with idempotency_mismatch. Needs a key with the run scope; a key with a spend cap starts no run that would take it past the cap.

get_studyread-only

Read a study: what it asks, which cohorts answer, and its run's status (draft, running, complete, failed), phase and progress. Pass waitSeconds (up to 55) to hold until the run finishes, then call get_results.

run_studymakes changes

Start a run for a draft study, or run a finished one again (for a fresh sample, a different depth, or with or without web research: pass depth or research as quote_study takes them). Refused while a run is in progress. Costs credits like create_study; refused with insufficient_credits when the balance cannot cover it, and with spend_cap_reached when it would take the key past its spend cap.

quote_studyread-only

Price a run of a study before starting it: its quoted price, which is the most it is charged and what is held when it starts (estimate and hold are the same number), in credits (100 credits = 1 USD), and the account's balance. Pass depth or research to price a different run than the study's own settings: extended adds one follow-up why per cohort after the run and max three per cohort plus a deeper analysis, so each depth up costs more. Create the study with run: false to price it before it runs, then start it with run_study.

archive_studymakes changes

Archive a study (archived: true) so it leaves the active list, or restore it (archived: false). Nothing is deleted: its runs, results and share link are kept, and list_studies with view "archived" lists it.

cancel_runmakes changes

Stop the study's run in progress (or the run named by runId). Its job on the simulation service is cancelled before its next paid call, the responses so far are discarded, and its credit hold is returned less what the answers already made used (nothing, if none came back). A run still going after three hours is cancelled and refunded in full on its own. A run that already finished is left as it is (stopped: false).

get_resultsread-only

Read a finished study's results: for every question the answer shares with their ranges, overall, per version and per cohort; averages for scores; orders for rankings; open answers with their themes; objections ranked by how upset each cohort is; representative quotes; and the written recommendation, findings, risks and next steps. Also the reads the report shows: the backlash level and peak upset, the virality level per version, how a comparison's versions stand against each other, a concept's funding forecast, and the run's cohorts, versions, settings, coverage, release, timing and cost. Lists are capped (50 objections, 24 quotes, 20 open answers per question); in a comparison the quotes are shared across its versions; `totals` says how many there were. Pass waitSeconds to wait for a running study. Reads the study's latest run unless you pass runId (as get_study or the app's ?run= link names it), so an earlier finished run stays readable while a re-run is going or after one failed. Answers `ready: false` with the run's progress while it is still going. `runMeta.creditChargedCents` is what the run was charged, its analysis extras included, and `runMeta.credits` gives the parts (run, extras, total, quote). `run.degraded` is true when fewer than half of the run's planned answers came back (it is charged only for the answers that came back; `run.coverage` is the share that did). The written parts (recommendation, themes, virality) land a minute or two after the run; `analysis` says which are ready, and a wait holds for them too.

ask_studymakes changes

Ask a question about a finished study's results and get a written answer, the same one the report's Chat panel gives. It answers only from what that run recorded: every cohort's answers, the shares, objections, quotes and the written analysis. It runs nothing new and asks the cohorts nothing; to put a new question to the cohorts themselves, use ask_followup. Asks about the latest finished run unless you pass runId. Waits for the whole answer (usually well under a minute) and returns it as markdown, with at most one chart left in it as a fenced ```chart block of JSON (bar, stacked, compare or heatmap; the shapes are in the API docs), plus sources (the question numbers, version keys and cohort count it drew on), up to three followups (next questions it left open) and action (one untested change it recommends, or null). Its numbers are model estimates read from the simulated run, not measurements. The question and answer also appear in the study's Chat in the app. Each answer costs credits (shown in the Chat panel), charged once it is written; a failed answer is free. 60 questions an hour per account, shared with the app's Chat; questions are 500 characters at most. Needs a key with the run scope, since it spends credits; each answer counts on the key's spend cap, and is refused with spend_cap_reached when the key has reached it.

ask_followupmakes changes

Ask a finished study's cohorts a follow-up question ("what would make this more believable?"). Each cohort answers in its own voice, grounded in what its real members say. Takes up to a minute. 40 follow-ups an hour per account. Each cohort's answer costs credits, charged once it is written. Needs a key with the run scope; the answers count on the key's spend cap, and are refused with spend_cap_reached when the key has reached it.

list_followupsread-only

List the follow-up questions asked of a study's latest run, with each cohort's answer.

share_studymakes changes

Turn on a read-only public link to the study's report and return it. Anyone with the link can read the report, so ask the person first and pass confirm: true; a call without it changes nothing and says how to confirm. Needs a key with the share scope. Use unshare_study to turn it off.

unshare_studyturns something off

Turn off a study's public link. The old link stops working at once.

report_ad_performancemakes changes

After you run the ads a study compared, send back how each one did, so Mimi's pick can be checked against what happened and Mimi improves as it sees more ads. Name each ad by the study's version key ("a", "b" and on, as get_study lists them; "a" for a single creative) and send its counts (impressions, clicks, installs), money (spend, revenue, currency) or rates (clickRate as clicks per impression, installRate as installs per click, from 0 to 1), engagementSeconds, and any other number by name in metrics. Send what you have: a report merges into the last one, so a number sent replaces the one stored and one left out is kept. Send cumulative totals, not the day's change. About the latest finished run unless you pass runId. Answers what get_ad_performance returns. Free; needs a key with the run scope.

get_ad_performanceread-only

Read the real numbers reported for a study's ads (report_ad_performance), one entry per version: the counts and money as sent, and clickRate (clicks per impression), installRate (installs per click), installsPerThousand (installs per 1,000 impressions) and roas (revenue over spend), each worked out from the counts when they were sent, else as reported. Beside them, the ad Mimi picked: only a version a validated side-by-side verdict named (versionPreference.state "validated_winner"). Otherwise mimiPick is a no-call (version null, basis "no_call") with its reason, for images and video, too-close and unvalidated runs alike. For each measure, which ad actually did best and whether it was Mimi's pick (null for a no-call, which is never scored). About the latest run with numbers reported unless you pass runId.

create_feed_testmakes changes

Start a Feed Emulator test: simulated people from one real audience cohort each scroll an Instagram-style feed (default) or an enabled X feed of 15 to 20 real recent posts picked for their interests, with your ad placed at a random slot from 4 to 7. Each person sees only what a scroller sees (a post's top until they stop; a video plays muted only while they keep watching) and decides on every post whether to scroll past, pause or stop, and whether to like, comment, share, save, open the profile or tap the button; afterwards they are asked what they remember. Upload the ad first with upload_media (a photo 1:1 or 4:5, or a video 9:16 or 4:5 up to 60 seconds; a video also needs its first frame uploaded as `cover`), then give the brand, caption, button and the audience (a cohort key, or `audience.describe`). An optional versionB from the same brand is compared with each person seeing one version. Returns the test's id; it runs for several minutes. Then call get_feed_test with waitSeconds until status is "finished" and get_feed_test_report for calibrated rates against the real posts around the ad. Costs credits (100 credits = 1 USD): the most it can cost is held when it starts, and it keeps only what its people used. Send an idempotencyKey to retry safely. X uses sampled public warehouse posts from scenario authors, not verified individual follow relationships; unavailable or insufficient warehouse evidence never triggers paid collection.

list_feed_testsread-only

List the account's Feed Emulator tests, newest first, with each one's audience, versions and status. view "archived" lists the archived ones instead.

get_feed_testread-only

Read a Feed Emulator test: its audience, its versions and where it stands (queued, collecting posts, scrolling, calibrating, finished, failed, cancelled) with how many people are done. Pass waitSeconds (up to 55) to hold until it finishes, then call get_feed_test_report.

get_feed_test_sessionsread-only

Read each simulated person's scroll: their version, where the ad sat, and for every post what they did (scrolled past, paused, stopped; how far into a video; liked, commented with what, shared to whom, saved, opened the profile, tapped) and why, then what they remembered. Other people's posts appear as numbered blanks (post-1, post-2): they were used inside the run only. Pass `person` for one person.

get_feed_test_reportread-only

Read a finished Feed Emulator test's report: how often people stopped for the ad, how far they watched it and how they engaged with it, each as a lift over the real posts in the same people's feeds (calibrated, never a raw simulated answer; an absolute rate only where the real posts' own counts anchor it), unaided and aided recall corrected for saying yes to anything, the themes of what people commented with their comments, and a check of how well the people tracked the real posts' real engagement. With a Version B it says which drew more engagement only once Feed Emulator has passed its check on real ad outcomes; until then it says there is no reliable winner call. Until the test finishes it answers ready: false; pass waitSeconds to wait.

cancel_feed_testturns something off

Stop a Feed Emulator test that is still in progress. What people had already done is kept and is charged for; a test that is already over is left as it is.

create_website_testmakes changes

Start a website test: simulated people drawn from one real audience cohort visit a public website in a browser, look around, and say what they think and what they would do. Give the site's address, the audience (a cohort key, or `audience.describe` to let mimi pick one), who they are to the site (`visitor`: customers by default, or investors, job candidates, partners, press, or your own description), an optional question or task, and how many people (10, 20, 50 or 100). Returns the test's id; it runs for a few minutes. Then call get_website_test with waitSeconds until status is "finished", get_website_test_results for what they did and why, and get_website_test_fixes for ready-made prompts to fix the site. Nobody signs in, fills in a form or buys anything; a site whose bot check keeps the browser out is reported as blocked, never worked around. Tests are limited by available credits and wait for browser capacity across the deployment; more than one test may be queued or running. Tests of pages behind a sign-in are started from the app, not here. Costs credits (100 credits = 1 USD): the most it can cost is held when it starts, and when it ends it keeps only what its people used (their steps and browser time); a test that fails gives the hold back. Refused with insufficient_credits when the balance cannot cover the hold, and with spend_cap_reached when it would take the key past its spend cap. Send an idempotencyKey to retry safely: the same key returns the first test, and the same key with a different request is refused with idempotency_mismatch.

list_website_testsread-only

List the account's website tests, newest first, with each one's site, audience, who visited, status and one-line result once it has finished. view "archived" lists the archived ones instead.

get_website_testread-only

Read a website test: the site, the audience, who the people are to it, the question, and where it stands (queued, capturing, visiting, writing, finished, failed, cancelled) with how many people are done. A failed test says why, including "blocked" when the site's bot check kept the browser out. Pass waitSeconds (up to 55) to hold until it finishes, then call get_website_test_results.

get_website_test_resultsread-only

Read a finished website test: how each visit ended (tapped a call to action, might come back, not for them, gave up) as counts, people kept out by a bot check, the score out of 100 and its parts, the headline, what put people off (themes with how many people, a fix and quotes), what works, what to fix first, what people picked on a task test, what the front page's first screen plainly shows, the pages and routes people took, and every person in brief. Pass `person` (a number from `everyone`) for that person's visit action by action: what they noticed, said and did. Until the test finishes it answers ready: false; pass waitSeconds to wait. Every count is computed from the stored visits. The people are simulated: present the result as a strong prior for what to fix and test, not as measured behaviour.

get_website_test_fixesread-only

Read a finished website test's fix plan: for each part of the score (weakest first) where it stands, the line to reach, what to change, people's own words, and a ready-made prompt that asks for the change; then one prompt for the whole site. Use this when the job is to go and improve the site: the prompts are written from the test's own counts and quotes and can be followed as they are. The targets are a line to reach, not a forecast; run the test again afterwards to see what moved.

cancel_website_testturns something off

Stop a website test that is still in progress and close its browsers. What people had already done is kept. A test that is already over is left as it is.

archive_website_testmakes changes

Archive a website test (archived: true) so it leaves the active list, or restore it (archived: false). Nothing is deleted: its result, its visits and its share link are kept, and list_website_tests with view "archived" lists it.

share_website_testmakes changes

Turn on a read-only public link to the website test and return it. Anyone with the link can read the result, replay every visit and read the insights, with no account; they cannot run or change anything. Ask the person first and pass confirm: true; a call without it changes nothing and says how to confirm. Needs a key with the share scope. A test can be shared while it is still running. Pass hideScore: true to keep the overall score and letter grade off the shared page (for sending a result to whoever made the site); calling again with hideScore changes the link already on, at the same address. Use unshare_website_test to turn it off.

unshare_website_testturns something off

Turn off a website test's public link. The old link stops working at once.