AI Endpoints¶

The AI API provides machine-learning-powered features including PDF extraction, bill analysis, tariff source discovery, and intelligent rate comparisons. All endpoints require authentication and are prefixed with /ai.

Processing Time

AI endpoints involve LLM inference and may take 5-30 seconds to respond depending on document complexity. Plan for longer timeouts in your client code.

POST /ai/extract¶

Upload a utility rate schedule PDF and extract structured tariff data using AI. The system uses OCR and language models to parse rate tables, TOU periods, demand charges, and riders.


Auth required	Yes
Content-Type	`multipart/form-data`

Request Body (Form Data)¶

Field	Type	Required	Description
`file`	file	Yes	PDF of the rate schedule (max 20 MB)

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/ai/extract \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/rate_schedule.pdf"

Example Response¶

200 OK

{
  "extraction_id": "ext_a1b2c3",
  "utility_name": "Pacific Gas & Electric",
  "tariff_name": "B-19 Medium General Demand-Metered TOU",
  "sector": "commercial",
  "rate_type": "tou",
  "effective_date": "2026-03-01",
  "energy_rates": [
    {
      "period": "summer_on_peak",
      "rate_per_kwh": 0.25120,
      "hours": "12:00-18:00",
      "months": [6, 7, 8, 9]
    },
    {
      "period": "summer_off_peak",
      "rate_per_kwh": 0.12450,
      "hours": "18:00-12:00",
      "months": [6, 7, 8, 9]
    },
    {
      "period": "winter_mid_peak",
      "rate_per_kwh": 0.15230,
      "hours": "08:00-21:00",
      "months": [1, 2, 3, 4, 5, 10, 11, 12]
    },
    {
      "period": "winter_off_peak",
      "rate_per_kwh": 0.10100,
      "hours": "21:00-08:00",
      "months": [1, 2, 3, 4, 5, 10, 11, 12]
    }
  ],
  "demand_rates": [
    {
      "period": "summer",
      "type": "max",
      "rate_per_kw": 19.84
    },
    {
      "period": "winter",
      "type": "max",
      "rate_per_kw": 10.25
    }
  ],
  "fixed_charges": [
    {
      "name": "Service Charge",
      "amount": 82.50,
      "frequency": "monthly"
    }
  ],
  "confidence": 0.91,
  "warnings": [
    "Rider charges on page 4 could not be fully parsed"
  ],
  "pages_processed": 6
}

Review Extracted Data

Always review AI-extracted tariff data before using it for billing calculations. Check the confidence score and warnings array for potential issues.

Error Cases¶

Status	Detail	Cause
`400`	`"File must be a PDF"`	Non-PDF file uploaded
`400`	`"File too large (max 20 MB)"`	File exceeds size limit
`422`	`"Could not extract rate data from PDF"`	AI extraction failed completely
`500`	`"AI service temporarily unavailable"`	LLM backend error

POST /ai/analyze-bill¶

Upload a utility bill PDF and receive an AI-powered analysis including cost breakdown, anomaly detection, and optimization suggestions.


Auth required	Yes
Content-Type	`multipart/form-data`

Request Body (Form Data)¶

Field	Type	Required	Description
`file`	file	Yes	PDF of the utility bill (max 10 MB)
`property_id`	string	No	Property ID for contextual analysis (compares against historical bills)

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/ai/analyze-bill \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/bill.pdf" \
  -F "property_id=prop_abc123"

Example Response¶

200 OK

{
  "analysis_id": "ana_x1y2z3",
  "extracted_data": {
    "utility_name": "Southern California Edison",
    "account_number": "3-042-1567-89",
    "billing_period_start": "2026-02-03",
    "billing_period_end": "2026-03-04",
    "total_amount": 3412.67,
    "total_usage_kwh": 17050,
    "peak_demand_kw": 51.2
  },
  "cost_breakdown": {
    "energy_charge": 2558.00,
    "demand_charge": 512.00,
    "fixed_charge": 125.00,
    "taxes_and_fees": 217.67
  },
  "anomalies": [
    {
      "type": "usage_spike",
      "severity": "medium",
      "message": "Usage is 12% higher than the 6-month average for this property.",
      "expected_kwh": 15200,
      "actual_kwh": 17050
    }
  ],
  "suggestions": [
    {
      "type": "rate_optimization",
      "message": "Switching to SCE TOU-GS-3 could save approximately $300/month based on your usage profile.",
      "estimated_monthly_savings": 300.00
    },
    {
      "type": "demand_management",
      "message": "Your peak demand of 51.2 kW occurred at 3:15 PM. Shifting 5 kW of load to off-peak hours could reduce demand charges by $115/month."
    }
  ],
  "confidence": 0.95
}

Contextual Analysis

Providing property_id enables historical comparison and more detailed anomaly detection. Without it, the analysis is based solely on the uploaded bill.

Error Cases¶

Status	Detail	Cause
`400`	`"File must be a PDF"`	Non-PDF file
`400`	`"File too large (max 10 MB)"`	File exceeds limit
`404`	`"Property not found"`	Invalid `property_id`
`422`	`"Could not analyze bill PDF"`	AI analysis failed

POST /ai/find-sources¶

Find official tariff data sources (rate schedule URLs, regulatory filings) for a utility. Useful for verifying tariff data or discovering new rate schedules.


Auth required	Yes

Request Body¶

Field	Type	Required	Description
`utility_name`	string	Yes	Name of the utility company
`state`	string	No	Two-letter state code to narrow the search
`tariff_name`	string	No	Specific tariff name to search for

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/ai/find-sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "utility_name": "Pacific Gas & Electric",
    "state": "CA",
    "tariff_name": "B-19"
  }'

Example Response¶

200 OK

{
  "utility_name": "Pacific Gas & Electric",
  "sources": [
    {
      "type": "tariff_book",
      "title": "PG&E Electric Schedule B-19",
      "url": "https://www.pge.com/tariffs/assets/pdf/tariffbook/ELEC_SCHEDS_B-19.pdf",
      "description": "Official rate schedule for B-19 Medium General Demand-Metered TOU service.",
      "last_verified": "2026-03-20"
    },
    {
      "type": "regulatory_filing",
      "title": "CPUC Rate Case A.21-06-021",
      "url": "https://apps.cpuc.ca.gov/apex/f?p=401:56:0::NO",
      "description": "General rate case filing containing B-19 rate adjustments effective 2026.",
      "last_verified": "2026-03-18"
    },
    {
      "type": "rate_comparison",
      "title": "PG&E Rate Comparison Tool",
      "url": "https://www.pge.com/en/account/rate-plans/find-your-best-rate-plan.html",
      "description": "Official PG&E tool for comparing available rate plans.",
      "last_verified": "2026-03-15"
    }
  ],
  "confidence": 0.88,
  "notes": "Sources verified via web search. Regulatory filing link may require CPUC account access."
}

Error Cases¶

Status	Detail	Cause
`422`	`"field required"`	Missing `utility_name`
`404`	`"No sources found for this utility"`	No matching sources discovered

POST /ai/compare-analysis¶

Get an AI-generated natural language analysis comparing multiple tariff options for a specific usage profile. Goes beyond raw numbers to explain trade-offs, seasonal impacts, and risk factors.


Auth required	Yes

Request Body¶

Field	Type	Required	Description
`tariff_ids`	array	Yes	Array of tariff IDs to compare (2-5)
`usage_kwh`	number	Yes	Monthly usage in kWh
`demand_kw`	number	No	Peak demand in kW
`property_type`	string	No	`residential`, `commercial`, `industrial`
`has_solar`	boolean	No	Whether the property has solar
`solar_capacity_kw`	number	No	Solar system size in kW

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/ai/compare-analysis \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tariff_ids": ["trf_sce_tou_gs2", "trf_sce_tou_gs3"],
    "usage_kwh": 16200,
    "demand_kw": 48.5,
    "property_type": "commercial",
    "has_solar": false
  }'

Example Response¶

200 OK

{
  "analysis_id": "cmp_r1s2t3",
  "tariffs_compared": [
    {
      "id": "trf_sce_tou_gs2",
      "name": "SCE TOU-GS-2",
      "estimated_monthly_cost": 4287.34
    },
    {
      "id": "trf_sce_tou_gs3",
      "name": "SCE TOU-GS-3",
      "estimated_monthly_cost": 3890.12
    }
  ],
  "recommendation": "trf_sce_tou_gs3",
  "analysis": "Based on your usage profile of 16,200 kWh/month with 48.5 kW peak demand, **SCE TOU-GS-3 is the better choice**, saving approximately **$397/month ($4,766/year)** compared to TOU-GS-2.\n\n**Key factors:**\n\n1. **Demand charges**: TOU-GS-3 has lower facility demand rates ($16.80/kW vs $18.42/kW), which matters significantly at your demand level.\n\n2. **Energy rates**: TOU-GS-3 on-peak rates are slightly higher ($0.2912 vs $0.2845), but mid-peak and off-peak rates are lower, resulting in net savings given your usage distribution.\n\n3. **Seasonal risk**: Summer bills under both tariffs will be 30-40% higher than winter. TOU-GS-3 provides more insulation against summer spikes due to its lower demand structure.\n\n**Caveat**: TOU-GS-3 requires a minimum demand of 20 kW. If your demand drops below this threshold during mild months, you may need to switch back to TOU-GS-2.",
  "seasonal_comparison": {
    "summer_monthly": {
      "trf_sce_tou_gs2": 5150.00,
      "trf_sce_tou_gs3": 4680.00
    },
    "winter_monthly": {
      "trf_sce_tou_gs2": 3425.00,
      "trf_sce_tou_gs3": 3100.00
    }
  }
}

Error Cases¶

Status	Detail	Cause
`422`	`"tariff_ids must contain 2 to 5 items"`	Wrong number of tariffs
`404`	`"Tariff not found: trf_xxx"`	Invalid tariff ID
`500`	`"AI service temporarily unavailable"`	LLM backend error