> ## 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` | 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. |

```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.