> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scalacomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracesets

> Trace file management (feature-gated: enable_trace_routes)

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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

**404** - Traceset not found

```json theme={null}
{
  "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 | - |

```json theme={null}
{
  "topologyId": "config_ghi789"
}
```

### Responses

**200** - Validation result

```json theme={null}
{
  "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

```json theme={null}
{
  "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` | UploadWorkloadMetadata | 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. UploadWorkloadMetadata describes the rank-count members; this field accepts any JSON object of at most 65,536 bytes when serialized whose rank-count members are valid, including members UploadWorkloadMetadata does not describe. |
| `workloadMetadata.shape` | WorkloadShape (nullable) | No | Workload scale. `shape.rankCount` declares the rank count. JSON null counts as absent. |
| `workloadMetadata.shape.rankCount` | integer (nullable) | No | Total rank count: a whole number from 1 to 2,147,483,647. Declaring it alone is enough; parallelism degrees are optional. When parallelism degrees are also given, their product must equal it. JSON null counts as absent. |
| `workloadMetadata.parallelism` | WorkloadParallelism (nullable) | No | Parallelism degrees. When at least one of `dp`, `tp`, `sp`, `ep` and `pp` is given, their product declares the rank count. JSON null counts as absent. |
| `workloadMetadata.parallelism.dp` | integer (nullable) | No | Data parallelism degree: the number of data-parallel ranks, each processing its own share of the global batch and synchronizing gradients with the others. Without FSDP each holds a full replica of the model; with `fsdp`, each group of `fsdp` of them holds one replica between them, so there are `dp` ÷ `fsdp` replicas. |
| `workloadMetadata.parallelism.tp` | integer (nullable) | No | Tensor parallelism degree: the number of ranks that split each layer's weight matrices, and the layer's computation, between them. |
| `workloadMetadata.parallelism.sp` | integer (nullable) | No | Sequence parallelism degree: the number of ranks that split each input sequence along its length. |
| `workloadMetadata.parallelism.ep` | integer (nullable) | No | Expert parallelism degree: the number of ranks a mixture-of-experts (MoE) model's experts are distributed across, each rank holding a subset of the experts and exchanging tokens with the others. |
| `workloadMetadata.parallelism.pp` | integer (nullable) | No | Pipeline parallelism degree: the number of pipeline stages, each a contiguous group of the model's layers on its own ranks, that microbatches pass through in turn. |

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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 | - |

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

### Responses

**201** - Upload completed and traceset created

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "error": {
    "message": "Missing parts for file 'rank_0.chakra.json'"
  }
}
```

**404** - Upload session not found

```json theme={null}
{
  "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)

```json theme={null}
{
  "error": {
    "message": "Upload session is already being completed by another request"
  }
}
```

**410** - Upload session expired

```json theme={null}
{
  "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

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

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.