Starts a paid, prepaid analysis package from text inputs; the whole quoted price is charged in credits immediately. Call it only after the user approved the quoted price from qualitative_quote_analysis (show price, model and effort first). Requires sign-in (OAuth connector or API key) with the runs:write scope. Pass `quoted_price_credits`, `expected_model` and `expected_effort` from that quote: if the price or the model changed, the call fails with quote_stale or model_changed and nothing is charged; show the new values to the user and ask again. Inputs are JSON text only (`inputs.transcript`: 1-10 items {name, text}; every other slot: one item), at most about 1 MB of text per call; larger inputs need the REST API with a multipart upload. It returns at once with a `run_id`; the analysis runs in the background, so follow it with qualitative_get_run. Do not call this tool again to check progress. Without an `idempotency_key` the key is derived from the exact input, so an identical call within 24 hours returns the same analysis (`replayed`: true) and is not charged again (after 24 hours it starts and charges a new one); to deliberately start a second identical analysis, pass a new `idempotency_key`. Without enough credits it answers payment_required and charges nothing; credits are managed in the user's SurveysAI account on the website.
View input schema
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Short title of the analysis, shown in the web app."
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "A preset id from qualitative_list_presets."
},
"analysis_brief": {
"type": "object",
"properties": {
"objective": {
"type": "string",
"minLength": 1,
"maxLength": 5000
},
"context": {
"type": "string",
"maxLength": 10000
},
"audience": {
"type": "string",
"maxLength": 1000
},
"outputPreference": {
"type": "string",
"maxLength": 1000
},
"conceptualGrounding": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"sensitizing",
"interpretive_lens",
"deductive_framework"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 50000
},
"source": {
"type": "string",
"minLength": 1,
"maxLength": 500
}
},
"required": [
"mode",
"content",
"source"
]
},
"evaluationPurpose": {
"type": "string",
"enum": [
"formative",
"summative",
"process",
"impact",
"developmental"
]
},
"recommendations": {
"type": "string",
"enum": [
"include",
"omit"
]
},
"codebookMode": {
"type": "string",
"enum": [
"locked",
"extend"
]
},
"reportFor": {
"type": "string",
"enum": [
"research_team",
"client"
]
}
},
"required": [
"objective"
],
"description": "The research objective (required, up to 5000 characters) and optional context."
},
"language": {
"default": "en",
"type": "string",
"minLength": 1,
"maxLength": 40,
"description": "Analysis output language, a BCP 47 code such as en, cs or de."
},
"selected_reports": {
"default": [],
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"report_language": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"report_audience": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"quoted_price_credits": {
"type": "integer",
"minimum": 0,
"maximum": 100000000,
"description": "The `price_credits` of the quote the user approved (qualitative_quote_analysis). A higher server price fails with quote_stale and charges nothing."
},
"expected_model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "The `model` of the approved quote."
},
"expected_effort": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 20
},
{
"type": "null"
}
],
"description": "The `effort` of the approved quote (null when the quote has none)."
},
"inputs": {
"type": "object",
"properties": {
"transcript": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
},
"outline": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
},
"fieldNotes": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
},
"contextMetadata": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
},
"conceptualFramework": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
},
"codebook": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
},
"evaluationFramework": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^\\\\/\\u0000-\\u001f]+$",
"description": "File name shown in the app, e.g. interview-01.md (.md or .txt)."
},
"text": {
"type": "string",
"minLength": 1,
"description": "UTF-8 text, at most 5 MB."
}
},
"required": [
"name",
"text"
],
"additionalProperties": false
}
}
},
"additionalProperties": false,
"description": "Input texts by slot: transcript 1-10 items {name, text}, every other slot one item. At most about 1 MB of text in total; larger inputs need the REST API."
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[\\x21-\\x7e]+$",
"description": "Optional key (printable ASCII, at most 255 characters). Omit it normally: the key is derived from the exact input, so an identical call within 24 hours returns the same analysis (`replayed`: true) and is not charged again. To deliberately start a second identical analysis, pass a new idempotency_key."
}
},
"required": [
"title",
"preset_id",
"analysis_brief",
"quoted_price_credits",
"expected_model",
"expected_effort",
"inputs"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}