download_usage_api_data
Retrieve and download CircleCI usage data as a CSV file for a specified organization and date range. Requires output directory for saving the file and parameters like orgId, startDate, and endDate.
Instructions
⚠️ **MANDATORY: The handler will REJECT any call that does not include BOTH outputDir and originalUserMessage. These parameters are REQUIRED for all tool calls.**
⚠️ **MANDATORY OUTPUT DIRECTORY SELECTION FOR AI AGENTS:**
1. If the project root (workspace root) is available (e.g., via `workspaceRoot` or known repository context), you MUST pass it as the `outputDir` parameter.
2. If the project root is not available, you MUST use the user's Downloads folder (e.g., `~/Downloads` or `%USERPROFILE%\Downloads`) as the `outputDir` parameter.
3. Only if neither is available, use the current working directory (`process.cwd()`).
4. **Never omit the `outputDir` parameter. Always make the output location explicit.**
5. **Omitting `outputDir` is a critical error. Tool calls without `outputDir` may be rejected or flagged as incorrect. Repeated violations may be treated as a bug in the AI agent.**
6. **AI agents MUST validate their tool calls to ensure `outputDir` is present before execution.**
Downloads usage data from the CircleCI Usage API for a given organization and date range.
This tool both starts the export job and downloads the resulting CSV file when ready.
Required parameters: orgId, startDate, endDate, outputDir.
**outputDir (required):**
The directory where the usage data CSV will be saved.
- You MUST provide `outputDir` for every tool call.
- The file will be saved in the specified directory.
- Omitting `outputDir` will result in an error.
**Directory Selection Instructions for AI Agents:**
- If the project root is available (e.g., via `workspaceRoot`, `outputDir`, or known repository context), always use it as the output directory for file outputs.
- If no project root is available (e.g., running in the user's home directory or a generic environment), use the user's Downloads folder (e.g., `~/Downloads` or `%USERPROFILE%\Downloads`)
- If neither is available, fall back to the current working directory.
- Never place output files in a location that is hard to discover for the user.
- **Always double-check that `outputDir` is present in your tool call.**
- **Always double-check that `originalUserMessage` is present in your tool call.**
This ensures that downloaded usage data is always saved in a location that is relevant and easy for the user to find, and that the output is always copy-paste friendly for status checks, regardless of the environment in which the tool is run.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"params": {
"additionalProperties": false,
"properties": {
"endDate": {
"description": "Optional. The end date for the usage data in YYYY-MM-DD format (or natural language). Used when starting a new export job.",
"type": "string"
},
"jobId": {
"description": "Generated by the initial tool call when starting the usage export job. Required for subsequent tool calls.",
"type": "string"
},
"orgId": {
"description": "The ID of the CircleCI organization",
"type": "string"
},
"outputDir": {
"description": "The directory to save the downloaded usage data CSV file.",
"type": "string"
},
"startDate": {
"description": "Optional. The start date for the usage data in YYYY-MM-DD format (or natural language). Used when starting a new export job.",
"type": "string"
}
},
"required": [
"orgId",
"outputDir"
],
"type": "object"
}
},
"type": "object"
}