> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an analysis group > A group of things to extract after a call. ```json theme={"dark"} { "name": "Lead QA", "description": "Qualification signals from sales calls.", "conditions": { "min_messages": 4 } } ``` A group runs as **one** extraction over the conversation, so items that belong together should share a group — it is cheaper and the answers stay consistent with each other. `conditions` skips the group when a call was too short to have said anything: a skipped group costs nothing and is reported as skipped rather than failed. Leave `model` unset and the group uses the agent's own model. Attach it by adding its `id` to an agent's `analysis_group_ids`. ## OpenAPI ````yaml developers/openapi.json POST /v1/custom-analysis/groups openapi: 3.1.0 info: title: Vocily API description: >- Public REST API for Vocily. Build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered. Authenticate with a workspace API key as a Bearer token. Some things stay in the dashboard, by design: creating an API key, buying or connecting a phone number, setting an agent's webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. version: v1 servers: - url: https://api.vocily.ai description: Production security: [] paths: /v1/custom-analysis/groups: post: tags: - custom-analysis summary: Create Custom Analysis Category description: >- Create a group. Its name becomes part of the key its values arrive under. operationId: create_custom_analysis_category_v1_custom_analysis_groups_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicAnalysisGroupCreate' example: name: Lead QA description: Qualification signals from sales calls. conditions: min_messages: 4 responses: '201': description: The created group. content: application/json: schema: type: object properties: id: type: string name: type: string description: type: string nullable: true model: type: string nullable: true temperature: type: number nullable: true max_tokens: type: integer nullable: true conditions: type: object is_default: type: boolean items: type: array items: type: object properties: id: type: string category_id: type: string name: type: string description: type: string result_format: type: string enum: - string - number - integer - boolean - array - object extraction_method: type: string enum: - ai - regex required: type: boolean constraints: type: object fields: type: array items: type: object enabled: type: boolean is_system: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time example: name: Lead quality description: What we ask the model to pull out of every call. model: null temperature: null max_tokens: null conditions: {} id: 0000000f-0000-4000-8000-00000000000f items: [] is_default: false created_at: '2026-09-16T19:38:04.226829Z' updated_at: '2026-09-16T19:38:04.226829Z' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: detail: Invalid API key code: UNAUTHORIZED '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded — honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: code: rate_limited security: - bearerAuth: [] components: schemas: PublicAnalysisGroupCreate: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: >- What to call this group. **It becomes part of the key values arrive under** — `custom_analysis["Lead QA"][…]` — so renaming it later changes your payload shape. description: anyOf: - type: string - type: 'null' title: Description description: Your own note about what the group is for. model: anyOf: - type: string maxLength: 128 - type: 'null' title: Model description: Which LLM runs the extraction. Defaults to the agent's own. temperature: anyOf: - maximum: 2 minimum: 0 type: number - type: 'null' title: Temperature description: >- Randomness for the extraction. Lower is more repeatable, which is usually what you want here. max_tokens: anyOf: - type: integer maximum: 10000 minimum: 50 - type: 'null' title: Max Tokens description: Cap on the extraction response. conditions: $ref: '#/components/schemas/CustomAnalysisConditions' description: >- When this group runs at all. A group that does not run costs nothing. additionalProperties: false type: object required: - name title: PublicAnalysisGroupCreate ApiError: type: object description: >- Error envelope. `code` is derived from the HTTP status, so branch on it for the CLASS of failure; the specific reason is `detail.code`. Every public refusal carries both. properties: detail: type: object description: >- The reason. `code` is the domain reason (e.g. `call_not_found`) and `message` is a sentence safe to log. On a `422` it also carries `errors[]`, one entry per rejected field — see `HTTPValidationError`. properties: code: type: string example: call_not_found message: type: string example: Call not found required: - code - message code: type: string description: Derived from the HTTP status, not the domain reason. example: NOT_FOUND HTTPValidationError: type: object title: HTTPValidationError description: >- A request the API could not read: a field of the wrong type, out of range, missing, or one we do not accept. Same envelope as every other error. properties: detail: type: object description: >- What was wrong, as `code`, a one-line `message`, and every offending field in `errors`. required: - code - message - errors properties: code: type: string enum: - validation_error message: type: string description: >- The first problem in one line, with a count of the rest — e.g. `model.temperature: Input should be less than or equal to 2 (and 1 more)`. errors: type: array items: $ref: '#/components/schemas/ValidationError' description: >- One entry per offending field. **Every problem is reported at once**, not just the first, so a malformed body needs one round trip to fix rather than one per field. code: type: string enum: - VALIDATION_ERROR description: Derived from the HTTP status, as on every error. CustomAnalysisConditions: properties: min_messages: anyOf: - type: integer minimum: 0 - type: 'null' title: Min Messages description: >- Skip the group unless the conversation ran at least this many messages. min_duration_seconds: anyOf: - type: integer minimum: 0 - type: 'null' title: Min Duration Seconds description: Skip it unless the call lasted at least this long. ended_reason: anyOf: - $ref: '#/components/schemas/CustomAnalysisEndedReasonCondition' - type: 'null' description: Run it only for calls that ended a particular way. additionalProperties: false type: object title: CustomAnalysisConditions description: >- Run a category only on the calls it applies to. Leave it empty and the category runs on every call. The fields are fixed rather than free-form, so a misspelled condition is a `422` instead of one that silently never matches. ValidationError: type: object title: ValidationError required: - field - message - type properties: field: type: string description: >- The offending field as a path from the root of your request — `voice.speed`, `variables[0].key`, or `query.limit` for a query parameter. **This is the field to read.** message: type: string description: What is wrong with it, in plain language. type: type: string description: >- A stable machine code for the kind of failure, e.g. `extra_forbidden` for a field we do not accept, `missing` for a required one, or `less_than_equal` for a number out of range. Switch on this rather than on `message`, which may be reworded. CustomAnalysisEndedReasonCondition: properties: operator: type: string title: Operator description: >- `one_of` to run the group only for these outcomes, `not_one_of` to run it for everything except them. values: items: type: string type: array title: Values description: >- How the call ended — one or more of `completed`, `voicemail`, `no_answer`, `busy`, `declined`, `failed`, `transfer_completed`, `transfer_failed`. These are the outcomes a *finished* call can hold, which is why the mid-call states are not offered: a condition on one would never match. Anything else is refused. additionalProperties: false type: object required: - operator title: CustomAnalysisEndedReasonCondition securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.' ````