# Voice Profile API: build and read a measured writing voice · ScriptGrain > Create a voice profile from writing samples and read back 45 measured attributes by REST or MCP: list_profiles, create_profile and get_profile. One extraction slot per profile, reads free. Canonical: https://scriptgrain.com/api/voice-profile # Voice Profile API: measure a writer's voice from their own samples *By Jack Stovell [X](https://x.com/StovBuilds) · [Instagram](https://www.instagram.com/stovbuilds) · [LinkedIn](https://www.linkedin.com/in/jackstovell/) · published 2026-10-29* The Voice Profile API turns a writer's own samples into a measured voice profile: 45 attributes across eight layers. Developers call it over REST, and assistants call it through the MCP server. Everything else in the API, from matching to generation, reads the profile it produces. So it comes first. ## At a glance **What it does:** Turns a writer's own samples into a profile of 45 measured attributes that every other call reads. · Endpoints · `GET /v1/profiles`, `POST /v1/profiles`, `GET /v1/profiles/{id}` MCP tools · `list_profiles`, `create_profile`, `get_profile` Cost · Creating a profile uses one extraction slot; listing and reading are free Plans · Every plan. Free: 1 profile and 1 extraction. Writer: 2 extractions a month. Operator: 5. Studio: 20. Agency: unlimited profiles ## What a voice profile holds A profile is 45 measured attributes across eight layers, built by a two-pass stylometric extraction. ScriptGrain measures writing. It is never trained on it. A complete profile hands back three things: 1. A confidence_score between 0 and 1. 2. A written narrative, a plain description of how the writer sounds. 3. The attributes object, split into eight groups: sentence structure, vocabulary, punctuation, tone and register, rhetoric, perspective and pronouns, structure and formatting, and signature phrases and banned terms. The full shape is in the [voice profile JSON schema](https://scriptgrain.com/reference/voice-profile-json-schema), and each measured trait is explained in [writing voice attributes](https://scriptgrain.com/reference/writing-voice-attributes). Only complete profiles can be used for generation. That matters, because extraction takes a little while. You create a profile with POST /v1/profiles. It answers at once with status processing, and you poll GET /v1/profiles/{id} until status is complete. Progress runs from 10 to 80 across the per-sample first pass, sits at 85 in the second pass, then 95 while finalising. Usually that's under a minute. The longest runs take about two. ## What makes a good sample set Own human prose. That's the rule, and everything else follows from it. Emails, posts and articles all work. Three or more pieces, about 3,000 words in total, is the recommendation. One sample can start a profile, but a thin set gives a thin reading, and the confidence score will tell you so. The API accepts 1 to 20 samples per request. Each can run to 5,000 words, with 50,000 in total, and at least one sample must be 50+ words. Set english_variant to uk or us so the spelling is read correctly. Then there's AI text. Don't send it as a sample, and the reason is simple. A profile built from machine prose measures the machine's voice, not the writer's. You'd get a precise, confident description of the wrong person. So feed it the messy, real stuff: the email written in a hurry, the post that took three goes. One extraction slot is charged per accepted run. Plan limits are below, so check your tier before you batch up a client list. ## When to use it Three situations come up again and again. **Onboarding a client voice from a script.** You have a folder of a client's published writing. Loop over it, post the samples, poll until complete, store the profile id. Every later piece of work for that client starts from a measured baseline instead of a vague brief. For a quick check on what a sample set produces, try the voice preview. **Letting Claude build your profile in conversation.** The MCP server at https://mcp.scriptgrain.com/mcp is on every plan, Free included. Paste your own writing into the chat, and the assistant calls the API for you. **A guest profile before signing up.** https://mcp.scriptgrain.com/try lets an assistant build one guest profile, at most 25,000 words, with no key. The person keeps it in a free account or deletes it at the claim link. To see how a finished profile gets used, look at voice match. Auth is an sg_live_ key minted at Settings, then API, sent as Authorization: Bearer. The limit is 60 requests a minute per key. Calls draw on the same credits as the app, and payments never happen through the API. Plan limits for profiles and extractions: Free gets 1 profile and 1 extraction. Writer is £12 a month for 1 profile and 2 extractions a month. Operator is £29 for 3 profiles and 5 extractions. Studio is £99 for 10 profiles and 20 extractions. Agency is £299 with unlimited profiles. ## Request and response Create a profile from your own writing. The call answers at once with `processing`; poll the profile until `status` is `complete`. Reading a finished profile (`GET /v1/profiles/{id}`), here ScriptGrain's own brand voice, called live on 29 October 2026 (narrative cut short, attributes omitted): ## In Claude, ChatGPT or Cursor Over MCP this is the tools `create_profile`, `get_profile` and `list_profiles`. Connect `https://mcp.scriptgrain.com/mcp` once (a custom connector in claude.ai, developer mode in ChatGPT on the web, the MCP settings in Cursor, or `claude mcp add` in Claude Code), then ask in plain words: > Build my ScriptGrain voice profile from these three posts I wrote, then tell me what it says about how I write. The server also ships a `build_my_voice_profile` prompt that walks an assistant through gathering samples, extracting and explaining the result. ## Get a key API and MCP access is on every plan, Free included. Create a free account (no card), then mint a key at Settings, then API: it starts `sg_live_`, is shown once, and goes in an `Authorization: Bearer` header. Every request, field and error code is in the [OpenAPI spec](https://scriptgrain.com/openapi.yaml). ## Questions ### Is the API on the Free plan? Yes. The REST API and the MCP server are on every plan, Free included. Free gives you 1 voice profile and 1 extraction, so you can test the whole flow end to end. There's no separate API quota either: calls draw on the same credits as the app, at 60 requests a minute per key. ### How do I know when a profile is ready to use? Poll GET /v1/profiles/{id} until status is complete. The first response says processing, and progress_percent runs from 10 to 95 as extraction works through. Most runs finish in under a minute, the longest in about two. Only complete profiles can be used for generation, so wait for that status. ### Can I build a profile from AI-written text? You shouldn't. The API measures whatever it is sent, so samples must be the writer's own human-written prose, such as emails, posts or articles. AI text would make the profile measure the wrong voice entirely. If someone's writing has been heavily machine-edited, find earlier pieces they wrote themselves and use those instead. ### Can an assistant build a profile without an account? Yes. https://mcp.scriptgrain.com/try lets an assistant build one guest profile of at most 25,000 words, with no key needed. The person then keeps it in a free account, or deletes it at the claim link. It's a low-pressure way to see a real profile before committing to anything. ## Related - [AI writing API and MCP server](https://scriptgrain.com/ai-writing-api-and-mcp-server) - [Works with Claude](https://scriptgrain.com/works-with/claude) - [Works with ChatGPT](https://scriptgrain.com/works-with/chatgpt) - [Works with Cursor and MCP clients](https://scriptgrain.com/works-with/cursor) - [MCP tool reference](https://scriptgrain.com/reference/mcp-tool-reference) - [Pricing](https://scriptgrain.com/pricing)