API Documentation

POST https://ecoaitracker.com/api/v1/calculate

Records AI inference usage details and returns calculated energy consumption (Wh) and ecological footprint (CO2 emissions).

1 Headers Required

ContentType:application/json
Authorization:Bearer <YOUR_API_KEY>

2 Request Payload (JSON)

{
  "provider": "Google",
  "model": "gemini-3-pro",
  "prompt_tokens": 788,
  "completion_tokens": 312,
  "reasoning_tokens": 0,
  "cached_tokens": 0,
  "startTimeMs": 1710000000000,
  "firstTokenTimeMs": 1710000010000,
  "source": "dom_estimated",
  "is_estimated": true,
  "estimation_method": "dom_gpt_tokenizer_v1"
}

3 Accepted Parameters

Parameter	Type	Required	Description
provider	string	Yes	Cloud or model provider name (e.g. "Google", "OpenAI").
prompt_tokens	number	Yes	Number of tokens sent in the prompt.
completion_tokens	number	Yes	Number of generated output tokens.
model	string	Optional*	Exact model ID. Required unless system has a safe fallback.
detected_region	string	Optional	Datacenter region (e.g. "us-west-1"). Enables REGION_SPECIFIC accuracy.
reasoning_tokens	number	Optional	Explicit reasoning tokens directly from provider. Overrides estimation, setting evidence class to CLASS_A_DIRECT. (Default: 0)
cached_tokens	number	Optional	Number of read tokens from prompt cache. (Default: 0)

4Supported Models (Allowed values for model)

No models loaded.

5 Successful Response

{
  "energy_wh": 3.45,
  "co2_grams": 1.22,
  "tree_days": 0.005,
  "water_ml": 0.85,
  "estimated_reasoning_tokens": 450,
  "audit": {
    "calculationMethod": "EXACT_REGION",
    "finalRegion": "us-west-1",
    "finalProvider": "AWS",
    "evidenceClass": "CLASS_A_DIRECT",
    "isApiReasoning": true,
    "locationBasedCO2": 1.55,
    "marketBasedCO2": 1.22,
    "sourceUrl": "https://sustainability.aboutamazon.com/"
  },
  "message": "This request cost the equivalent of 0.0050 days of a tree's carbon absorption."
}

GET https://ecoaitracker.com/api/v1/history

Retrieves paginated history logs associated with all your API keys. Requires API History (Read) scope.

1 Query Parameters (Optional)

startDateISO 8601 string (e.g. 2025-01-01)
endDateISO 8601 string (e.g. 2025-12-31)
keyNameString – API Key Name from Dashboard
pageNumber – Default: 1
limitNumber – Default: 100, max: 100000

2 Successful Response

{
  "status": "success",
  "data": [
    {
      "id": "uuid",
      "logDate": "2025-05-10T12:00:00Z",
      "keyName": "Production Key",
      "maskedKey": "eco_...a1b2",
      "provider": "OpenAI",
      "model": "gpt-4o",
      "inputTokens": 100,
      "outputTokens": 200,
      "energyWh": 0.5,
      "co2Grams": 0.1
    }
  ],
  "pagination": {
    "totalElements": 4200,
    "totalPages": 42,
    "currentPage": 1,
    "limit": 100
  }
}

Audit-Ready ESG Compliance

Built on the GHG Protocol to ensure your AI infrastructure meets the strict reporting requirements of the CSRD directive.