---
title: "Label Existing Fields"
method: POST
path: "/v1/generate/fields/label-existing"
tags: ["generate"]
---

# Label Existing Fields

`POST /v1/generate/fields/label-existing`

## Request

- Base URL: `https://api.pioneer.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pioneer.ai/v1/generate/fields/label-existing`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/generate/fields/label-existing/post.ts> (a function with typed inputs; its response is checked against the schema)

Label existing data dictionaries with custom input/output field definitions.

Args:
    request: Fields labeling request with input dicts and field schemas.
    auth: Authenticated user context.

Returns:
    GenerateResponse with labeled samples and optional dataset info.

Raises:
    HTTPException: 400 on invalid field configuration, missing inputs, or dataset validation failure.
    HTTPException: 500 on labeling failure.

## Request body

- LabelExistingFieldsRequest: Label existing data with custom input/output fields
  - `user_id` string, nullable: User ID (optional, uses authenticated user if not provided)
  - `input_fields` RecordField[], required: Input field definitions
    - `name` string, required
    - `type` string
    - `description` string, nullable
    - `allowed_values` string[], nullable
  - `output_fields` RecordField[], required: Output field definitions
    - `name` string, required
    - `type` string
    - `description` string, nullable
    - `allowed_values` string[], nullable
  - `inputs` object[], required: List of input data dictionaries
  - `domain_description` string, nullable: Domain description for generation context
  - `seed` integer, nullable: Random seed for reproducibility
  - `session_id` string, nullable: Session ID for log streaming
  - `config_num_examples` integer: Number of examples to generate for config
  - `temperature` number: Generation temperature
  - `constraints` ConstraintRequest[], nullable: Custom constraints
    - `description` string, required: Constraint description
    - `choices` string[], nullable: Optional list of choices for this constraint
    - `weights` number[], nullable: Optional weights for choices (must align with choices length)
    - `probability` number, nullable: Optional probability (0.0-1.0) for this constraint
  - `save_dataset` boolean: Save generated dataset to S3 and database
  - `dataset_name` string, nullable: Name for the saved dataset (required if save_dataset=True)
  - `project_id` string, uuid, nullable: Project ID to assign the dataset to

## Response `200`

Successful Response

- GenerateResponse: Generation response
  - `success` boolean, required
  - `data` object[], required
  - `count` integer, required
  - `task_type` string, required
  - `token_usage` integer, nullable: Estimated tokens used for generation
  - `dataset` object, nullable: Dataset info if saved to S3/database

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-24** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/generate/fields/label-existing/post.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) - [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/0e5e86e2bae5?raw)