AI Cost Audit & Anomaly Detection Actor

LLM cost audit · OpenAI · Anthropic · GPT · Claude · FinOps · token cost calculator · AI spend analytics

Audit, analyze, and optimize your AI and LLM usage costs from CSV or JSON in one run. Get token-based cost per model, anomaly detection, data quality and efficiency metrics, actionable optimization recommendations (often 20–40% savings), and optional webhook alerts — no external APIs, no LLM calls. Supports OpenAI, Anthropic, Groq, Google Gemini, and Azure OpenAI out of the box. v3.0 adds attribution, outcome linkage, n8n and OpenClaw integrations, idempotency, and enforcement simulation.

---

Why use this Actor?

You get	Benefit
Cost breakdown	By model, day, feature, workflow, node, tenant, environment
Anomaly detection	Dual-threshold spike detection; catch unusual spend without noise
Optimization engine	Rules-based recommendations with estimated savings (e.g. “Switch 15 calls to gpt-4o-mini”)
Data quality & efficiency	Quality score, token efficiency, cost per request
Attribution & outcomes	Cost per workflow/node/tenant; cost per outcome, outcomes per dollar
Alerts	Webhooks for anomalies and budget thresholds (Slack, Discord, etc.)
Integrations	n8n (workflow events) and OpenClaw (chat/agent tool)

---

How to use this Actor

1. Apify Console — Paste example input into the Input tab and run. Use a dataUrl to your CSV/JSON or provide rawData inline.
2. Apify API — Call the Actor via Apify API v2 (e.g. POST /acts/~actorId/runs) with the same input; read summary.json and the dataset from the run.
3. n8n — Use the Apify node and set inputType: "n8n" with your workflow events. See n8n integration and N8N_TESTING_GUIDE.md.
4. OpenClaw — Install the ai_cost_audit plugin and run cost audits from chat (e.g. “Audit AI costs from https://…”). See OpenClaw integration and docs/OPENCLAW_INTEGRATION.md.

---

Integrations: n8n and OpenClaw

n8n integration

Use the Actor inside n8n to audit LLM costs from your workflows. Send usage events (from HTTP Request, Webhook, or other nodes) into the Actor with inputType: "n8n". You get:

• Flexible field mapping — Map your n8n payload fields to the canonical event shape.
• Attribution — Cost by workflow, node, run, tenant, environment.
• Idempotency — Event deduplication; late events supported.
• Prompt hashing — Raw prompts never stored (SHA-256 only).

Quick n8n test: In the Apify node, set input to the N8N_TESTING_GUIDE.md#quick-start-minimal-test-input in N8N_TESTING_GUIDE.md.

OpenClaw integration

Run cost audits from OpenClaw (Slack, Telegram, or other channels). The ai_cost_audit tool runs this Actor via the Apify API and returns a short summary (total cost, anomalies, optimization hints).

Setup: Install the plugin from integrations/openclaw, set APIFY_TOKEN, and allow the ai_cost_audit tool for your agent. Then ask in chat: “Audit AI costs from https://…” or “Run a cost audit on our usage data.”

Full steps: docs/OPENCLAW_INTEGRATION.md.

---

What this Actor does

For each usage record, the Actor:

• Calculates input / output token costs
• Aggregates costs by:
  • model
  • day
  • feature
  • user (optional)
  • workflow, node, tenant, environment (v3 — optional)
• Detects anomalies and cost spikes (optional, v3: dual-threshold)
• Analyzes data quality with comprehensive metrics
• Calculates token efficiency (input/output ratio, cost per request, efficiency score)
• Links costs to outcomes (v3 — cost per outcome, outcomes per dollar)
• Identifies cost optimization opportunities with concrete, actionable recommendations
• Simulates enforcement actions (v3 — when thresholds exceeded)
• Deduplicates events (v3 — idempotency protection)
• Analyzes trends (last 7 vs previous 7 days) and projects monthly costs
• Sends webhook alerts for anomalies and budget thresholds (optional)
• Produces:
  • 📊 Dataset — detailed per-record costs (6 pre-configured views including Attribution)
  • 📄 summary.json — complete analysis with all metrics
  • 🔍 Data Quality Report — validation metrics & recommendations
  • ⚡ Token Efficiency Metrics — efficiency score & optimization insights
  • 💡 Cost Optimization Opportunities — rules-based recommendations with potential savings
  • 📈 Trend & Forecast — last 7 vs previous 7 days comparison and monthly projection
  • 🏷️ Attribution Breakdown (v3) — by workflow, node, tenant, environment
  • 📊 Outcome Efficiency (v3) — cost per outcome, outcomes per dollar
  • 🛡️ Enforcement Actions (v3) — simulated cost-control decisions
  • 📝 report.md — human-readable insights and recommendations

---

Typical use cases

• AI / LLM cost auditing — OpenAI, Anthropic, Claude, GPT spend analysis and token cost tracking
• FinOps & cost optimization — Identify savings with concrete recommendations and potential savings estimates
• n8n workflow cost tracking — Audit LLM usage from n8n workflows (input type n8n; see N8N_TESTING_GUIDE.md)
• OpenClaw / chat-driven audits — Run cost audits from Slack, Telegram, or other channels via the ai_cost_audit tool
• Anomaly detection — Dual-threshold spike detection; webhook alerts for unusual usage
• Cost attribution — By workflow, node, tenant, environment (multi-tenant and workflow ROI)
• Outcome-based ROI — Cost per outcome, outcomes per dollar (leads, conversions)
• Data quality & token efficiency — Quality score, efficiency metrics, optimization opportunities
• Trend & forecast — Last 7 vs previous 7 days; projected monthly cost
• Budget monitoring — Webhook alerts when spending exceeds thresholds
• Model comparison — Compare costs and efficiency across GPT, Claude, Gemini, and other models

---

Quick start (Apify Console)

Run the Actor in a few steps:

1. Open this Actor on Apify and go to the Input tab.
2. Choose input type: CSV (URL or raw), JSON array, or n8n (for n8n integration).
3. Provide usage data: either paste the Example input (JSON) below (works as-is) or set Data URL to your CSV/JSON and set Provider (OpenAI, Anthropic, etc.).
4. (Optional) Adjust price table, groupBy, anomaly detection, or v3 options (attribution, idempotency, enforcement).
5. Click Start and wait for the run to finish.

Where to find results:

Output	Location	Contents
Dataset	Actor run → Dataset	Per-record costs (6 views, including Attribution)
summary.json	Actor run → Key-Value Store	Full analysis: totals, byModel, byDay, anomalies, optimization, data quality, trend
report.md	Actor run → Key-Value Store	Human-readable report for stakeholders

Features:

• ✅ Multi-provider support (OpenAI, Anthropic, Groq, Gemini, Azure OpenAI, generic)
• ✅ Model-aware anomaly detection (v3: dual-threshold)
• ✅ Data quality analysis (success rate, field completeness, outliers)
• ✅ Token efficiency metrics (efficiency score, input/output ratio, cost per request)
• ✅ Cost optimization engine (rules-based recommendations with potential savings)
• ✅ Trend & forecast (last 7 vs previous 7 days, monthly projection)
• ✅ Attribution breakdown (v3 — workflow, node, tenant, environment)
• ✅ Outcome efficiency (v3 — cost per outcome, outcomes per dollar)
• ✅ Enforcement simulation (v3 — cost-control actions)
• ✅ Idempotency protection (v3 — event deduplication)
• ✅ Prompt security (v3 — SHA-256 hashing)
• ✅ Webhook alerts (anomalies and budget thresholds)
• ✅ No external API keys required

---

Input overview

Required

• Usage data (CSV or JSON)
• Provider (openai, anthropic, groq, gemini, azure-openai, generic)

Optional

• Price table (uses defaults if not provided)
• Grouping fields (model, day, feature, user, workflow, node, tenant, environment)
• Anomaly detection settings (v3: dual-threshold with minAbsoluteIncrease)
• Enforcement config (v3 — cost-control simulation)
• Idempotency config (v3 — event deduplication)
• Retention metadata (v3 — informational policy)
• Webhook URL (for real-time alerts)
• Budget threshold (for budget exceeded alerts)
• Output options

---

Example input (JSON)

Copy the JSON below into the Actor input and run — it works as-is with no file hosting. Do not use placeholder URLs like https://example.com/usage-data.csv; they do not exist and will return HTTP 404.

To use your own data via URL instead, leave out rawData, set inputType to "csv" or "json", and set dataUrl to a real URL that serves your data.

{
  "inputType": "json",
  "provider": "openai",
  "currency": "USD",
  "rawData": [
    {"timestamp":"2026-02-01T09:00:00Z","model":"gpt-4o","prompt_tokens":1200,"completion_tokens":450,"feature":"chatbot","user_id":"user-1","workflowId":"wf-support","nodeId":"node-classify","environment":"production","tenantId":"tenant-acme","endpoint":"/api/chat","outcomeType":"resolution","outcomeValue":1,"eventId":"evt-001"},
    {"timestamp":"2026-02-01T10:00:00Z","model":"gpt-4o","prompt_tokens":1500,"completion_tokens":600,"feature":"chatbot","user_id":"user-1","workflowId":"wf-support","nodeId":"node-respond","environment":"production","tenantId":"tenant-acme","endpoint":"/api/chat","outcomeType":"resolution","outcomeValue":1,"eventId":"evt-002"},
    {"timestamp":"2026-02-01T11:00:00Z","model":"gpt-4o-mini","prompt_tokens":300,"completion_tokens":120,"feature":"summarizer","user_id":"user-2","workflowId":"wf-content","nodeId":"node-summarize","environment":"production","tenantId":"tenant-acme","endpoint":"/api/summarize","outcomeType":"summary","outcomeValue":1,"eventId":"evt-003"},
    {"timestamp":"2026-02-01T13:00:00Z","model":"claude-3-5-sonnet","prompt_tokens":1800,"completion_tokens":700,"feature":"analysis","user_id":"user-5","workflowId":"wf-analytics","nodeId":"node-analyze","environment":"staging","tenantId":"tenant-acme","endpoint":"/api/analyze","outcomeType":"insight","outcomeValue":2,"eventId":"evt-004"},
    {"timestamp":"2026-02-01T15:00:00Z","model":"gpt-4o","prompt_tokens":900,"completion_tokens":350,"feature":"assistant","user_id":"user-3","workflowId":"wf-internal","nodeId":"node-draft","environment":"development","tenantId":"tenant-beta","endpoint":"/api/assist","outcomeType":"draft","outcomeValue":1,"eventId":"evt-005"},
    {"timestamp":"2026-02-02T09:00:00Z","model":"gpt-4o","prompt_tokens":1100,"completion_tokens":420,"feature":"chatbot","user_id":"user-1","workflowId":"wf-support","nodeId":"node-classify","environment":"production","tenantId":"tenant-acme","endpoint":"/api/chat","outcomeType":"resolution","outcomeValue":1,"eventId":"evt-006"},
    {"timestamp":"2026-02-02T11:00:00Z","model":"claude-3-5-sonnet","prompt_tokens":2200,"completion_tokens":850,"feature":"analysis","user_id":"user-5","workflowId":"wf-analytics","nodeId":"node-analyze","environment":"staging","tenantId":"tenant-acme","endpoint":"/api/analyze","outcomeType":"insight","outcomeValue":3,"eventId":"evt-007"},
    {"timestamp":"2026-02-02T14:00:00Z","model":"gpt-4o","prompt_tokens":950,"completion_tokens":370,"feature":"assistant","user_id":"user-3","workflowId":"wf-internal","nodeId":"node-draft","environment":"development","tenantId":"tenant-beta","endpoint":"/api/assist","outcomeType":"draft","outcomeValue":1,"eventId":"evt-008"},
    {"timestamp":"2026-02-02T16:00:00Z","model":"gpt-4o","prompt_tokens":1600,"completion_tokens":620,"feature":"chatbot","user_id":"user-4","workflowId":"wf-support","nodeId":"node-respond","environment":"production","tenantId":"tenant-gamma","endpoint":"/api/chat","outcomeType":"resolution","outcomeValue":1,"eventId":"evt-009"},
    {"timestamp":"2026-02-03T10:00:00Z","model":"gpt-4o","prompt_tokens":1350,"completion_tokens":530,"feature":"chatbot","user_id":"user-4","workflowId":"wf-support","nodeId":"node-respond","environment":"production","tenantId":"tenant-gamma","endpoint":"/api/chat","outcomeType":"resolution","outcomeValue":1,"eventId":"evt-010"}
  ],
  "priceTable": {
    "gpt-4o": { "inputPer1K": 0.0025, "outputPer1K": 0.01 },
    "gpt-4o-mini": { "inputPer1K": 0.00015, "outputPer1K": 0.0006 },
    "claude-3-5-sonnet": { "inputPer1K": 0.003, "outputPer1K": 0.015 }
  },
  "groupBy": ["model", "day", "feature", "workflow", "tenant"],
  "anomalyDetection": {
    "enabled": true,
    "thresholdMultiplier": 2.5,
    "minAbsoluteIncrease": 0.01,
    "groupByFeature": false
  },
  "enforcement": {
    "enabled": true,
    "maxDailyCost": 0.50,
    "action": "warn"
  },
  "idempotency": {
    "enabled": true,
    "ttlSeconds": 86400
  },
  "retention": {
    "rawDays": 90,
    "aggregateDays": 365
  },
  "budgetThreshold": 100,
  "writeDataset": true,
  "writeReportMd": true,
  "includeSummaryWhenEmpty": true
}

Using a URL instead? Omit rawData, set "inputType": "csv" or "json", and set "dataUrl" to a real URL that serves your CSV/JSON (e.g. a file you uploaded or a URL from your own server). Placeholder URLs like example.com do not work.

Re-running the same example? With idempotency.enabled: true, event IDs are remembered (for ttlSeconds, default 24h). A second run with the same eventIds will skip all events and complete successfully with 0 new records and an empty cost breakdown. To see the cost breakdown again, either set "idempotency": { "enabled": false } in the example or use different eventId values.

---

Supported input formats

CSV format

Your CSV should include columns such as:

• timestamp (or date, created_at)
• model
• prompt_tokens (or input_tokens, promptTokenCount for Gemini)
• completion_tokens (or output_tokens, candidatesTokenCount for Gemini)
• Optional: feature, user_id
• v3 Optional: workflowId, workflowName, nodeId, environment, tenantId, endpoint, provider, outcomeType, outcomeValue, eventId, prompt (will be hashed)

Provider-specific field names:

• OpenAI: prompt_tokens, completion_tokens
• Anthropic: input_tokens, output_tokens
• Groq: prompt_tokens, completion_tokens
• Gemini: promptTokenCount, candidatesTokenCount
• Azure OpenAI: prompt_tokens, completion_tokens (same as OpenAI)

Example:

timestamp,model,prompt_tokens,completion_tokens,feature,workflowId,nodeId,outcomeType,outcomeValue
2026-02-01T10:00:00Z,gpt-4o-mini,500,200,chatbot,workflow-123,node-1,lead,1

---

JSON format

OpenAI / Azure OpenAI:

[
  {
    "timestamp": "2026-02-01T10:00:00Z",
    "model": "gpt-4o-mini",
    "prompt_tokens": 500,
    "completion_tokens": 200,
    "feature": "chatbot",
    "workflowId": "workflow-123",
    "nodeId": "node-1",
    "tenantId": "tenant-abc",
    "environment": "prod",
    "outcomeType": "lead",
    "outcomeValue": 1,
    "eventId": "evt-xyz-123",
    "prompt": "You are a helpful assistant..." // Will be hashed automatically
  }
]

Anthropic:

[
  {
    "timestamp": "2026-02-01T10:00:00Z",
    "model": "claude-3-5-sonnet",
    "input_tokens": 500,
    "output_tokens": 200,
    "feature": "chatbot",
    "workflowId": "workflow-123"
  }
]

Gemini:

[
  {
    "timestamp": "2026-02-01T10:00:00Z",
    "model": "gemini-1.5-pro",
    "promptTokenCount": 500,
    "candidatesTokenCount": 200,
    "feature": "chatbot"
  }
]

---

Getting all reports

To get every output the Actor can produce, set these in the Input (they are all on by default):

Input	Default	Effect
writeDataset	true	Write cost records (or one summary record when all are duplicates) to the Dataset.
writeReportMd	true	Generate report.md in the Key-Value Store (human-readable audit report).
includeSummaryWhenEmpty	true	When idempotency skips all records, still push one summary record to the Dataset so workflows (e.g. n8n) get a result.

Summary (summary.json) is always written to the Key-Value Store; there is no option to disable it.

To include all reports: keep defaults or set explicitly:

"writeDataset": true,
"writeReportMd": true,
"includeSummaryWhenEmpty": true

Then you get:

• Dataset – Cost records (one per usage event), or one summary record when all events are duplicates.
• Key-Value Store – summary.json (full JSON summary) and report.md (markdown report).

---

Output details

Dataset (per record)

Each dataset item represents one usage record:

{
  "timestamp": "2026-02-01T10:00:00.000Z",
  "model": "gpt-4o-mini",
  "inputTokens": 500,
  "outputTokens": 200,
  "inputCost": 0.000075,
  "outputCost": 0.00012,
  "totalCost": 0.000195,
  "currency": "USD",
  "feature": "chatbot",
  "userId": "user123",
  "workflowId": "workflow-123",
  "nodeId": "node-1",
  "environment": "prod",
  "tenantId": "tenant-abc",
  "outcomeType": "lead",
  "outcomeValue": 1,
  "promptHash": "a1b2c3d4e5f6...",
  "eventId": "evt-xyz-123"
}

---

Summary (summary.json)

{
  "totalCost": 0.5234,
  "totalInputTokens": 15000,
  "totalOutputTokens": 10000,
  "totalRecords": 30,
  "currency": "USD",
  "byModel": [...],
  "byDay": [...],
  "byWorkflow": [...],
  "byNode": [...],
  "byTenant": [...],
  "byEnvironment": [...],
  "topCostDrivers": [...],
  "anomalies": [...],
  "outcomeEfficiency": {
    "recordsWithOutcomes": 25,
    "totalOutcomes": 150,
    "costPerOutcome": 0.0035,
    "outcomesPerDollar": 286.5,
    "byOutcomeType": [...]
  },
  "enforcementActions": [...],
  "idempotencyStats": {
    "duplicatesSkipped": 5,
    "uniqueEventsProcessed": 25
  },
  "retentionPolicyApplied": {
    "rawDays": 90,
    "aggregateDays": 365,
    "appliedAt": "2026-02-06T..."
  },
  "dataQuality": {
    "overallQualityScore": 100,
    "qualityGrade": "excellent",
    "successRate": 100,
    "fieldCompleteness": {...},
    "recommendations": [...]
  }
}

---

Report (report.md)

A human-readable Markdown report including:

• Executive Summary with overall metrics and efficiency score
• Cost Breakdown Tables (by model, day, feature)
• Attribution Breakdown (v3 — by workflow, node, tenant, environment)
• Outcome Efficiency (v3 — cost per outcome, outcomes per dollar, by outcome type)
• Top Cost Drivers analysis
• Anomaly Alerts with detailed context and top-offender attribution (v3)
• Enforcement Actions (v3 — simulated cost-control decisions)
• Data Quality Report section:
  • Quality score (0-100) with grade badge
  • Field completeness table
  • Data issues summary
  • Outlier detection results
  • Quality recommendations
• Token Efficiency Metrics section:
  • Efficiency score (0-100) with grade
  • Key metrics table (cost per request, tokens per request, ratios)
  • Cost efficiency table (cost per 1K tokens)
  • Token utilization percentages
  • Efficiency recommendations
• Cost Optimization Opportunities section:
  • Total potential savings
  • Recommendations grouped by priority (high/medium/low)
  • Specific action items for each opportunity
  • Affected records and costs
• Trend & Forecast section:
  • Last 7 days vs previous 7 days comparison table
  • Trend direction (increasing/decreasing/stable) with percentage change
  • Projected monthly cost based on recent daily averages
• Retention Policy (v3 — informational metadata)
• General Optimization Recommendations

Ideal for sharing with non-technical stakeholders and executives.

---

v3.0 New Features

🏷️ Attribution Layer

Track costs by workflow, node, tenant, and environment:

{
  "workflowId": "workflow-123",
  "workflowName": "Lead Generation Pipeline",
  "nodeId": "node-1",
  "environment": "prod",
  "tenantId": "tenant-abc",
  "endpoint": "/api/chat"
}

Aggregations:

• byWorkflow — Cost breakdown by workflow
• byNode — Cost breakdown by node/step
• byTenant — Cost breakdown by tenant
• byEnvironment — Cost breakdown by environment (prod/stage/dev)

Use cases:

• Multi-tenant cost allocation
• Workflow-level ROI analysis
• Environment cost comparison
• Node-level optimization

---

📊 Outcome Linkage

Link costs to business outcomes:

{
  "outcomeType": "lead",
  "outcomeValue": 1
}

Metrics:

• costPerOutcome — Average cost to produce one outcome
• outcomesPerDollar — How many outcomes per dollar spent
• Breakdown by outcome type

Use cases:

• ROI calculation (cost per lead, cost per conversion)
• Efficiency tracking (outcomes per dollar)
• Outcome-based optimization

---

🎯 Smarter Anomaly Detection

Dual-threshold spike detection:

A spike is only flagged when both conditions are met:

1. Relative spike > thresholdMultiplier (e.g., 2.5x)
2. Absolute delta > minAbsoluteIncrease (e.g., $0.50)

This prevents noise from small-value spikes while catching significant increases.

{
  "anomalyDetection": {
    "enabled": true,
    "thresholdMultiplier": 2.5,
    "minAbsoluteIncrease": 0.50,
    "groupByFeature": false
  }
}

Enhanced anomaly context:

• topOffender — Attribution context (workflowId, nodeId, model, promptHash)
• Helps operators pinpoint root cause

---

🛡️ Enforcement Engine

Simulate cost-control actions when thresholds are exceeded:

{
  "enforcement": {
    "enabled": true,
    "maxDailyCost": 100,
    "action": "warn"
  }
}

Actions:

• warn — Log warning (default)
• throttle — Simulate throttling
• switch_model — Simulate model downgrade
• block — Simulate request blocking

Important: All actions are simulated — no actual blocking occurs. This provides visibility into enforcement rules without risking data-pipeline disruption.

---

🔄 Idempotency Protection

Deduplicate events using eventId:

{
  "idempotency": {
    "enabled": true,
    "ttlSeconds": 86400
  }
}

How it works:

• Records with the same eventId are processed only once (within TTL window)
• Uses Apify KV store for persistence
• Records without eventId always pass through (fail-open)

Use cases:

• Prevent double-counting from retries
• Handle duplicate webhook deliveries
• Ensure idempotent processing

---

🔒 Prompt Security

Automatic prompt hashing:

If a record contains a prompt field:

• Raw prompt is hashed using SHA-256
• Only the hash (promptHash) is stored
• Raw prompt is never logged or stored

Example:

{
  "prompt": "You are a helpful assistant...",
  // → Automatically converted to:
  "promptHash": "a1b2c3d4e5f6..."
}

Security benefits:

• No PII leakage in logs
• No sensitive prompts in datasets
• Hash can be used for deduplication/analysis

---

📅 Retention Metadata

Attach retention policy metadata (informational only):

{
  "retention": {
    "rawDays": 90,
    "aggregateDays": 365
  }
}

Note: This actor does not delete data. The policy is attached to the summary for downstream systems to interpret.

---

🔗 n8n Integration

First-class support for ingesting n8n workflow events with flexible field mapping and automatic attribution.

Features:

• Accepts n8n events from HTTP Request/Webhook exports
• Maps custom field names to canonical structure
• Automatic eventId generation when missing
• Prompt hashing (SHA-256) with size limits
• Late event detection and marking
• Full attribution breakdown (workflow → node → run)

Configuration:

{
  "inputType": "n8n",
  "provider": "generic",
  "n8n": {
    "enabled": true,
    "source": {
      "type": "raw",
      "rawEvents": [
        {
          "eventId": "evt-001",
          "timestamp": "2026-02-01T10:00:00Z",
          "provider": "openai",
          "model": "gpt-4o",
          "inputTokens": 1200,
          "outputTokens": 450,
          "workflowId": "wf-support",
          "workflowName": "Customer Support",
          "nodeId": "node-classify",
          "nodeName": "Classify Request",
          "runId": "run-001",
          "env": "prod",
          "tenantId": "tenant-acme",
          "userId": "user-1",
          "endpoint": "/v1/chat/completions",
          "prompt": "Classify this request",
          "outcomeType": "resolution",
          "outcomeValue": 1,
          "outcomeOk": true
        }
      ]
    },
    "mapping": {
      "workflowIdField": "workflowId",
      "workflowNameField": "workflowName",
      "nodeIdField": "nodeId",
      "nodeNameField": "nodeName",
      "environmentField": "env",
      "tenantIdField": "tenantId",
      "userIdField": "userId",
      "runIdField": "runId",
      "eventIdField": "eventId",
      "timestampField": "timestamp"
    },
    "defaults": {
      "environment": "prod"
    },
    "derive": {
      "workflowNameFrom": "workflowId",
      "nodeIdFrom": "nodeName",
      "hashPrompt": true
    }
  },
  "idempotency": {
    "enabled": true,
    "ttlHours": 168,
    "allowedLateHours": 48
  }
}

Canonical Event Structure:

The Actor expects events with these fields (all optional except timestamp, model/provider, and token counts):

{
  "eventId": "uuid-or-hash",
  "timestamp": "ISO string",
  "provider": "openai|anthropic|google|bedrock|other",
  "model": "gpt-4o|claude-3-5-sonnet|...",
  "inputTokens": 123,
  "outputTokens": 456,
  "workflowId": "wf_123",
  "workflowName": "Lead Qualification",
  "nodeId": "node_7",
  "nodeName": "OpenAI Chat",
  "runId": "execution_999",
  "env": "prod|stage|dev",
  "tenantId": "customer_42",
  "userId": "agent_7",
  "endpoint": "/v1/responses",
  "prompt": "OPTIONAL raw prompt",
  "outcomeType": "lead",
  "outcomeValue": 1,
  "outcomeOk": true
}

Field Mapping:

Use n8n.mapping to map custom field names:

{
  "n8n": {
    "mapping": {
      "workflowIdField": "custom_workflow_id",
      "nodeIdField": "custom_node_id"
    }
  }
}

EventId Generation:

If eventId is missing, it's automatically generated from:

sha256(runId + nodeId + timestamp + model + inputTokens + outputTokens)

Prompt Handling:

• Prompts are automatically hashed using SHA-256
• Raw prompts are never stored (only promptHash)
• Prompts exceeding 1MB are dropped with a warning
• Set derive.hashPrompt: false to disable hashing

Late Events:

Events older than lastRunEnd - allowedLateHours are:

• Still processed (not skipped)
• Marked with lateEvent: true flag
• Included in idempotencyStats.lateEventsCount

Aggregations:

When n8n events include attribution fields, the Actor produces:

• byWorkflow — Cost breakdown by workflow
• byNode — Cost breakdown by node/step
• byTenant — Cost breakdown by tenant
• byEnvironment — Cost breakdown by environment
• byRunId — Cost breakdown by execution run

Use Cases:

• Multi-tenant cost allocation
• Workflow-level ROI analysis
• Node-level optimization
• Cost per successful run (with outcomeOk)
• Late event reconciliation

Example Output:

{
  "byWorkflow": [
    {
      "key": "wf-support",
      "totalCost": 0.5234,
      "inputTokens": 15000,
      "outputTokens": 10000,
      "recordCount": 30
    }
  ],
  "byNode": [
    {
      "key": "node-classify",
      "totalCost": 0.2345,
      "inputTokens": 8000,
      "outputTokens": 5000,
      "recordCount": 15
    }
  ],
  "idempotencyStats": {
    "duplicatesSkipped": 5,
    "uniqueEventsProcessed": 25,
    "lateEventsCount": 2
  }
}

---

Anomaly Detection

Overview

The Actor includes intelligent anomaly detection to identify unusual spending patterns. Anomalies are detected across multiple dimensions:

• Cost Spikes - Individual requests with unusually high costs (model-aware, v3: dual-threshold)
• Expensive Models - Models consuming disproportionate budget
• High Volume Days - Days with abnormally high usage
• Low Efficiency - Models with poor output/input token ratios

Configuration

Configure anomaly detection using the anomalyDetection object:

{
  "anomalyDetection": {
    "enabled": true,
    "thresholdMultiplier": 2.5,
    "minAbsoluteIncrease": 0.50,
    "groupByFeature": false
  }
}

Options:

• enabled (boolean) - Enable/disable anomaly detection (default: true)
• thresholdMultiplier (number) - Relative sensitivity multiplier (default: 2.5)
  • Higher = less sensitive (fewer anomalies)
  • Lower = more sensitive (more anomalies)
  • Range: 1.5 - 10
• minAbsoluteIncrease (number, v3) - Minimum absolute cost increase to trigger spike (default: 0.01)
  • Prevents noise from small-value spikes
  • Example: 0.50 means $0.50 minimum delta required
• groupByFeature (boolean) - Use per-model+feature baselines for spike detection (default: false)
  • false - Compare each record against other records from the same model
  • true - Compare against records from the same model AND feature

Data Requirements

Anomaly detection requires minimum data thresholds:

• Spike Detection: Requires at least 10 records
• Volume Detection: Requires at least 3 unique days

If your dataset doesn't meet these requirements:

• anomalyDetectionStatus will be set to "insufficient_data"
• anomalyDetectionNotes will explain what's missing
• The report will show a "Data too small" warning
• No spike/volume anomalies will be generated

Example insufficient data response:

{
  "anomalyDetectionStatus": "insufficient_data",
  "anomalyDetectionNotes": [
    "Too few records for spike detection (need at least 10, have 3).",
    "Too few days for volume detection (need at least 3, have 1)."
  ],
  "anomalies": []
}

Model-Aware Spike Detection

Spike detection uses per-model baselines to avoid false positives when comparing different models:

• Each model's costs are analyzed separately
• A spike is only flagged if it's unusual for that specific model
• Example: A $0.50 request is normal for gpt-4o but a spike for gpt-4o-mini

When groupByFeature: true, baselines are computed per model+feature combination:

• Useful when features have different typical usage patterns
• Example: "image-generation" vs "text-completion" may have different cost profiles

Enriched Spike Anomalies

Spike anomalies include detailed context for investigation:

{
  "type": "spike",
  "severity": "high",
  "model": "gpt-4o",
  "feature": "chatbot",
  "baseline": "per_model",
  "value": 0.5234,
  "threshold": 0.2500,
  "modelMedian": 0.0850,
  "modelP95": 0.3200,
  "groupRecordCount": 150,
  "rankInGroup": 1,
  "timestamp": "2026-02-01T14:32:00Z",
  "topOffender": {
    "workflowId": "workflow-123",
    "nodeId": "node-1",
    "model": "gpt-4o",
    "promptHash": "a1b2c3..."
  }
}

Fields:

• baseline - How the baseline was computed (per_model or per_model_feature)
• modelMedian - Median cost for this model/group
• modelP95 - 95th percentile cost
• groupRecordCount - Total records in baseline group
• rankInGroup - Where this record ranks (1 = most expensive)
• topOffender (v3) - Attribution context to help pinpoint root cause

Backward Compatibility

Legacy configuration format is still supported:

{
  "anomalyDetectionEnabled": true,
  "anomalyThreshold": 2.5
}

However, the new anomalyDetection object format is recommended for access to all features including dual-threshold.

---

Key Features

🔍 Data Quality Analysis

• Overall quality score (0-100) with grade (excellent/good/fair/poor)
• Success rate tracking (valid vs invalid records)
• Field completeness metrics (feature, userId, required fields)
• Data issue detection (normalization errors, invalid timestamps, duplicates, outliers)
• Actionable quality recommendations

⚡ Token Efficiency Metrics

• Efficiency score (0-100) based on multiple factors
• Input/output ratio analysis
• Cost per request metrics
• Cost per 1K tokens (input/output/total)
• Token utilization percentages
• Efficiency recommendations

💡 Cost Optimization Engine

• Rules-based recommendations (no AI magic)
• 5 detection rules:
  • Model downgrade opportunities (expensive models for simple tasks)
  • Prompt optimization (high input/low output ratio)
  • Caching opportunities (repetitive requests)
  • Feature optimization (dominating spend)
  • High-cost pattern detection
• Concrete action items for each recommendation
• Potential savings estimates
• Priority-based grouping (high/medium/low)

🏷️ Attribution & Outcome Analysis (v3)

• Cost attribution by workflow, node, tenant, environment
• Outcome efficiency — cost per outcome, outcomes per dollar
• Breakdown by outcome type for ROI analysis

🛡️ Enforcement & Security (v3)

• Enforcement simulation — cost-control actions when thresholds exceeded
• Idempotency protection — event deduplication with KV store
• Prompt security — automatic SHA-256 hashing (raw prompts never stored)

📡 Webhook Alerts (Optional)

• Anomaly alerts — HTTP POST when anomalies detected
• Budget alerts — HTTP POST when budget threshold exceeded
• Works with Slack, Discord, Zapier, or any webhook endpoint
• Simple HTTP POST with JSON payloads

---

Pricing (Apify)

• This Actor does not call any external APIs (no OpenAI/Anthropic/etc. calls from the Actor).
• All cost calculations use your price table and run on Apify; no per-record API fees.
• You pay only for Actor run time (compute and storage) via your Apify plan.

---

Common issues & fixes

"No input provided"

Ensure input is passed via:

• Apify UI
• Input JSON
• URL or raw data

---

"No price found for model"

Add the missing model to the priceTable:

{
  "your-model-name": {
    "inputPer1K": 0.001,
    "outputPer1K": 0.002
  }
}

---

CSV parsing errors

• Ensure header row exists
• Use commas as separators
• Quote text fields with commas

---

Webhook not sending

• Verify webhookUrl is configured correctly (must be HTTP/HTTPS)
• Check that anomalies were detected or budget threshold was exceeded
• Review Actor logs for webhook errors
• Test with https://webhook.site/ first

---

No optimization recommendations

• Optimization engine analyzes patterns automatically
• Recommendations appear when specific patterns are detected:
  • Model downgrade: Requires 5+ simple requests with expensive models
  • Prompt optimization: Requires 3+ requests with high input/low output ratio
  • Caching: Requires 5+ repetitive requests (same model + feature)
  • Feature optimization: Requires feature with >50% of spend
• If no recommendations: Current usage may already be efficient

---

v3 features not appearing

Attribution aggregations:

• Ensure records include workflowId, nodeId, tenantId, or environment fields
• Add these fields to your groupBy array if you want them in aggregations

Outcome efficiency:

• Ensure records include both outcomeType and outcomeValue fields
• Section only appears if at least one record has outcome data

Enforcement actions:

• Enable enforcement.enabled: true in config
• Set maxDailyCost threshold
• Actions only appear if threshold is exceeded

Idempotency:

• Enable idempotency.enabled: true in config
• Ensure records include eventId field
• Stats only appear if deduplication is enabled

---

Local development (optional)

For contributors or advanced users.

Install dependencies

$npm install

Build

$npm run build

Run tests

$npm test

Run locally

$npx apify run --input-file=example-input-raw.json

---

Deployment (developers)

apify login
apify push

Then run via the Apify Console.

---

What Makes This Actor Unique?

🎯 Actionable Insights (Not Just Metrics)

• Concrete recommendations: "Switch 15 requests from gpt-4o to gpt-4o-mini"
• Potential savings: See estimated cost reduction before acting
• Specific action items: Know exactly what to do

📊 Comprehensive Analysis

• Cost analysis: Aggregations by model, day, feature, user, workflow, node, tenant, environment
• Anomaly detection: Model-aware spike detection with dual-threshold (v3)
• Data quality: Quality score, completeness metrics, validation errors
• Token efficiency: Efficiency score, ratios, utilization analysis
• Outcome linkage (v3): Cost per outcome, outcomes per dollar
• Optimization: Rules-based recommendations with savings estimates
• Trend & forecast: Last 7 vs previous 7 days comparison, monthly projection
• Enforcement simulation (v3): Cost-control actions when thresholds exceeded

🔔 Real-Time Alerts

• Webhook notifications: Get alerted when anomalies detected or budget exceeded
• Works with any endpoint: Slack, Discord, Zapier, custom APIs
• Simple setup: Just provide webhook URL

🚀 Production Ready

• No external APIs: All processing done locally
• Fast: Processes thousands of records in seconds
• Secure: No API keys, no prompt logging (v3: automatic prompt hashing)
• Idempotent (v3): Event deduplication prevents double-counting
• Well-documented: Complete documentation and examples

---

Backward Compatibility

v3.0 is fully backward compatible with v2.0:

• ✅ All existing fields preserved
• ✅ Legacy config format still supported
• ✅ Dataset schema only extended (new fields optional)
• ✅ Summary schema only extended (new sections optional)
• ✅ All v3 features disabled by default
• ✅ Actor behaves identically to v2.0 unless you opt in
• ✅ n8n mode is opt-in (does not affect csv/json modes)

Migration:

• No changes required — existing configs continue to work
• Enable v3 features by adding new config sections
• Add attribution/outcome fields to your data to unlock new aggregations
• Use inputType: "n8n" to enable n8n event ingestion

---

Ready to audit your AI costs?

Run the Actor with your usage data (CSV, JSON, or n8n events), or trigger it from OpenClaw chat. You get:

• Complete cost breakdown by model, day, feature, workflow, node, tenant, environment
• Anomaly detection and optimization recommendations with estimated savings
• Data quality and token efficiency metrics
• Optional webhook alerts and idempotent processing for pipelines

Use it from: Apify Console · Apify API · n8n (Apify node) · OpenClaw (ai_cost_audit tool)

Get clear answers about where your AI budget is going — and how to reduce it — in minutes.