Datasets - Soundverse

Create Dataset

Create a named dataset to organize your candidate tracks.

/trace/v1/dataset

Request Body

Field	Type	Required	Description
`name`	string	✅	Unique name for the dataset
`description`	string		Optional description for the dataset

Request Body Example

{
  "name": "my-reference-catalog",
  "description": "Our main candidate lookup library"
}

Response

Status 201 Created

{
  "dataset_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "user_id": "user_12345",
  "name": "my-reference-catalog",
  "description": "Our main candidate lookup library",
  "created_at": "2026-06-19T12:00:00Z",
  "ingested_tasks": [],
  "encoder_types": []
}

List Datasets

List all datasets owned by the authenticated API key user.

/trace/v1/dataset

Response

Status 200 OK

[
  {
    "dataset_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "user_id": "user_12345",
    "name": "my-reference-catalog",
    "description": "Our main candidate lookup library",
    "created_at": "2026-06-19T12:00:00Z",
    "ingested_tasks": [
      "full_audio_latent",
      "light_stem"
    ],
    "encoder_types": [
      "type1"
    ]
  }
]

Get Dataset Details

Retrieve details for a specific dataset using its unique ID.

/trace/v1/dataset/{dataset_id}

Response

Status 200 OK

{
  "dataset_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "user_id": "user_12345",
  "name": "my-reference-catalog",
  "description": "Our main candidate lookup library",
  "created_at": "2026-06-19T12:00:00Z",
  "ingested_tasks": [
    "full_audio_latent",
    "light_stem"
  ],
  "encoder_types": [
    "type1"
  ]
}

Limits & Validation Errors

To prevent processing failures, datasets enforce the following system limits:

File Sizes: Max 100 MB per file.
Track Duration: Max 300 seconds (5 minutes) per track.
File Formats: .mp3, .wav, .flac, .m4a files only.
Max Number of Files: Max 10 blobs per /trace/v1/ingest/type* request.
Max Search Matrix (M×N): Max 100,000 comparison pairs per search job.

Common Error Scenarios

400 Bad Request: Returned if a batch exceeds 10 files, the audio duration is longer than 5 minutes, or the file format is unsupported.
413 Payload Too Large: Returned during upload if a file exceeds 100 MB.
404 Not Found: Returned if the requested dataset_name does not exist in the database.

​Create Dataset

​Request Body

​Response

​List Datasets

​Response

​Get Dataset Details

​Response

​Limits & Validation Errors

​Common Error Scenarios

Create Dataset

Request Body

Response

List Datasets

Response

Get Dataset Details

Response

Limits & Validation Errors

Common Error Scenarios