Generation Runs
Generating content from your own instructions, and following its progress.
List generation runs
Lists generation runs, newest first. Results are paged with cursor and limit: take meta.next_cursor from a response and pass it back as cursor for the next page. There is no total count.
A signed-in user sees only the runs they submitted. An access-token caller sees every run in the tenant, and can narrow to one user with created_by. Runs you cannot see are absent from the page rather than causing a 403.
query Parameters
created_byReturn only items created by this user. Naming a user whose items you cannot see gives an empty page.
A UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
cursorThe meta.next_cursor value from a previous response. Treat it as an opaque string: pass it back unchanged, and never build one yourself.
limitHow many items to return per page. Omit it for 20. A value above 100 is rejected with 422 rather than quietly reduced to it, so read the maximum from this parameter rather than probing for it.
Treat it as an upper bound, not a promise: a short page does not mean the listing has ended. Keep paging until meta.next_cursor is null.
List generation runs › Responses
The matching page of generation runs.
Pagination metadata. There is no total count and no page number — a listing is walked forwards with the cursor until next_cursor is null, and cannot be jumped into part-way.
Generate content from your own instructions
Generates content from your own instructions: either a fresh generation for a segment and use case, or a refinement of one existing suggestion. type says which of the two request shapes you are sending. The locale comes from your tenant's settings.
Signed-in users only. Every run is attributed to the person who asked for it, and a machine-to-machine access token identifies the integration rather than a user, so an access token cannot create runs. Creating them from a backend integration needs a token that carries a user identity, which is not supported yet.
Generation happens in the background, so this returns 202 straight away with a run you then poll at GET /v1/generation-runs/{generationRunId} until it succeeds or fails.
An unknown segment, use case or parent_suggestion_id returns 404, as does a parent suggestion you are not allowed to read. A 403 means generating from your own instructions is switched off for your tenant (steering_disabled).
Generate content from your own instructions › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · type="steered_generation" · requires: segment_id, use_case_id, steering_text | |
| type = object · type="refinement" · requires: parent_suggestion_id, instruction |
typesegment_idA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
use_case_idA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
steering_textWhat you want the generated content to say or do — the product calls this the brief. It is instructions for the generator, not content to publish: the generated copy is written for the segment you named and will not quote this text back.
Counted in Unicode characters, not bytes, and the same 4000-character ceiling is enforced again after the request passes schema validation, as 422 input_too_long. Text that is empty once trimmed is refused as 422 input_rejected.
variant_countHow many alternative pieces of content to generate from the one brief. They arrive together in the run's suggestion-set, numbered variant_no 1 upwards. Omit it and one variant is generated.
This applies only to a brief. Ready-made (precompute) content is generated with a per-use-case count you do not control, so a ready-made set can hold more variants than the maximum here.
Generate content from your own instructions › Responses
The run was accepted; poll it for status.
idA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
typeWhich request produced this run. steered_generation is the product's brief; refinement is an edit of an existing suggestion.
statuscreated_atWhen the run was accepted, not when it started generating. A run can sit at queued for a while, so do not measure generation time from here.
created_byThe user who submitted the run. Never null: a run can only be created by a signed-in user, so there is no unattributed run.
attempt_countHow many attempts have started. 0 on the run you get back from POST /v1/generation-runs, because nothing has picked it up yet.
A run that stalls returns to queued and is tried once more, so watching this go up while status goes back to queued is normal progress, not a failure. Only status: failed is terminal — do not give up on a retry.
A generation request. type says which of the two shapes you are sending. The locale comes from your tenant's settings.
steered_generation is the request behind what the product calls a brief: you supply the instructions. refinement edits one suggestion that already exists. Ready-made content — the Inspiration catalogue — is deliberately not a value here: it is produced on a schedule rather than requested, and is read through GET /v1/inspiration.
The suggestion-set a succeeded steered_generation run produced. Always null for a refinement run — see suggestion_id.
The turn a succeeded refinement run appended to its thread. Always null for a steered_generation run — see suggestion_set_id.
Why the run failed, if it fails.
Fetch a generation run by id
Poll this to follow a run's progress. A signed-in user can fetch a run they submitted, and an access-token caller can fetch any run in the tenant. A run you cannot see returns 404, not 403.
path Parameters
generationRunIdA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
Fetch a generation run by id › Responses
The generation run.
idA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
typeWhich request produced this run. steered_generation is the product's brief; refinement is an edit of an existing suggestion.
statuscreated_atWhen the run was accepted, not when it started generating. A run can sit at queued for a while, so do not measure generation time from here.
created_byThe user who submitted the run. Never null: a run can only be created by a signed-in user, so there is no unattributed run.
attempt_countHow many attempts have started. 0 on the run you get back from POST /v1/generation-runs, because nothing has picked it up yet.
A run that stalls returns to queued and is tried once more, so watching this go up while status goes back to queued is normal progress, not a failure. Only status: failed is terminal — do not give up on a retry.
A generation request. type says which of the two shapes you are sending. The locale comes from your tenant's settings.
steered_generation is the request behind what the product calls a brief: you supply the instructions. refinement edits one suggestion that already exists. Ready-made content — the Inspiration catalogue — is deliberately not a value here: it is produced on a schedule rather than requested, and is read through GET /v1/inspiration.
The suggestion-set a succeeded steered_generation run produced. Always null for a refinement run — see suggestion_id.
The turn a succeeded refinement run appended to its thread. Always null for a steered_generation run — see suggestion_set_id.
Why the run failed, if it fails.