Doit MCP API

DoiT API Code Generator

Generate correct DoiT Platform API calls for cost analytics. Use this skill to produce production-ready code when developers need to integrate DoiT cost analytics into their applications.

Tool Selection

Use MCP tools as the primary interface for all DoiT API operations. Only generate API code when the developer explicitly needs it for integration into their own applications.

Ava Fallback (Ask Ava)

If an MCP tool call fails, returns an error, returns empty/unexpected results, or does not answer the user's question, fall back to Ava — DoiT's AI assistant that can answer any cloud cost question.

Ava can be reached via both the DCI CLI and MCP. Prefer the DCI CLI (dci ask-ava-sync) because it returns cleaner JSON output. Before calling Ava, check if the DCI CLI is installed by running command -v dci. If it is not installed, you MUST ask the user if they want to install it: "To get a better answer, I can ask Ava (DoiT's AI assistant). The recommended way is via the DCI CLI. Would you like to install it? (brew install doitintl/dci-cli/dci)". If the user agrees, invoke the doit-mcp-setup skill to install and authenticate the DCI CLI, then call Ava. If the user declines, fall back to the MCP Ava tool instead.

When to use Ava fallback:

• An MCP tool call fails or times out
• Query results are empty and you cannot determine why
• The user's question is about DoiT API behavior, field meanings, or best practices that structured tools cannot answer
• You need contextual or explanatory information that the API reference alone does not cover

How to call Ava:

dci ask-ava-sync ephemeral: true, question: "<rephrase the user's question or describe what you need>" --output json

• Always set ephemeral: true to avoid persisting throwaway conversations.
• Rephrase the question to include relevant context (e.g., endpoint, error message, dimension ID) from earlier steps.
• Parse the answer field from the JSON response and present it to the user.

When to Use

Activate this skill when a developer:

• Asks how to call the DoiT API
• Needs to build a cost analysis query
• Wants to list, filter, or retrieve reports
• Needs to query dimensions, anomalies, or incidents
• Is debugging a DoiT API call
• Wants code examples in any language

Quick Reference

Dimension Mappings

Map natural language to dimension IDs:

Cloud Provider Filter Values

Time Range Mappings

Metric Types

Time Interval Mappings

Control data aggregation granularity:

Note: Omitting timeInterval defaults to daily breakdown. For time ranges > 7 days, specify timeInterval to avoid hundreds of rows.

Parameter Reference

Common optional parameters:

customerId Usage:

• Omit: Query returns data for all accessible customers
• Include: Query returns data for specific customer only (e.g., 'KzDE3pXU4KeQ3b53ciDN')

Filter Combination Logic

Understanding how filters combine:

Example:

// Get costs for (AWS OR GCP) AND us-east-1 AND NOT test environment
filters: [
  {
    id: 'cloud_provider',
    type: 'fixed',
    inverse: false,
    values: ['amazon-web-services', 'google-cloud']  // AWS OR GCP
  },
  {
    id: 'region',
    type: 'fixed',
    inverse: false,
    values: ['us-east-1']  // AND us-east-1
  },
  {
    id: 'attribution_group',
    type: 'attribution',
    inverse: true,
    values: ['test']  // AND NOT test
  }
]

MCP Tool Mapping

When using the DoiT MCP server instead of direct HTTP calls:

Generic MCP Client Usage

// Generic MCP client interface (works with any MCP implementation)
interface MCPClient {
  callTool(request: { name: string; arguments: Record<string, any> }): Promise<any>;
}

// Example: Run query via MCP
const result = await mcpClient.callTool({
  name: 'run_query',
  arguments: {
    config: {
      dataSource: 'billing',
      metric: { type: 'basic', value: 'cost' },
      timeRange: { mode: 'last', amount: 1, unit: 'month', includeCurrent: false },
      timeInterval: 'month'
    }
  }
});

Basic Query Structure

Response Schema

Query results automatically include these columns alongside your grouped dimensions:

Note: Results include a ∑ Other aggregated row when the limit value is exceeded.

// Example 1: Monthly aggregation (recommended for cost analysis)
const monthlyQuery = {
  config: {
    dataSource: 'billing',
    metric: { type: 'basic', value: 'cost' },
    timeRange: { mode: 'last', amount: 1, unit: 'month', includeCurrent: false },
    timeInterval: 'month',  // Aggregate by month (returns ~6 rows per service)
    group: [{
      id: 'service_description',
      type: 'fixed',
      limit: { metric: { type: 'basic', value: 'cost' }, sort: 'desc', value: 25 }
    }]
  }
};

// Example 2: Daily breakdown (default behavior)
const dailyQuery = {
  config: {
    dataSource: 'billing',
    metric: { type: 'basic', value: 'cost' },
    timeRange: { mode: 'last', amount: 30, unit: 'day', includeCurrent: false },
    // No timeInterval = daily rows (returns ~750 rows for 30 days)
    group: [{
      id: 'service_description',
      type: 'fixed',
      limit: { metric: { type: 'basic', value: 'cost' }, sort: 'desc', value: 25 }
    }]
  }
};

[!IMPORTANT] Always verify dimension IDs with list_dimensions before using them in queries to prevent 400 Bad Request errors.

[!WARNING] Omitting timeInterval returns daily data by default, which can produce hundreds of rows. For cost analysis over weeks or months, always specify timeInterval: 'month' or 'week' to aggregate results.

Additional Resources

Reference Files

For detailed specifications and patterns, consult:

• references/api-reference.md — Full endpoint specifications, request/response schemas, validation rules
• references/code-examples.md — Complete TypeScript, Python, Go, and cURL examples
• references/troubleshooting.md — Error handling, HTTP status codes, common scenarios
  • Report Comparison Workflow — Step-by-step guide for matching query results with saved reports

Example Files

Working examples in examples/ that can be copied and adapted:

• examples/query-costs-by-service.ts — TypeScript example
• examples/query-costs-by-service.py — Python example
• examples/query-costs-by-service.sh — Bash/cURL example