> ## Documentation Index > Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bulk create scores > Create up to 100 scores in a single request. Per-item validation errors are collected and returned; valid items are committed together in a single batch insert. Infrastructure errors bubble as 500. ## OpenAPI ````yaml POST /v3/scores/bulk openapi: 3.0.3 info: title: Fiddler API - 2.0 description: APIs to interact with Fiddler termsOfService: https://fiddler.ai/about/terms contact: email: support@fiddler.ai license: name: Proprietary url: '2.0' version: '2.0' servers: [] security: - BearerAuth: [] tags: - name: access-key description: CRUD operations for API keys - name: span-v3 - name: aggregation-invalidation-request-v3 description: Endpoints related to retrieving aggregation invalidation requests - name: alert-rules-v3 description: CRUD for Alert Rules, Summary, and Stats APIs - name: application-v3 - name: attribute-v3 - name: auth description: Authentication strategies and login flows - name: baseline-v3 description: CRUD for baseline - name: catalog-v3 description: >- Entity catalog provides paginated, searchable discovery of entity names (attribute keys, agent names, span types, span names, score names, evaluator config names) and their distinct values. Powered by ClickHouse materialized views — no worker or PostgreSQL dependency. - name: chart-annotation-v3 description: Endpoints related to retrieving chart annotations - name: chart-v3 description: CRUD for chart - name: queries-v3 description: v3 queries API - name: configuration-v3 description: CRUD for configurations - name: custom-metrics-v3 - name: dimensionality-reduction-v3 - name: environment-v3 description: Endpoints related to environment management - name: evals - name: datasets - name: evaluation-v3 - name: evaluator-v3 - name: rule-evaluators-v3 - name: experiment-v3 - name: explainability-v3 - name: llm_rca-v3 - name: file-upload description: Endpoints related to file uploading. - name: fql-expressions-v3 description: > Endpoints for listing FQL (Fiddler Query Language) functions available for GenAI custom metrics. Used by the frontend for autocomplete and signature hints in the FQL editor. - name: genai-alert-rules-v3 description: CRUD API for GenAI Alert Rules - name: genai-custom-metrics-v3 description: API for GenAI Custom Metrics - name: genai-metrics-v3 description: >- Endpoints for pre-aggregated GenAI metrics. All metric data is pre-aggregated by an hourly ClickHouse refreshable materialized view; no real-time aggregation is performed at request time. - name: guardrails-api description: Endpoints related to retrieving Guardrails specific data - name: ingestion-v3 - name: intercom-api description: Endpoints related to intercom APIs - name: jobs-v3 - name: llm-gateway-v3 - name: auth-login - name: auth-logout - name: mcp-client-setup-v3 description: Endpoints for retrieving MCP client setup instructions. - name: metrics-v3 description: Metrics endpoints - name: model-v3 - name: dashboard-v3 - name: model-deployment-v3 - name: monitoring-summary-v3 - name: histograms-v3 - name: organization-roles-v3 description: Update user org role - name: organization-settings-v3 description: Update organization settings such as timezone, email configuration, etc. - name: pagerduty-api description: CRUD for Pagerduty services. - name: project-v3 - name: project-roles-v3 description: Project role assignment management - name: scores-v3 description: Unified CRUD for scores and annotations - name: searchable-text-key-v3 description: >- Manage the global searchable text keys table that controls which OTel attribute keys are routed to the full-text-searchable `ValueContent` column in the unified attributes table. Changes propagate to the backing ClickHouse dictionary within 1-2 minutes and affect all tenants. - name: segments-v3 - name: semantic-mapping-v3 description: >- Manage the global semantic name mappings table that maps raw OTel attribute keys to canonical semantic concepts. Changes propagate to the backing ClickHouse dictionary within 1-2 minutes and affect all tenants. - name: server-info-v3 description: Endpoints related to retrieving server information - name: sessions-v3 description: v3 session APIs - name: team-roles-v3 - name: team-v3 - name: traces-v3 description: v3 trace api for monitoring - name: fetch-sessions-v3 description: v3 fetch sessions api for monitoring - name: user-access-key description: > CRUD operations for user API keys. All endpoints are user-scoped — each user can only operate on their own API keys. No one including Org admins have access to other users' API keys. - name: users-v3 - name: version-compatibility-v3 - name: webhooks externalDocs: url: https://docs.fiddler.ai description: Find out more about Fiddler paths: /v3/scores/bulk: post: tags: - scores-v3 summary: Bulk create scores description: > Create up to 100 scores in a single request. Per-item validation errors are collected and returned; valid items are committed together in a single batch insert. Infrastructure errors bubble as 500. operationId: bulkCreateScores requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkCreateScoresRequest' example: application_id: 550e8400-e29b-41d4-a716-446655440000 scores: - name: correctness span_id: span-001 score_type: numeric value: 0.95 source: human - name: sentiment span_id: span-002 score_type: categorical label: positive source: llm annotator_id: gpt-4o responses: '200': description: > Bulk operation completed. Always returns 200 regardless of per-item outcome — check the errors array for individual item failures. A fully-failed batch still returns 200 with created: 0 and a populated errors array. content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/BulkCreateScoresResponse' example: data: created: 2 errors: [] api_version: '3.0' kind: NORMAL '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' components: schemas: BulkCreateScoresRequest: type: object description: Request body for bulk score creation. required: - application_id - scores properties: application_id: type: string format: uuid description: Application UUID (shared across all items) scores: type: array minItems: 1 maxItems: 100 description: List of scores to create (max 100) items: $ref: '#/components/schemas/BulkScoreItem' additionalProperties: false ApiResponse: type: object description: | Response object for standard API responses. properties: api_version: type: string default: '3.0' enum: - '2.0' - '3.0' description: | API version. kind: type: string default: NORMAL enum: - NORMAL description: | Type of response, indicating a normal response. BulkCreateScoresResponse: type: object description: Response from bulk score creation. properties: created: type: integer description: Number of scores successfully created errors: type: array description: Per-item validation errors (empty when all items succeed) items: $ref: '#/components/schemas/BulkScoreError' BulkScoreItem: allOf: - $ref: '#/components/schemas/BaseScoreFields' - type: object description: > Single item in a bulk create request. Same fields as CreateScoreRequest except application_id (provided at top level). required: - name - score_type - source BulkScoreError: type: object description: Error detail for a single item in a bulk request. properties: index: type: integer description: Zero-based index of the failed item in the request array message: type: string description: Human-readable error message ErrorResponse: type: object description: | Response object for errors returned by the API. properties: api_version: type: string default: '3.0' enum: - '2.0' - '3.0' description: | API version of the response. kind: type: string default: ERROR enum: - ERROR description: | Type of response, usually indicating an error. error: type: object properties: code: type: integer format: int32 description: > Represents the code for this error, typically an HTTP response code. default: 400 enum: - 400 - 403 - 404 - 500 message: type: string description: > A human-readable message providing more details about the error. If there are multiple errors, it will be the message for the first error. example: Resource Not Found errors: type: array description: > Container for additional information regarding the error, especially for multiple errors. items: type: object properties: reason: type: string description: > Unique identifier for this error, different from the error code. example: ResourceNotFoundException message: type: string description: > A human-readable message providing more details about the error. If there is only one error, this field will match error.message. example: Resource Not Found help: type: string description: > Link to support or documentation providing more information on the error. BaseScoreFields: type: object description: > Common fields shared by CreateScoreRequest and BulkScoreItem. Not used directly — referenced via allOf composition. properties: id: type: string format: uuid description: > Optional client-provided score ID for upsert. If not provided, a deterministic UUID v5 is generated from (application_id, target_id, name, annotator_id). name: type: string minLength: 1 maxLength: 255 description: Score name (e.g. "correctness") span_id: type: string description: >- Target span ID. Exactly one of span_id, trace_id, or session_id is required. trace_id: type: string description: >- Target trace ID. Exactly one of span_id, trace_id, or session_id is required. session_id: type: string description: >- Target session ID. Exactly one of span_id, trace_id, or session_id is required. score_type: type: string enum: - numeric - boolean - categorical - text description: > Score type. Determines which value field is required. Vector type is not accepted on create (used by evaluators only). value: type: number format: double description: > Numeric value. Required for numeric type. For boolean type, must be exactly 1.0 or 0.0 (runtime-validated; out-of-range values return 422). label: type: string description: Categorical label. Required for categorical type. text: type: string maxLength: 65536 description: Text content. Required for text type. source: type: string enum: - human - llm - code description: > Score source. Evaluator is not accepted (evaluator scores are created by the enrichment worker, not via this API). annotator_id: type: string description: > Annotator identifier. Required for source=llm and source=code. Ignored for source=human (backend populates from auth token). reasoning: type: string description: Optional reasoning or explanation metadata: type: object additionalProperties: type: string description: Arbitrary key-value metadata (string to string map) config_name: type: string description: Configuration name. Defaults to name if not provided. responses: '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Retry-After: schema: type: integer description: Seconds to wait before retrying X-RateLimit-Limit: schema: type: string description: Rate limit policy X-RateLimit-Remaining: schema: type: integer description: Remaining requests in current window X-RateLimit-Reset: schema: type: integer description: Unix timestamp when the rate limit resets '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer ````