Tracesets

Trace file management (feature-gated: enable_trace_routes)

Endpoints

Method	Path	Description
GET	`/api/v1/tracesets`	List tracesets
GET	`/api/v1/tracesets/{id}`	Get traceset
DELETE	`/api/v1/tracesets/{id}`	Delete traceset
GET	`/api/v1/tracesets/{id}/download`	Get traceset download URL
POST	`/api/v1/tracesets/{id}/validate`	Validate traceset
POST	`/api/v1/tracesets/upload-url`	Initiate multipart traceset upload
POST	`/api/v1/tracesets/upload-url/complete`	Complete multipart traceset upload

List tracesets

GET /api/v1/tracesets List all tracesets. Supports pagination, filtering by workspace/status, full-text name search, and date range filtering. Results are sorted by creation date (newest first) by default.

Parameters

Name	In	Type	Required	Description
`workspaceId`	query	string	No	Filter by workspace ID (format: `workspace_xxx`). If not provided, returns all tracesets accessible to the authenticated user.
`status`	query	string	No	Filter by traceset status. Valid values: `uploading`, `processing`, `ready`, `metadata_failed`, `upload_failed`, `deleted`.
`search`	query	string	No	Full-text search on traceset name (case-insensitive)
`sort`	query	string	No	Sort order: comma-separated list of `field:direction` pairs (e.g., `created:desc,name:asc`). Default: `created:desc`
`limit`	query	integer	No	Maximum number of items to return
`next`	query	string	No	Opaque cursor token from previous response’s nextCursor field
`createdAfter`	query	string	No	Filter by creation date — items created on or after this time (ISO 8601, inclusive)
`createdBefore`	query	string	No	Filter by creation date — items created before this time (ISO 8601, exclusive)

Responses

200 - Paginated list of tracesets

{
  "items": [
    {
      "id": "ts_abc123xyz",
      "name": "GPT-175B Training Traces",
      "status": "ready",
      "fileCount": 4,
      "createdAt": "2026-02-20T14:30:00Z"
    }
  ],
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "eyJjcmVhdGVkIjoiMjAyNi0wMi0yMFQxNDozMDowMFoifQ=="
  }
}

400 - Bad Request — Invalid query parameters (bad cursor, invalid sort field)

{
  "error": {
    "message": "Invalid sort field: 'unknown'. Valid fields: created, name, status"
  }
}

Get traceset

GET /api/v1/tracesets/{id} Returns a traceset by ID including all file metadata, tags, and expiration information.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Traceset ID (format: `ts_xxx`)

Responses

200 - Traceset details

{
  "id": "ts_abc123xyz",
  "name": "GPT-175B Training Traces",
  "description": "Chakra traces for GPT-175B on 256 ranks",
  "status": "ready",
  "files": [
    {
      "name": "rank_0.chakra.json",
      "size": 1048576,
      "role": "primary",
      "metadataStatus": "complete"
    }
  ],
  "totalSize": 4194304,
  "tags": [
    "gpt",
    "training"
  ],
  "workspaceId": "workspace_def456",
  "createdAt": "2026-02-20T14:30:00Z"
}

404 - Traceset not found

{
  "error": {
    "message": "Traceset 'ts_notfound' not found"
  }
}

Delete traceset

DELETE /api/v1/tracesets/{id} Soft-deletes a traceset. Associated library files are reference-counted and cleaned up asynchronously. Excluded when trace_routes_read_only is enabled.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Traceset ID (format: `ts_xxx`)

Responses

204 - Traceset deleted 404 - Traceset not found

{
  "error": {
    "message": "Traceset 'ts_notfound' not found"
  }
}

Get traceset download URL

GET /api/v1/tracesets/{id}/download Returns a presigned S3 download URL for a specific file within a traceset, or for the entire traceset archive if no file is specified. The URL expires after a short TTL.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Traceset ID (format: `ts_xxx`)
`file`	query	string	No	Specific file name within the traceset. If omitted, returns a URL for the entire traceset archive.

Responses

200 - Presigned download URL

{
  "url": "https://scala-traces.s3.amazonaws.com/ts_abc123xyz/rank_0.chakra.json?X-Amz-Algorithm=...",
  "expiresAt": "2026-02-23T20:30:00Z",
  "file": "rank_0.chakra.json"
}

400 - File uses an external URL that cannot be downloaded via presigned URL

{
  "error": {
    "message": "File 'external.dat' uses an external URL and cannot be downloaded via presigned URL"
  }
}

404 - Traceset not found

{
  "error": {
    "message": "Traceset 'ts_notfound' not found"
  }
}

Validate traceset

POST /api/v1/tracesets/{id}/validate Runs validation checks on a traceset including file integrity and metadata completeness. Optionally accepts a topologyId for compatibility validation, but the topology_correlation check currently always returns passed (not yet implemented).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Traceset ID (format: `ts_xxx`)

Request Body

Field	Type	Required	Description
`topologyId`	string (nullable)	No	-

{
  "topologyId": "config_ghi789"
}

Responses

200 - Validation result

{
  "valid": true,
  "checks": [
    {
      "name": "file_integrity",
      "passed": true
    },
    {
      "name": "metadata_complete",
      "passed": true
    },
    {
      "name": "topology_correlation",
      "passed": true,
      "message": "Not yet implemented \u2014 always passes"
    }
  ]
}

404 - Traceset not found

{
  "error": {
    "message": "Traceset 'ts_notfound' not found"
  }
}

Initiate multipart traceset upload

POST /api/v1/tracesets/upload-url Creates a traceset record and returns presigned S3 multipart upload URLs for each file. Each file is split into parts based on size. After uploading all parts to their presigned URLs, call POST /api/v1/tracesets/upload-url/complete to finalize the upload.

Request Body

Field	Type	Required	Description
`workspaceId`	string (nullable)	No	Workspace ID. If not provided, uses the universal traceset workspace.
`name`	string	Yes	-
`description`	string (nullable)	No	-
`tags`	array[string] (nullable)	No	-
`ttlDays`	integer (nullable)	No	Custom TTL in days (1-365). Uses server default if omitted.
`files`	array[UploadFileSpec]	Yes	-

{
  "workspaceId": "workspace_def456",
  "name": "GPT-175B Training Traces",
  "description": "Chakra traces for GPT-175B on 256 ranks",
  "tags": [
    "gpt",
    "training"
  ],
  "files": [
    {
      "name": "rank_0.chakra.json",
      "size": 1048576,
      "role": "primary"
    },
    {
      "name": "rank_1.chakra.json",
      "size": 1048576,
      "role": "primary"
    }
  ]
}

Responses

200 - Presigned upload URLs for each file part

{
  "uploadId": "upload_ghi789",
  "checksumAlgorithm": "SHA256",
  "files": [
    {
      "name": "rank_0.chakra.json",
      "parts": [
        {
          "partNumber": 1,
          "url": "https://scala-traces.s3.amazonaws.com/...?X-Amz-Algorithm=..."
        }
      ]
    }
  ],
  "expiresAt": "2026-02-24T14:30:00Z"
}

400 - Invalid request (empty files list, missing required fields)

{
  "error": {
    "message": "At least one file is required"
  }
}

Complete multipart traceset upload

POST /api/v1/tracesets/upload-url/complete Finalizes a multipart upload session by providing the ETags returned by S3 for all uploaded parts. The traceset transitions from uploading to processing state while metadata extraction runs asynchronously. Returns 201 on first completion or 200 on idempotent retry.

Request Body

Field	Type	Required	Description
`uploadId`	string	Yes	-
`files`	array[CompletedFileInput]	Yes	-

{
  "uploadId": "upload_ghi789",
  "files": [
    {
      "name": "rank_0.chakra.json",
      "parts": [
        {
          "partNumber": 1,
          "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
        }
      ]
    }
  ]
}

Responses

201 - Upload completed and traceset created

{
  "id": "ts_abc123xyz",
  "name": "GPT-175B Training Traces",
  "status": "processing",
  "files": [
    {
      "name": "rank_0.chakra.json",
      "size": 1048576,
      "role": "primary"
    }
  ],
  "totalSize": 1048576
}

200 - Idempotent retry — upload was already completed

{
  "id": "ts_abc123xyz",
  "name": "GPT-175B Training Traces",
  "status": "processing",
  "files": [
    {
      "name": "rank_0.chakra.json",
      "size": 1048576,
      "role": "primary"
    }
  ],
  "totalSize": 1048576
}

400 - Invalid request (missing parts, bad ETags)

{
  "error": {
    "message": "Missing parts for file 'rank_0.chakra.json'"
  }
}

404 - Upload session not found

{
  "error": {
    "message": "Upload session 'upload_notfound' not found"
  }
}

410 - Upload session expired

{
  "error": {
    "message": "Upload session 'upload_ghi789' has expired"
  }
}

Getting Started

API Reference

Reference

Examples

Release Notes

Endpoints

List tracesets

Parameters

Responses

Get traceset

Parameters

Responses

Delete traceset

Parameters

Responses

Get traceset download URL

Parameters

Responses

Validate traceset

Parameters

Request Body

Responses

Initiate multipart traceset upload

Request Body

Responses

Complete multipart traceset upload

Request Body

Responses

​Endpoints

​List tracesets

​Parameters

​Responses

​Get traceset

​Parameters

​Responses

​Delete traceset

​Parameters

​Responses

​Get traceset download URL

​Parameters

​Responses

​Validate traceset

​Parameters

​Request Body

​Responses

​Initiate multipart traceset upload

​Request Body

​Responses

​Complete multipart traceset upload

​Request Body

​Responses

Endpoints

List tracesets

Parameters

Responses

Get traceset

Parameters

Responses

Delete traceset

Parameters

Responses

Get traceset download URL

Parameters

Responses

Validate traceset

Parameters

Request Body

Responses

Initiate multipart traceset upload

Request Body

Responses

Complete multipart traceset upload

Request Body

Responses