Skip to main content

Get Collection

Retrieve detailed information about a specific collection.

GET /api/collections/{id}

Authorization​

  • Customer: Can view their own collections only
  • Analyst: Can view any collection

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCollection ID

Response​

{
  "id": "col_abc123",
  "customer": {
    "id": "cus_xyz789",
    "company_name": "Acme Corp",
    "contact_name": "Jane Smith",
    "contact_email": "jane@acme.com"
  },
  "connector": {
    "id": "conn_slack001",
    "platform_name": "Slack",
    "version": "1.2.0",
    "endpoints": [
      {
        "id": "ep_001",
        "path": "/api/conversations.list",
        "method": "GET"
      }
    ]
  },
  "credential": {
    "id": "cred_abc123",
    "credential_type": "oauth2",
    "validation_status": "valid",
    "expires_at": "2024-06-15T00:00:00Z"
  },
  "assigned_analyst": {
    "id": "analyst_001",
    "full_name": "John Doe"
  },
  "case_reference": "CASE-2024-001",
  "business_context": "Internal investigation - HR matter",
  "priority": "high",
  "scope_config": {
    "date_range": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T23:59:59Z"
    }
  },
  "status": "in_progress",
  "progress": {
    "total_endpoints": 12,
    "completed_endpoints": 5,
    "failed_endpoints": 0,
    "total_files_collected": 234,
    "total_bytes_collected": 15728640
  },
  "timestamps": {
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:35:00Z",
    "paused_at": null,
    "completed_at": null,
    "reviewed_at": null,
    "signed_off_at": null,
    "delivered_at": null
  },
  "error_message": null,
  "error_count": 0,
  "last_error_at": null,
  "delivery": null
}

When Collection is Delivered​

The delivery field is populated after delivery:

{
  "delivery": {
    "zip_file_path": "collections/col_abc123/delivery.zip",
    "sas_url": "https://storage.blob.core.windows.net/...",
    "sas_expires_at": "2024-01-20T00:00:00Z"
  }
}

Example Request​

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

Error Responses​

403 Forbidden​

Customer trying to access another customer's collection:

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

404 Not Found​

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