API reference

One endpoint. Report each agent run when it finishes, Solventic tracks the cost and the outcome value automatically from there.

Authentication

Every request needs your personal API key as a bearer token. Find it on the Connect your agents page. Keep it server-side, never in client-side code.

Authorization: Bearer sk_live_your_key_here

POST /api/ingest/run

Call this once per completed agent run, from your agent's callback/webhook, not from inside the chain itself.

You must send either cost, or all four of provider / model / input_tokens / output_tokens.

Response

{ "status": "ok", "outcome_value": 42.0 }

How the cost is calculated

There are two ways to report cost, and Solventic always prefers the first one when it can use it.

Token-based (calculated by Solventic)

Send provider, model, input_tokens, and output_tokens. Solventic looks up that model in its own verified per-token pricing table and computes the cost itself, ignoring any cost value you also send. This is deliberate: it means the number on your dashboard isn't just whatever a client reports, it's independently calculated from usage.

If your provider or model isn't on this list yet, send cost directly instead, and let us know, we're adding to this table regularly.

Self-reported

Send cost as a dollar amount and skip the token fields. Solventic uses this number as-is. This is the simpler path if you're already tracking spend yourself, or using a provider we don't have pricing for yet.

How the outcome value is calculated

On the Connect your agents page, you set a dollar value for each status on a given workflow, for example a resolved support ticket might be worth $8 in avoided human handling cost, a completed booking might be worth a fixed commission. Those three numbers (resolved_value, escalated_value, failed_value) live on the workflow's configuration.

Every time you report a run, Solventic looks up the value matching that run's status and stamps it on as outcome_value, both in the API response and on your dashboard. If a workflow hasn't been configured yet, a small placeholder value is used instead so test runs don't error out, configure it on the setup page to see real numbers.

Your dashboard's totals are just sums of these two numbers across every run in the period: total spend is the sum of every run's cost, value delivered is the sum of every run's outcome_value. Net value and ROI ratio are derived from those two sums.

Labor displacement (hours saved)

On the Connect your agents page you can optionally set resolved_minutes per workflow -- roughly how long a human would have spent on a task this agent resolves. Every resolved run is stamped with that estimate at ingest time as outcome_minutes (escalated and failed runs get 0, since a human still had to finish the task). Your dashboard sums this into an "hrs saved" figure alongside dollar value delivered, both overall and per workflow. This isn't part of the request/response payload above -- it's derived automatically from your workflow config, the same way outcome_value is.

Payback period

Also on the Connect your agents page, you can optionally set an upfront_cost per workflow -- a one-time build or license cost. Every run's outcome_value - cost is added to a running total for that workflow (independent of your plan's data retention window, so it doesn't reset or lose history as older runs age out of what's displayed). Your dashboard shows progress toward that upfront cost, and the date it was crossed once it has been.

Rate limits

300 requests per minute per API key. This is burst protection against a runaway loop or a leaked key, separate from your plan's monthly run quota shown on the setup page.

Examples

curl -X POST https://www.solventic.io/api/ingest/run \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "support_bot",
    "status": "resolved",
    "provider": "anthropic",
    "model": "claude-haiku-4.5",
    "input_tokens": 1450,
    "output_tokens": 320
  }'

curl -X POST https://www.solventic.io/api/ingest/run \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "support_bot",
    "status": "resolved",
    "cost": 0.014
  }'

import requests

requests.post(
    "https://www.solventic.io/api/ingest/run",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    json={
        "workflow": "support_bot",
        "status": "resolved",          # resolved | escalated | failed
        "provider": "anthropic",
        "model": "claude-haiku-4.5",
        "input_tokens": 1450,
        "output_tokens": 320,
    },
)

# LangChain: drop this in a callback's on_chain_end (or wherever your
# pipeline knows the final outcome), not inside the chain itself.