Loss Run API Documentation

Extract claims from carrier loss runs in your own software. Upload a PDF, start an extraction, poll until it finishes, then download the claims through the API as structured JSON, CSV or Excel.

Reference status. This page describes the API as it behaves today and is the reference; there is no separate OpenAPI specification. Read limits such as the rate limit from the response headers in your code rather than hard-coding them.

Contents

How an extraction works

API requests use the base URL https://lossrunguru.com/v1. Extracting one loss run takes these steps:

  1. Request an upload URL with POST /v1/uploads.
  2. Upload the file with an HTTP PUT to the URL you got back. Do not send your API key to that URL.
  3. Start the extraction with POST /v1/extractions. Nothing is charged yet.
  4. Poll GET /v1/extractions/{id} until the status is completed, locked or failed. Extraction usually takes a few minutes.
  5. Unlock a locked extraction with POST /v1/extractions/{id}/unlock. By default an extraction is charged and unlocked automatically when it finishes, so you only need this step if you turned that off or your balance was short.
  6. Download the claims with GET /v1/extractions/{id}/claims.

Each extraction reads one file: a PDF, PNG or JPEG of up to 25 MB. To extract several loss runs, run one extraction per file. The API sends no emails: poll for results instead.

Get an API key

API access is available on paid accounts: any account that has bought a credit pack, of any size, can create a key.

  1. Log in and open Settings. Find the API access card.
  2. If your account has not bought a credit pack yet, the card links to Credits. Buy any pack, then come back to Settings.
  3. Create a key. The full key is shown once: copy it, store it somewhere safe, then click I’ve saved it. Afterwards Settings shows only the key’s prefix.

Live keys start with lrg_live_. Each account has one active key. Regenerating replaces it and the old key stops working immediately; revoking turns it off. Keep the key on your server and out of browser or mobile code.

Authentication

Send the key as a Bearer token in the Authorization header of every /v1 request:

export LOSSRUNGURU_API_KEY="lrg_live_your_key_here"
curl https://lossrunguru.com/v1/me \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY"

A missing, malformed or revoked key gets 401 UNAUTHORIZED. A valid key on an account that has never bought a credit pack gets 403 FORBIDDEN.

1. Request an upload URL

POST /v1/uploads with the file name and its content type. contentType must be application/pdf, image/png or image/jpeg.

curl -X POST https://lossrunguru.com/v1/uploads \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "acme-trucking-2024.pdf", "contentType": "application/pdf"}'

Response 201 Created:

{
  "uploadId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
  "uploadUrl": "https://...",
  "uploadHeaders": { "Content-Type": "application/pdf" },
  "expiresAt": "2026-11-20T15:15:00Z"
}

The uploadUrl is valid for 15 minutes. Keep the uploadId: you need it to start the extraction, and it becomes the extraction’s id. An upload that is never extracted is deleted after 24 hours.

2. Upload the file

PUT the file’s raw bytes to uploadUrl, sending every header in uploadHeaders:

UPLOAD_URL="paste the uploadUrl from step 1 here"
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @acme-trucking-2024.pdf

A 200 response means the file is stored. Size and content are checked in the next step: the file must be 25 MB or smaller, not empty, and its content must match the type you declared.

3. Start the extraction

POST /v1/extractions with the uploadId. An Idempotency-Key header is required: any unique string of 1 to 255 characters, such as a UUID.

curl -X POST https://lossrunguru.com/v1/extractions \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b9d4d52-6a0e-4b38-9a43-5c1f3e2d7a10" \
  -d '{"uploadId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93"}'

Response 202 Accepted:

{
  "id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
  "status": "processing",
  "pageCount": 12,
  "autoUnlock": true
}
FieldMeaning
uploadIdRequired. The id from POST /v1/uploads.
autoUnlockOptional, default true. When the extraction finishes, charge your paid credits and unlock it automatically. Set it to false to have every extraction wait as locked until you call unlock, for example so a person can approve the cost first.

Your account needs a paid credit balance above zero to start an extraction; otherwise you get 402 INSUFFICIENT_CREDITS and nothing is sent. The cost is worked out from the number of claims found, after extraction. See Credits.

Retrying safely

If a request times out or the connection drops, send it again with the same Idempotency-Key. The extraction will not run twice:

  • If the first request was accepted, you get the original 202 response back, with an Idempotent-Replayed: true header.
  • If the first request returned 502 (the document could not be submitted for extraction), you get that 502 back. Nothing was charged. Request a new upload URL, upload the file again and start a new extraction with a new key.
  • If the first request is still running, you get 409 CONFLICT. Wait a moment and retry.
  • A 400 or 402 response is returned before anything is sent, so you can fix the problem and retry with the same key.
  • Reusing a key with a different request body returns 409 CONFLICT.
  • Each upload is extracted once. Starting it again with a new key returns 409 “This upload has already been extracted.”

Use a new key for each new extraction. A key is remembered for at least 24 hours.

4. Check the extraction

GET /v1/extractions/{id} returns the extraction’s current state:

curl https://lossrunguru.com/v1/extractions/3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93 \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY"
{
  "id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
  "fileName": "acme-trucking-2024.pdf",
  "createdAt": "2026-11-20T15:00:12Z",
  "status": "completed",
  "autoUnlock": true,
  "pageCount": 12,
  "claimCount": 23,
  "creditsRequired": 5,
  "creditsCharged": 5,
  "failure": null
}
statusMeaning
processingThe loss run is being read. Poll again later.
lockedExtraction finished and the claims are priced (claimCount, creditsRequired), but nothing has been charged. Either autoUnlock was false, or your paid balance did not cover creditsRequired. Unlock it to download the claims.
completedCharged and unlocked. creditsCharged is set and the claims are ready to download.
failedThe extraction did not finish. failure says why. A failed extraction is never charged.

A failed extraction looks like this:

{
  "id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
  "status": "failed",
  ...
  "failure": {
    "code": "NO_CLAIMS",
    "message": "No claims were found in this document. Nothing was charged."
  }
}
failure.codeMeaning
NO_CLAIMSThe document was read but no claims were found in it.
TIMED_OUTExtraction did not finish within 3 hours.
SUBMIT_FAILEDThe document could not be submitted for extraction.
RETIREDThe document was removed before extraction finished.
PROCESSING_FAILEDExtraction failed for another reason.

Wait at least 10 seconds between polls. Each poll counts toward your rate limit. A 404 NOT_FOUND means the id is not one of your API extractions; uploads made in the web app are not visible to the API.

5. Unlock a locked extraction

POST /v1/extractions/{id}/unlock charges creditsRequired paid credits and unlocks the claims. No body is needed:

curl -X POST https://lossrunguru.com/v1/extractions/3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93/unlock \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY"

Response 200 OK:

{
  "id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
  "status": "completed",
  "creditsCharged": 5,
  "paidCreditsRemaining": 35
}

Unlocking is safe to retry: an extraction that is already unlocked returns the same 200 body and is not charged again. If your paid balance is too low, nothing is charged and you get 402 with the shortfall:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough paid credits to unlock this extraction. Top up on lossrunguru.com, then retry.",
    "details": { "creditsRequired": 5, "creditsAvailable": 2, "shortfall": 3 }
  }
}

Buy credits on lossrunguru.com, then call unlock again. An extraction that is still processing or has failed returns 409 NOT_READY.

6. Download the claims

GET /v1/extractions/{id}/claims?format=json, ?format=csv or ?format=xlsx. The API defaults to JSON.

curl "https://lossrunguru.com/v1/extractions/3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93/claims" \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY"
{
  "schemaVersion": 1,
  "id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
  "metadata": {
    "fileName": "acme-trucking-2024.pdf",
    "pageCount": 12,
    "claimCount": 23
  },
  "claims": [
    {
      "carrier": "Example Mutual Insurance Co",
      "insuredName": "Acme Trucking LLC",
      "policyNumber": "CA-1048825",
      "policyYear": "2024",
      "lineOfBusiness": "Commercial Auto",
      "policyEffectiveDate": "2024-03-01",
      "policyExpirationDate": "2025-03-01",
      "claimNumber": "CLM-20240611-07",
      "claimantName": "J. Rivera",
      "lossDescription": "Insured vehicle rear-ended claimant at intersection",
      "dateOfLoss": "2024-06-11",
      "dateReported": "2024-06-12",
      "closeDate": null,
      "claimStatus": "Open",
      "indemnityPaid": "8250.00",
      "expensePaid": "1100.00",
      "totalPaid": "9350.00",
      "indemnityReserve": "4000.00",
      "totalReserve": "4000.00",
      "totalIncurred": "13350.00",
      ...
    }
  ]
}
  • The API returns every field on every claim in JSON, with null where the loss run has no value. The full list is below.
  • Dates are ISO 8601 (YYYY-MM-DD). Amounts are decimal strings with at least two places ("$1,250" becomes "1250.00"; negatives and amounts in parentheses become negative). A date or amount that cannot be read is null rather than a guess.
  • Claims are in the same order as the CSV: grouped by policy, policies by effective date, claims by date reported.
  • schemaVersion is currently 1. This page is the reference for the shape.
  • format=csv returns text/csv and format=xlsx an Excel workbook, both as file downloads with the same columns as the web app.
  • For format=xlsx, send Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. Without it the workbook arrives base64-encoded instead of as raw bytes.

A locked extraction returns 409 LOCKED with creditsRequired in details; one that is processing or failed returns 409 NOT_READY. A 502 UPSTREAM_UNAVAILABLE is temporary: retry after a short wait.

Claim fields

FieldCSV columnType
carrierCarriertext
insuredNameInsured Nametext
policyNumberPolicy Numbertext
policyYearPolicy Yeartext
lineOfBusinessLine of Businesstext
policyEffectiveDatePolicy Effective Datedate
policyExpirationDatePolicy Expiration Datedate
claimNumberClaim Numbertext
claimantNameClaimant Nametext
lossDescriptionLoss Descriptiontext
injuryTypeInjury Typetext
injuredBodyPartInjured Body Parttext
driverNameDriver Nametext
dateOfLossDate of Lossdate
dateReportedDate Reporteddate
closeDateClose Datedate
valuationDateValuation Datedate
lossLocationLoss Locationtext
lossStateLoss Statetext
lossCityLoss Citytext
claimStatusClaim Statustext
indemnityPaidIndemnity Paidamount
expensePaidExpense Paidamount
alaePaidALAE Paidamount
medicalPaidMedical Paidamount
totalPaidTotal Paidamount
indemnityReserveIndemnity Reserveamount
expenseReserveExpense Reserveamount
alaeReserveALAE Reserveamount
medicalReserveMedical Reserveamount
totalReserveTotal Reserveamount
subrogationRecoverySubrogation Recoveryamount
salvageRecoverySalvage Recoveryamount
recoveryRecoveryamount
totalRecoveryTotal Recoveryamount
totalIncurredTotal Incurredamount
deductible1Deductible 1amount
deductible2Deductible 2amount
yearYeartext
monthMonthtext
dayOfWeekDay of Weektext
lagTimeLag Timetext

Text fields are returned as printed on the loss run. Read totals against the source document before you rely on them.

List your extractions

GET /v1/extractions lists your API extractions, newest first:

curl "https://lossrunguru.com/v1/extractions?status=locked&limit=50" \
  -H "Authorization: Bearer $LOSSRUNGURU_API_KEY"
{
  "data": [
    { "id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93", "status": "locked", ... }
  ],
  "nextCursor": "NjM4OTk5NjQ0MDAwMDAwMDAwOjFiNGQ..."
}
Query parameterMeaning
statusOptional. processing, locked, completed or failed.
created_afterOptional. An ISO 8601 timestamp; only extractions started after it.
limitOptional. 1 to 100, default 25.
cursorOptional. The nextCursor from the previous page.

Each item has the same fields as GET /v1/extractions/{id}. nextCursor is null on the last page. Paging is stable: extractions started while you page through do not cause duplicates or gaps.

Your account and credits

GET /v1/me returns your account and balances:

{
  "userId": "8b2f0c4e-7d1a-4f3b-9c6e-2a5d8e1f4b70",
  "email": "you@agency.com",
  "paidCreditsRemaining": 40,
  "freeCreditsRemaining": 0,
  "apiKeyPrefix": "lrg_live_ab12"
}

API extractions only ever use paidCreditsRemaining. Free credits are for the web app.

Credits

  • API extractions use purchased (paid) credits only. Free credits are never used.
  • An extraction is priced after it finishes, by the number of claims found: 1 credit per 5 claims, rounded up. A 23-claim loss run costs 5 credits. There is no page limit and nothing is charged up front.
  • With autoUnlock on (the default), the credits are charged when the extraction finishes. If your balance is short at that moment, the extraction waits as locked until you top up and call unlock.
  • With autoUnlock off, nothing is charged until you call unlock.
  • A failed extraction, including one with no claims, is never charged.
  • Credits never expire.

Errors

Errors share one shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "uploadId must be the id returned by POST /v1/uploads."
  }
}
StatuscodeWhen
400VALIDATION_ERRORThe request is invalid. message says what to fix, for example an expired upload link, a file over 25 MB, or content that does not match its type.
401UNAUTHORIZEDMissing, malformed or revoked API key.
402INSUFFICIENT_CREDITSNo paid credits to start an extraction, or too few to unlock one.
403FORBIDDENThe account has never bought a credit pack.
404NOT_FOUNDUnknown route, or an id that is not one of your API extractions.
409CONFLICTIdempotency conflict, or an upload that was already extracted.
409LOCKEDClaims requested for a locked extraction.
409NOT_READYThe extraction is still processing or has failed.
429RATE_LIMITEDToo many requests. See Rate limits.
500INTERNAL_ERRORSomething went wrong on our side. Retry later.
502INTERNAL_ERRORFrom POST /v1/extractions: the document could not be submitted. Nothing was charged.
502UPSTREAM_UNAVAILABLEFrom the claims download: temporarily unavailable. Retry.

Every response carries an X-Request-Id header. Include it if you contact support about a request.

Rate limits

Each API key can make 60 requests per minute. Every response carries the current limit:

HeaderValue
X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetUnix time, in seconds, when the count resets.

Over the limit you get 429 RATE_LIMITED with a Retry-After header in seconds. The PUT to uploadUrl does not count.

Full example: Python

Uploads a loss run, extracts it, unlocks it if needed and prints each claim. Uses the requests package.

import os
import time
import uuid
import requests

API = "https://lossrunguru.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['LOSSRUNGURU_API_KEY']}"}


def extract_claims(path, auto_unlock=True):
    upload = requests.post(f"{API}/uploads", headers=HEADERS, json={
        "fileName": os.path.basename(path),
        "contentType": "application/pdf",
    })
    upload.raise_for_status()
    upload = upload.json()

    with open(path, "rb") as f:
        requests.put(upload["uploadUrl"], headers=upload["uploadHeaders"], data=f).raise_for_status()

    started = requests.post(f"{API}/extractions", headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
                            json={"uploadId": upload["uploadId"], "autoUnlock": auto_unlock})
    started.raise_for_status()
    extraction_id = started.json()["id"]

    while True:
        time.sleep(15)
        extraction = requests.get(f"{API}/extractions/{extraction_id}", headers=HEADERS).json()
        if extraction["status"] == "failed":
            raise RuntimeError(extraction["failure"]["message"])
        if extraction["status"] == "locked":
            unlocked = requests.post(f"{API}/extractions/{extraction_id}/unlock", headers=HEADERS)
            if unlocked.status_code == 402:
                raise RuntimeError(unlocked.json()["error"]["message"])
            unlocked.raise_for_status()
        if extraction["status"] in ("locked", "completed"):
            break

    claims = requests.get(f"{API}/extractions/{extraction_id}/claims", headers=HEADERS)
    claims.raise_for_status()
    return claims.json()["claims"]


for claim in extract_claims("acme-trucking-2024.pdf"):
    print(claim["claimNumber"], claim["dateOfLoss"], claim["totalIncurred"])

Full example: Node.js

The same flow with Node.js 18 or later, which has fetch built in. Save it as an .mjs file.

import { readFile } from "node:fs/promises";
import { basename } from "node:path";
import { randomUUID } from "node:crypto";

const API = "https://lossrunguru.com/v1";
const headers = { Authorization: `Bearer ${process.env.LOSSRUNGURU_API_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(path, options = {}) {
  const response = await fetch(`${API}${path}`, { ...options, headers: { ...headers, ...options.headers } });
  const body = await response.json();
  if (!response.ok) throw new Error(`${response.status} ${body.error.code}: ${body.error.message}`);
  return body;
}

async function extractClaims(path, autoUnlock = true) {
  const upload = await call("/uploads", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ fileName: basename(path), contentType: "application/pdf" }),
  });

  const put = await fetch(upload.uploadUrl, { method: "PUT", headers: upload.uploadHeaders, body: await readFile(path) });
  if (!put.ok) throw new Error(`Upload failed: ${put.status}`);

  const { id } = await call("/extractions", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
    body: JSON.stringify({ uploadId: upload.uploadId, autoUnlock }),
  });

  for (;;) {
    await sleep(15000);
    const extraction = await call(`/extractions/${id}`);
    if (extraction.status === "failed") throw new Error(extraction.failure.message);
    if (extraction.status === "locked") await call(`/extractions/${id}/unlock`, { method: "POST" });
    if (extraction.status === "locked" || extraction.status === "completed") break;
  }

  return (await call(`/extractions/${id}/claims`)).claims;
}

for (const claim of await extractClaims("acme-trucking-2024.pdf")) {
  console.log(claim.claimNumber, claim.dateOfLoss, claim.totalIncurred);
}

Use it from an AI assistant (MCP)

The LossRunGuru MCP server connects Claude Desktop, Claude Code, Cursor, VS Code and other MCP clients to this API, so you can ask your assistant to extract a loss run instead of writing code. For example: “Extract the claims from ~/Downloads/acme-loss-run.pdf with LossRunGuru and save them as an Excel file next to the PDF.”

It runs on your computer and needs Node.js 22 or later and an API key (see Get an API key). In Claude Code:

claude mcp add lossrunguru --scope user -e LOSSRUNGURU_API_KEY=lrg_live_your_key_here -- npx -y @lossrunguru/mcp

In Claude Desktop (Settings → Developer → Edit Config), Cursor and most other clients, add it to the client’s MCP config:

{
  "mcpServers": {
    "lossrunguru": {
      "command": "npx",
      "args": ["-y", "@lossrunguru/mcp"],
      "env": { "LOSSRUNGURU_API_KEY": "lrg_live_your_key_here" }
    }
  }
}

Your assistant asks before spending credits. Extracting a loss run through the MCP server never charges: the result waits as locked, with its claim count and price at 1 credit per 5 claims. Only the separate unlock step spends credits, so your assistant tells you the price and your AI app asks you to approve that step before anything is charged.

The server can also check your credit balance, list your API extractions and save unlocked claims as CSV or Excel on your computer. Setup for every client, the full tool list and troubleshooting are in the package README.