PowerMeterAPI Enterprise Carbon Tracking

PowerMeterAPI – Developer Documentation

Track energy consumption, generate carbon receipts, and automate compliance reporting

Manage API Keys

Welcome to PowerMeterAPI – Developer Documentation

This API lets you track energy consumption, generate carbon receipts, and automate compliance reporting.

To get started:

  1. Log in to your dashboard and generate an API key in Settings.
  2. Authenticate your API requests using the key in the Authorization: Bearer <YOUR_API_KEY> header.
  3. Submit energy usage data, generate receipts, and retrieve compliance reports.
For full onboarding, view the Quickstart Guide.
For help, contact support.

All responses are JSON. Rate limits and error codes are listed below.

API Overview

REST API
JSON-based HTTP endpoints
Bearer Auth
API key authentication
Rate Limited
1,000 calls/day (dev tier)

Base URL

https://app.powermeterapi.dev/

Authentication

All API requests require authentication using API keys generated from your account.

Authorization Header

Authorization: Bearer your_api_key_here

Energy Reporting

Submit energy usage data and receive carbon tracking receipts

POST /v1/report

Report energy usage for a single compute job and receive a carbon tracking receipt

Request Body

{
  "job_id": "ml-training-001",
  "duration_minutes": 120,
  "cpu_cores": 8,
  "memory_gb": 32,
  "gpu_cores": 2,
  "geo_iso": "US"
}

Response

{
  "status": "success",
  "data": {
    "job_id": "ml-training-001",
    "kwh": 2.45,
    "co2_grams": 1102.5,
    "receipt_id": "rcpt_abc123def"
  }
}
Python Example 
import requests

api_key = "pm_live_your_api_key_here"
base_url = "https://app.powermeterapi.dev/"

response = requests.post(
    f"{base_url}v1/report",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "job_id": "ml-training-001",
        "duration_minutes": 120,
        "cpu_cores": 8,
        "memory_gb": 32,
        "gpu_cores": 2,
        "geo_iso": "US"
    }
)

data = response.json()
print(f"Receipt ID: {data['data']['receipt_id']}")
print(f"Energy: {data['data']['kwh']} kWh")
print(f"CO2: {data['data']['co2_grams']} grams")
cURL Example 
curl -X POST "https://app.powermeterapi.dev/v1/report" \
  -H "Authorization: Bearer pm_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "ml-training-001",
    "duration_minutes": 120,
    "cpu_cores": 8,
    "memory_gb": 32,
    "gpu_cores": 2,
    "geo_iso": "US"
  }'

POST /v1/batch

Report energy usage for multiple jobs (up to 10,000) in a single request

Request Body

{
  "jobs": [
    {
      "job_id": "job-001",
      "duration_minutes": 60,
      "cpu_cores": 4,
      "memory_gb": 16,
      "geo_iso": "US"
    },
    {
      "job_id": "job-002",
      "duration_minutes": 90,
      "cpu_cores": 8,
      "gpu_cores": 1,
      "geo_iso": "EU"
    }
  ]
}

Response

{
  "status": "success",
  "data": {
    "total_jobs": 2,
    "total_kwh": 1.82,
    "total_co2_grams": 819.0,
    "jobs": [
      {
        "job_id": "job-001",
        "kwh": 0.72,
        "receipt_id": "rcpt_def456"
      },
      {
        "job_id": "job-002", 
        "kwh": 1.10,
        "receipt_id": "rcpt_ghi789"
      }
    ]
  }
}
Python Example 
import requests

api_key = "pm_live_your_api_key_here"

jobs_data = [
    {"job_id": "job-001", "duration_minutes": 60, "cpu_cores": 4, "geo_iso": "US"},
    {"job_id": "job-002", "duration_minutes": 90, "cpu_cores": 8, "gpu_cores": 1, "geo_iso": "EU"}
]

response = requests.post(
    "https://app.powermeterapi.dev/v1/batch",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"jobs": jobs_data}
)

data = response.json()
print(f"Total energy: {data['data']['total_kwh']} kWh")
print(f"Jobs processed: {data['data']['total_jobs']}")

Data Retrieval

Access your carbon receipts, audit logs, and usage statistics

GET /v1/receipts

Retrieve your carbon tracking receipts with optional filtering

Query Parameters

  • limit - Number of receipts (default: 50, max: 1000)
  • offset - Pagination offset (default: 0)
  • job_id - Filter by specific job ID

Response

{
  "status": "success",
  "data": {
    "receipts": [
      {
        "receipt_id": "rcpt_abc123def",
        "job_id": "ml-training-001",
        "kwh": 2.45,
        "co2_grams": 1102.5,
        "timestamp": "2024-06-27T14:30:00Z"
      }
    ],
    "total": 1,
    "has_more": false
  }
}
Python Example 
import requests

api_key = "pm_live_your_api_key_here"

# Get recent receipts
response = requests.get(
    "https://app.powermeterapi.dev/v1/receipts?limit=10",
    headers={"Authorization": f"Bearer {api_key}"}
)

data = response.json()
for receipt in data['data']['receipts']:
    print(f"Job: {receipt['job_id']} - {receipt['kwh']} kWh")
cURL Example 
curl -X GET "https://app.powermeterapi.dev/v1/receipts?limit=10" \
  -H "Authorization: Bearer pm_live_your_api_key_here"

GET /v1/api-keys/stats

Get usage statistics and limits for your API keys

No Parameters Required

Returns current usage stats for the authenticated user

Response

{
  "status": "success",
  "data": {
    "daily_api_calls": 45,
    "daily_limit": 1000,
    "remaining_calls": 955,
    "daily_usage_kwh": 12.34,
    "active_keys": 2
  }
}
Python Example 
import requests

api_key = "pm_live_your_api_key_here"

response = requests.get(
    "https://app.powermeterapi.dev/v1/api-keys/stats",
    headers={"Authorization": f"Bearer {api_key}"}
)

stats = response.json()['data']
print(f"API calls today: {stats['daily_api_calls']}/{stats['daily_limit']}")
print(f"Energy tracked: {stats['daily_usage_kwh']} kWh")

Audit & Compliance

Access audit trails and compliance reports

GET /v1/audit/logs

Retrieve tamper-proof audit logs for compliance reporting

Query Parameters

  • action_type - Filter by action (VIEW, EDIT, DOWNLOAD)
  • receipt_id - Filter by receipt ID
  • limit - Number of entries (default: 100)

Response

{
  "status": "success",
  "data": {
    "logs": [
      {
        "id": "audit_12345",
        "action_type": "VIEW",
        "receipt_id": "rcpt_abc123",
        "timestamp": "2024-06-27T14:30:00Z",
        "signature": "sha256_hash",
        "verified": true
      }
    ],
    "total": 1
  }
}
Python Example 
import requests

api_key = "pm_live_your_api_key_here"

response = requests.get(
    "https://app.powermeterapi.dev/v1/audit/logs?action_type=VIEW&limit=50",
    headers={"Authorization": f"Bearer {api_key}"}
)

logs = response.json()['data']['logs']
for log in logs:
    print(f"{log['timestamp']}: {log['action_type']} on {log['receipt_id']}")

HTTP Response Codes & Error Handling

Comprehensive list of API response codes and their meanings

Success Codes

200
OK
Request successful. Data returned in response body.
201
Created
Resource created successfully (e.g., API key generation).

Client Error Codes

400
Bad Request
Invalid request format, missing required fields, or malformed JSON.
401
Unauthorized
Missing, invalid, or expired API key. Check your Authorization header.
403
Forbidden
Valid API key but insufficient permissions for this resource.
404
Not Found
Requested resource (receipt, job, etc.) does not exist.
422
Unprocessable Entity
Valid JSON but failed validation (e.g., negative values, invalid geo_iso).
429
Rate Limited
Daily API call limit (1,000/day) or usage cap (50 kWh/day) exceeded.

Server Error Codes

500
Internal Server Error
Unexpected server error. Contact support if persistent.
503
Service Unavailable
API temporarily unavailable for maintenance.

Error Response Format

All error responses follow this standardized JSON format:

{
  "detail": "Descriptive error message",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "timestamp": "2024-06-27T14:30:00Z"
}

Rate Limits & Usage Caps

API Call Limits

  • • Dev Tier: 1,000 calls/day
  • • Resets daily at 00:00 UTC
  • • Check remaining with /v1/api-keys/stats

Usage Caps

  • • Dev Tier: 50 kWh/day maximum
  • • Prevents unexpected billing charges
  • • Upgrade plan for higher limits