Skip to main content

​
Create Dataset

Create a named dataset to organize your candidate tracks.
  • /trace/v1/dataset

​
Request Body

FieldTypeRequiredDescription
namestring✅Unique name for the dataset
descriptionstringOptional 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.