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. PUT each part with its size bytes before partUrlsExpireAt (one hour by default); expiresAt is the 24-hour session lifetime, not the URLs’. After uploading all parts to their presigned URLs, call POST /api/v1/tracesets/upload-url/complete to finalize the upload. An upload with primary files must declare its rank count in workloadMetadata, as shape.rankCount or as parallelism degrees (dp, tp, sp, ep, pp, multiplied together); the declaration is checked before any upload URL is issued, and the traceset reports it as rankCountDerived. An upload of supporting files only needs no declaration.

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	-
`workloadMetadata`	WorkloadMetadata	No	Workload characterization metadata, stored on the traceset as given. It declares the traceset’s rank count, which an upload with primary files must declare: either shape.rankCount, or the parallelism degrees parallelism.dp, tp, sp, ep and pp, multiplied together, with an absent degree counting as 1 (cp and fsdp are not factors). When both are given they must be equal. Each value must be a whole number of at least 1. The traceset reports that count as rankCountDerived, and attaching the traceset to a configuration uses it; it cannot be changed after upload. The canonical structure is trace-service’s WorkloadMetadata (trace-service/openapi.json#WorkloadMetadata); this field accepts any JSON object of at most 65,536 bytes when serialized.

{
  "workspaceId": "workspace_def456",
  "name": "GPT-175B Training Traces",
  "description": "Chakra traces for GPT-175B on 2 ranks",
  "tags": [
    "gpt",
    "training"
  ],
  "workloadMetadata": {
    "shape": {
      "rankCount": 2
    }
  },
  "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,
          "size": 1048576,
          "url": "https://scala-traces.s3.amazonaws.com/...?X-Amz-Algorithm=..."
        }
      ],
      "partUrlsExpireAt": "2026-02-23T15:30:00Z"
    }
  ],
  "expiresAt": "2026-02-24T14:30:00Z"
}

400 - Invalid request: empty files list or missing required fields; primary files without a declared rank count; a shape.rankCount or parallelism degree that is not a whole number of at least 1; a shape.rankCount that differs from the parallelism product; a declared rank count above 2,147,483,647; or a workloadMetadata, shape or parallelism that is neither an object nor null. The message names the field at fault.

{
  "error": {
    "message": "Uploads with primary trace files must declare a rank count: set workloadMetadata.shape.rankCount, or workloadMetadata.parallelism degrees (dp, tp, sp, ep, pp)"
  }
}

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 is ready when this returns, every file reports metadataStatus complete, and the platform does not process the trace files: the rank count is the one declared at upload. With exactly one primary file, that file reports rankRange 0 to N−1 for N declared ranks. Returns 201 on first completion or 200 on idempotent retry. The completion keeps running if this request times out (408) or disconnects: retry the same request, which answers 409 while the completion runs, then 200 once it has finished or 400 if it failed.

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": "ready",
  "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": "ready",
  "files": [
    {
      "name": "rank_0.chakra.json",
      "size": 1048576,
      "role": "primary"
    }
  ],
  "totalSize": 1048576
}

400 - Invalid request (missing parts, bad ETags, or an upload session minted by POST /api/v1/mapping-files/upload-url, which only POST /api/v1/mapping-files/upload-url/complete accepts)

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

404 - Upload session not found

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

409 - The upload session is being completed by another request, or by an earlier request that timed out; retry until it answers 200, or 400 if the completion failed (open a new upload session)

{
  "error": {
    "message": "Upload session is already being completed by another request"
  }
}

410 - Upload session expired

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

413 - An uploaded file is larger than the size declared for it at upload-url; its staged object is deleted and the upload session fails, so open a new upload session

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "File rank_0.chakra.json is 2097152 bytes, larger than its declared size of 1048576 bytes"
  }
}

Getting Started

API Reference

Models

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