How-To Query Billing Costs API With Required Parameters

Last Updated: Jan 15, 2026

Introduction

This guide explains how to query the Crusoe Cloud Billing Costs API endpoint to retrieve your organisation's cost data. It covers the necessary parameters and required authentication to successfully make requests.

Prerequisites

• Crusoe Cloud API Access Key and Secret Key
• Your organisation’s UUID (Organisation ID)
• Basic knowledge of making HTTP requests (e.g., with Python, Postman)

Step-by-Step Instructions

Step 1:  Confirm API Endpoint and Version

• Use the following base URL and API version:

  https://api.crusoecloud.com/v1alpha5

• The billing costs path is: (Replace {organization_id} with your organisation’s UUID.)

  /organizations/{organization_id}/billing/costs

Step 2:  Define Required and Optional Query Parameters

The billing costs endpoint requires the following query parameters:

• start_date (required): Start date of billing data in YYYY-MM-DD format. 
  Example: start_date="2022-07-01"
• end_date (required): End date of billing data in YYYY-MM-DD format.
  Example: end_date="2023-08-08"

Optional filters include:

• projects (array of project IDs)
  Example: projects=d8f5fd-dd86-4-8f01-643e6d0f15bb
• resources (array of resource IDs)
  Example: resources=d8f5fd-dd86-4-8f01-643e6d0f15bb
• resource_types (array of resource type strings)
  Example: resource_types=persistent-ssd,a40.1x
• regions (array of region strings)
  Example: regions=us-east1,us-northcentral1
• format (json or csv)
  Example: format="json","csv"

Step 3: Prepare the Signature Payload

The signature payload is composed of:

• HTTP path (including version and endpoint)
• Canonicalized query parameters, sorted lexicographically and joined with & (or a single newline \n if empty)
• HTTP verb (GET)
• Timestamp in RFC3339 format (e.g., 2025-09-18T10:53:00Z)
• Example payload:

• /v1alpha5/organizations/<organization_id>/billing/costs
  end_date=2025-08-20&start_date=2025-08-01
  GET
  2025-09-18T10:53:00Z

Step 4:  Generate the HMAC Signature

• Decode your base64 secret key (URL-safe base64 with padding adjusted)
• Use SHA256 HMAC with decoded secret on the payload string
• Encode the result as URL-safe base64, stripping trailing equals =

Step 5:  Construct a Request Headers

• X-Crusoe-Timestamp: Use the same timestamp as in the payload

• Authorization: Format as

  Bearer 1.0:<access_key_id>:<base64_encoded_signature>

Step 6:  Make the GET Request

Include query parameters and headers in your HTTP GET request. Example full URL:

• https://api.crusoecloud.com/v1alpha5/organizations/<organization_id>/billing/costs?start_date=2025-08-01&end_date=2025-08-20

Step 7:  Handle the API Response

• 200 OK indicates successful retrieval of billing data.

Possible errors with corresponding HTTP status codes:

• 400 Bad Request (missing or invalid parameters)
• 401 Authentication Failed
• 403 Permissions Denied
• 500 Internal Server Error

Python Sample Code for Querying Billing Costs API

import hmac
import hashlib
import base64
import datetime
import requests
import urllib.parse
import json

api_access_key = "<ACCESS_KEY>"
api_secret_key = "<SECRET_KEY>"
organization_id = "<ORG_ID>"

api_version = "/v1alpha5"
request_path = f"/organizations/{organization_id}/billing/costs"
request_verb = "GET"

# Query parameters - required start_date and end_date
params = {
    "start_date": "2025-08-01",
    "end_date": "2025-08-20"
}

# Canonicalize sorted query parameters
sorted_params = sorted(params.items())
query_params_str = urllib.parse.urlencode(sorted_params, doseq=True)

# Timestamp in RFC3339 format UTC
timestamp = datetime.datetime.utcnow().replace(microsecond=0).isoformat() + "Z"

# Signature payload as per API spec
signature_payload = f"{api_version}{request_path}\n{query_params_str}\n{request_verb}\n{timestamp}\n"

# Decode secret key and generate HMAC-SHA256 signature (base64 URL-safe)
decoded_secret = base64.urlsafe_b64decode(api_secret_key + '=' * (-len(api_secret_key) % 4))
signature = base64.urlsafe_b64encode(
    hmac.new(decoded_secret, signature_payload.encode("utf-8"), hashlib.sha256).digest()
).decode("utf-8").rstrip("=")

# Request headers
headers = {
    "X-Crusoe-Timestamp": timestamp,
    "Authorization": f"Bearer 1.0:{api_access_key}:{signature}",
    "Accept": "application/json"
}

# Perform GET request
response = requests.get(f"https://api.crusoecloud.com{api_version}{request_path}", headers=headers, params=params)

# Output results
print(f"Status: {response.status_code}")
try:
    print(json.dumps(response.json(), indent=4))
except Exception:
    print(response.text)

Troubleshooting

Issue: 400 Bad Request When Querying Billing Costs API Without start_date Parameter

Problem: When querying the /organizations/{organization_id}/billing/costs endpoint without including the required start_date query parameter, the API returns a 400 Bad Request error. This is because the start_date parameter is mandatory.

Error Message Example:

{
 "code": "bad_request",
 "message": "bad request, check request parameters. failure when calling Billing Costs API: failed to parse request arguments: start date must be after May 1, 2025",
 "error_id": "<error_id>"
}

Cause:
The API requires the start_date parameter specifying the beginning date of the billing data query end_date parameter should also be provided.

Resolution:

Always include the start_date and the  end_date Include a query parameter in your request with a valid date in YYYY-MM-DD format.

Additional Resources

• Crusoe API Reference
• Billing API References