Sign in

v3

latestOpenAPI 3.1.02026-07-311,4541,5202.3 MB
datasets

Create Dataset

Create or duplicate datasets

Endpoint: POST /api/datasets/ - Create a dataset (from logs, empty, or by duplicating an existing one)

Args (POST): - name (string, required) - description (string, optional) - start_time (string, required, ISO 8601) — ignored if is_empty=true or source_dataset_id set - end_time (string, required, ISO 8601) — ignored if is_empty=true or source_dataset_id set - sampling (integer, optional, default 100) — percent of logs to add - initial_log_filters (object, optional, default {}) - is_empty (boolean, optional, default false) — create empty dataset without adding logs - source_dataset_id (string, optional) — duplicate an existing dataset. Copies all logs asynchronously. When set, start_time/end_time/sampling/initial_log_filters are ignored. Name defaults to "{source_name} (copy)" if not provided.

Returns (POST 201): { "id": "dataset_id", "name": "...", "type": "sampling", "status": "initializing", ... }

Notes: - Server sets organization and updated_by; type defaults to "sampling". - If selected logs exceed plan limits, returns 400 with error message. - Duplication fires dataset_processing_complete WS event when done (same as import).

post/api/datasets/

Headers

Authorizationstring required

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request body

organizationinteger required
namestring required
descriptionstring
type'llm' | 'human' | 'dataset' | 'sampling' | 'reference'
  • llm - Llm
  • human - Human
  • dataset - Dataset
  • sampling - Sampling
  • reference - Reference
granularity'logs' | 'traces' | 'threads'
  • logs - Logs
  • traces - Traces
  • threads - Threads
initial_log_filtersFilterParamDictPydantic

Pydantic model for FilterParamDict. A dictionary that maps metric names to their filter parameters.

Each key is a metric name (str), and each value can be:

  • A single MetricFilterParamPydantic (one condition)
  • A List[MetricFilterParamPydantic] (multiple conditions for same metric)
  • A FilterBundlePydantic (nested filter bundle with connector)

Note: Uses extra="allow" for dynamic metric name fields. The pydantic_extra annotation tells Pydantic what types to expect for extra fields, and generates typed additionalProperties in JSON Schema.

start_timestring date-time
end_timestring date-time
samplinginteger

Percent of logs to add (1-100).

is_emptyboolean

Create empty dataset without adding logs.

source_dataset_idstring

ID of dataset to duplicate. Copies all logs asynchronously.

Response

idstring required
organizationinteger required
namestring required
descriptionstring
type'llm' | 'human' | 'dataset' | 'sampling' | 'reference'
  • llm - Llm
  • human - Human
  • dataset - Dataset
  • sampling - Sampling
  • reference - Reference
granularity'logs' | 'traces' | 'threads'
  • logs - Logs
  • traces - Traces
  • threads - Threads
status'initializing' | 'ready' | 'failed' | 'loading' required
  • initializing - Initializing
  • ready - Ready
  • failed - Failed
  • loading - Loading
initial_log_filtersFilterParamDictPydantic

Pydantic model for FilterParamDict. A dictionary that maps metric names to their filter parameters.

Each key is a metric name (str), and each value can be:

  • A single MetricFilterParamPydantic (one condition)
  • A List[MetricFilterParamPydantic] (multiple conditions for same metric)
  • A FilterBundlePydantic (nested filter bundle with connector)

Note: Uses extra="allow" for dynamic metric name fields. The pydantic_extra annotation tells Pydantic what types to expect for extra fields, and generates typed additionalProperties in JSON Schema.

log_countinteger required
created_atstring date-time required
updated_atstring date-time required