Resolving "Malformed request body" Error in CircleCI Usage Export API

Overview:

When making API calls to CircleCI's Usage Export endpoint and receiving a "Malformed request body" error, the issue is typically related to date formatting in your request. This article explains how to properly format date parameters in the Usage Export API to avoid this error. The API requires dates in ISO 8601 format with timezone information, even though the specific time values don't affect the usage data returned.

Understanding and Fixing the Date Format Error:

• The CircleCI Usage Export API requires dates to be in ISO 8601 format with timezone information (YYYY-MM-DDThh:mm:ssZ), not just the date portion (YYYY-MM-DD)

While the API returns full-day data regardless of time values, the complete timestamp format is still required

Example of incorrect format that will fail:

curl -X POST "https://circleci.com/api/v2/organizations/ORG_ID/usage_export_job" \ -H "Circle-Token: CIRCLE_TOKEN" \ -H "Content-Type: application/json" \ -d {
  "start": "2025-01-01",
  "end": "2025-01-31",
  "shared_org_ids": ["ORG_ID"]
}

Example of correct format that will work:

curl -X POST "https://circleci.com/api/v2/organizations/ORG_ID/usage_export_job" \ -H "Circle-Token: CIRCLE_TOKEN" \ -H "Content-Type: application/json" \ -d {
  "start": "2025-01-01T00:00:00Z",
  "end": "2025-01-31T23:59:59Z",
  "shared_org_ids": ["ORG_ID"]
}

Additional Notes:

• The Z at the end of the timestamp represents UTC timezone (Zulu time)
• Any valid time can be used (e.g., T12:00:00Z) as the API will return the full day's data regardless
• Ensure other required headers (Circle-Token and Content-Type) are properly included in your request

Additional Resources:

• CircleCI API v2 Documentation
• ISO 8601 Date Format Explanation