AgentsIQ
CUR Analyser ▾
CUR Analyser Overview API Reference

📚 CUR Analyser API Reference

REST API endpoints for AWS Cost & Usage Report analysis and data management

v1.1.0 Port 8002 FastAPI Base URL: http://<host>:8002

Authentication

All endpoints require: X-API-Key: <BACKEND_API_KEY> header

The backend orchestrator injects the Anthropic API key per-request; agents never store secrets.

Health & Chat

GET /health
Agent health check. Used by backend registry to verify agent is running.
Response
{ "status": "ok", "agent": "cur-analyser", "version": "0.2.0" }
Example
curl -X GET http://localhost:8002/health
POST /invoke
Chat invoke (non-streaming). Runs Claude tool-use loop for question answering.
Request Body
session_id (string) — Chat session ID for history tracking
user_message (string) — User question or command
context (object) — Query context (optional)
  • report_id — UUID of selected CUR report
  • has_data — Boolean flag if report has loaded data
Response
response — Claude's text response
metadata.tokens_used — Token count for billing
chart (object, optional) — Chart data if response includes visualization
Example
curl -X POST http://localhost:8002/invoke \ -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "session_id": "abc123", "user_message": "What is the top service by cost?", "context": {"report_id": "uuid-here", "has_data": true} }'
POST /invoke/stream
Streaming chat invoke. Response is SSE (Server-Sent Events) stream of text chunks.
Request Body
Same as /invoke
Response
SSE stream of chunks ending with [DONE]

Reports

GET /reports
List all uploaded CUR reports with metadata.
Response
Array of report objects:
id — Report UUID
filename — Original filename
row_count — Number of line items
total_cost — Sum of cost column
file_size — Bytes on disk
status — ready | processing | failed
date_range_start — Billing period start
date_range_end — Billing period end
Example
curl -X GET http://localhost:8002/reports \ -H "X-API-Key: your-api-key"
DELETE /reports/{report_id}
Delete a report and remove its on-disk file (DuckDB file and CSV cache).
Path Parameters
report_id (UUID) — ID of report to delete
Response
ok — Boolean success flag
deleted — Boolean deletion confirmation

CUR Data Upload

POST /data-sources/cur/upload
Upload single CUR file. Supports CSV, compressed (.gz, .zip), Parquet, CUR 2.0 JSON format. Max 2GB per file.
Request Body
file (file, multipart/form-data) — CUR file to upload
Response
job_id — UUID of upload job for polling
filename — Stored filename
Example
curl -X POST http://localhost:8002/data-sources/cur/upload \ -H "X-API-Key: your-api-key" \ -F "file=@report.csv.gz"
POST /data-sources/cur/upload-folder
Upload multiple CUR part files from one S3 export folder. Validates schema consistency and billing period match.
Request Body
files (files[], multipart/form-data) — Multiple CUR part files
Response
job_id — Upload job UUID
filename — Combined dataset filename
GET /data-sources/cur/upload-status/{job_id}
Poll upload job status. Check this repeatedly until status is 'ready' or 'failed'.
Response
job_id — The job UUID
status — uploading | decompressing | processing | ingesting | ready | failed | cancelled
filename — Name of file being processed
error (optional) — Error message if failed
report_id (optional) — Report UUID if ready
POST /data-sources/cur/upload-status/{job_id}/cancel
Cancel an in-progress upload job.
Response
ok — Boolean success
cancelled — Boolean if job was running

Inventory Enrichment

POST /data-sources/inventory/upload
Upload inventory XLSX file for CUR enrichment. 25 sheets with ARN, tag, and metadata columns.
Request Body
file (file, multipart/form-data) — Inventory XLSX file
Response
ok — Boolean success
source_id — Inventory source UUID
record_count — Total records ingested
matched_accounts — Number of unique accounts matched
DELETE /data-sources/inventory
Remove the current inventory file and disable enrichment.
Response
ok — Boolean success

Data Source Status

GET /data-sources/status
Get status of all uploaded CUR sources and inventory.
Response
cur_sources — Array of CUR source objects
active_cur_ids — List of currently active CUR report IDs
inventory — Inventory source metadata
GET /data-sources/active-report-id
Get the UUID of the currently active (selected) report in the registry.
Response
report_id — UUID of active report
GET /data-sources/storage-usage
Get CUR data directory storage usage vs 10GB cap.
Response
cur_used_bytes — Bytes consumed by CUR files
cur_used_gb — GB consumed (rounded)
disk_free_gb — Free space on disk
cap_gb — 10GB cap
used_pct — Percentage of cap used

Enrichment Analysis

GET /data-sources/inventory/coverage
Get inventory enrichment match rate for a specific report.
Query Parameters
report_id (UUID) — Target report ID
Response
enrichment_level — account | resource (highest level matched)
has_resource_column — Boolean if CUR has ResourceId
matched_accounts — Count of matched account IDs
account_match_rate — Percentage (0-100)
spend_match_rate_pct — Percentage of total cost matched
GET /data-sources/enriched-summary
Full enrichment summary with before/after coverage and per-service match rates.
Query Parameters
report_id (UUID) — Target report ID
Response
enrichment_level — Max enrichment level achieved
per_service — Array of service-level match stats
unmatched_top — Top 10 unmatched resources by cost
before_after — Coverage before/after for Environment, Customer, Cost Centre

Dashboard Data

GET /dashboard/tab/overview
Overview tab data (KPI summary, service breakdown, daily trend, savings opportunities).
Query Parameters
report_id (UUID) — Report to analyze
Response
total_cost — Sum of all cost
row_count — Total line items
service_breakdown — Top services by cost
daily_trend — Cost trend chart data
savings_opportunities — Cost optimization recommendations
GET /dashboard/tab/accounts
Accounts tab data (account and org unit breakdown).
Query Parameters
report_id (UUID) — Report to analyze
Response
account_breakdown — Per-account cost distribution
org_unit_breakdown — Per-org-unit cost (if available)
GET /dashboard/tab/environments
Environments tab data (from Environment tag or enrichment).
Query Parameters
report_id (UUID) — Report to analyze
Response
environment_breakdown — prod, staging, dev costs
env_month_breakdown — Per-environment monthly trend
env_category_breakdown — Per-environment service mix
GET /dashboard/tab/services
Services tab data (service category breakdown and top resources).
Query Parameters
report_id (UUID) — Report to analyze
Response
service_category_breakdown — All services sorted by cost
top_resources — Top 20 resources by cost
GET /dashboard/tab/tags
Tags tab data (all tag breakdowns including managed-by and native team tags).
Query Parameters
report_id (UUID) — Report to analyze
Response
tag_product_breakdown — Product tag breakdown
tag_team_breakdown — Managed By tag breakdown
tag_team_native_breakdown — Native team tag if available
tag_customer_breakdown — Customer tag breakdown
tag_costcentre_breakdown — Cost Centre tag breakdown
untagged_resources — Cost of resources missing tags
GET /dashboard/tab/trends
Trends tab data (pricing term, month-over-month comparison, region breakdown).
Query Parameters
report_id (UUID) — Report to analyze
Response
pricing_term_breakdown — On-Demand vs Reserved vs Spot
mom_comparison — Month-over-month cost trend
region_breakdown — Per-region cost distribution

HTTP Status Codes

  • 200 OK — Request succeeded
  • 202 Accepted — Async job accepted (upload, processing) — use job_id to poll status
  • 400 Bad Request — Invalid parameters or file format
  • 401 Unauthorized — Missing or invalid X-API-Key header
  • 404 Not Found — Resource not found (report, job)
  • 413 Payload Too Large — File exceeds 2GB limit
  • 500 Internal Server Error — Unexpected server error