Collection Files

List all files collected as part of a collection.

GET /api/collections/{id}/files

Authorization

• Customer: Can view files from their own collections
• Analyst: Can view files from any collection

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Query Parameters

Parameter	Type	Required	Description
include_download_urls	boolean	No	When true, each file includes a time-limited download_url (SAS)

Response

{
  "files": [
    {
      "id": "file_001",
      "original_filename": "conversation_C0123ABC.json",
      "stored_filename": "col_abc123/conversations/C0123ABC_1705312200.json",
      "file_path": "collections/col_abc123/conversations/C0123ABC_1705312200.json",
      "file_size_bytes": 24576,
      "mime_type": "application/json",
      "sha256_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "sha256_hash_validated": true,
      "status": "stored",
      "collected_at": "2024-01-15T12:30:00Z",
      "api_log_id": "log_xyz789",
      "download_url": "https://tracestorage.blob.core.windows.net/..."
    }
  ],
  "totals": {
    "count": 234,
    "total_bytes": 15728640,
    "validated_count": 234,
    "error_count": 0
  }
}

File Properties

Field	Description
original_filename	Name assigned during collection
stored_filename	Storage object name
file_path	Full storage path (Azure Blob)
sha256_hash	Cryptographic hash for integrity verification
sha256_hash_validated	Whether hash has been verified after storage
status	Per-file status
api_log_id	Link to the API call that collected this file (nullable)
download_url	Present only when include_download_urls=true

Totals

Field	Description
count	Number of files
total_bytes	Combined size
validated_count	Files whose hash has been validated
error_count	Files in an error state

Example Request

curl -X GET "https://api.traces.io/api/collections/col_abc123/files?include_download_urls=true" \
  -H "Authorization: Bearer <token>"

Use Cases

Verify File Integrity

Use the sha256_hash to verify files after download:

# After downloading a file
sha256sum downloaded_file.json
# Compare with sha256_hash from API

Audit Trail

Each file links to its api_log_id, which contains:

• Full request/response details
• Timestamp
• Rate limit information
• Any errors encountered

Error Responses

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have access to this collection"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Collection not found"
  }
}