> ## 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 add spans to dataset > Accept a list of explicit span references and a field mapping, fetch span attributes from ClickHouse, apply the mapping server-side, and write one dataset item per span. All-or-nothing — if any span cannot be resolved, no items are written and a 422 is returned with the list of unresolvable spans. `start_time` and `end_time` are required to bound the ClickHouse lookup to the relevant monthly partitions. Without them, the query would scan every partition for the application. The FE should pass the datagrid's current time range; MCP agents should pass the time range of the spans being exported. Mapping values are span attribute keys as returned by `POST /v3/spans/fields` (e.g. `"system.gen_ai.usage.input_tokens"`, `"user.cost_usd"`). Each key maps to the corresponding value from the span's `span_attributes` dict. ## OpenAPI ````yaml POST /v3/evals/datasets/{dataset_id}/items/from-spans 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) 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: 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: 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/evals/datasets/{dataset_id}/items/from-spans: parameters: - name: dataset_id in: path description: Dataset UUID required: true schema: type: string format: uuid post: tags: - evals - datasets summary: Bulk add spans to dataset description: >- Accept a list of explicit span references and a field mapping, fetch span attributes from ClickHouse, apply the mapping server-side, and write one dataset item per span. All-or-nothing — if any span cannot be resolved, no items are written and a 422 is returned with the list of unresolvable spans. `start_time` and `end_time` are required to bound the ClickHouse lookup to the relevant monthly partitions. Without them, the query would scan every partition for the application. The FE should pass the datagrid's current time range; MCP agents should pass the time range of the spans being exported. Mapping values are span attribute keys as returned by `POST /v3/spans/fields` (e.g. `"system.gen_ai.usage.input_tokens"`, `"user.cost_usd"`). Each key maps to the corresponding value from the span's `span_attributes` dict. operationId: bulkAddSpansToDatasetV3 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkAddSpansRequest' responses: '201': description: Dataset items created from spans content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/BulkAddSpansResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': description: >- One or more spans could not be resolved. No items were written. The errors array identifies which span references failed and why. content: application/json: schema: $ref: '#/components/responses/422' example: error: code: 422 message: >- One or more spans could not be resolved. No items were written. errors: - reason: SpanNotFound message: >- Span span-002-b (trace 4f9fa507) not found within the specified time range api_version: '3.0' kind: ERROR '500': $ref: '#/components/responses/500' components: schemas: BulkAddSpansRequest: type: object required: - application_id - start_time - end_time - spans - mapping properties: application_id: type: string format: uuid description: UUID of the GenAI application to query spans from start_time: type: string format: date-time description: >- Start of the time range (inclusive, UTC). Used to bound the ClickHouse partition scan to the relevant monthly partitions. Should match the time range of the spans being exported. end_time: type: string format: date-time description: >- End of the time range (exclusive, UTC). Used to bound the ClickHouse partition scan to the relevant monthly partitions. Should match the time range of the spans being exported. spans: type: array items: $ref: '#/components/schemas/SpanReference' minItems: 1 maxItems: 200 description: >- Explicit span references to resolve and write as dataset items. Maximum 200 per request. mapping: $ref: '#/components/schemas/FieldMapping' 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. BulkAddSpansResponse: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/BulkAddSpansResultItem' description: >- Created dataset items, one per input span reference, in the same order as the request. All spans were resolved — if any span could not be resolved, no items are written and a 422 is returned instead. SpanReference: type: object required: - trace_id - span_id properties: trace_id: type: string description: OpenTelemetry trace ID (hex string) span_id: type: string description: OpenTelemetry span ID (hex string) FieldMapping: type: object description: >- Maps dataset field keys to source span attribute paths. Each bucket contains { field_key: source_attr_path } pairs where source_attr_path is an OTel-convention key from the span's attributes. properties: inputs: type: object additionalProperties: type: string example: question: gen_ai.request.user_message expected_outputs: type: object additionalProperties: type: string example: answer: gen_ai.completion.content metadata: type: object additionalProperties: type: string example: trace_id: trace.id model: gen_ai.request.model extras: type: object additionalProperties: type: string example: context: gen_ai.contents.context BulkAddSpansResultItem: type: object required: - trace_id - span_id - item_id properties: trace_id: type: string description: OpenTelemetry trace ID (hex string) span_id: type: string description: OpenTelemetry span ID (hex string) item_id: type: string format: uuid description: UUID of the created dataset item 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. responses: '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer ````