Pricing and estimates

Spending here is prepaid and per Run. You top a balance up, each operation draws its price from it, and every charge is a line you can read back. There are three things worth knowing before you write the integration: an answer we already hold costs a quarter of a fresh one, you can ask the price of any call without making it, and running out of money is refused before any work starts rather than halfway through.

The balance

One prepaid dollar balance per organization. Every key that organization issues spends the same balance, so a runaway script on a staging key drains the same pot as production. Reading the balance is free and instant:

curl "https://www.shortsintel.com/v1/account/balance" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/account/balance",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/account/balance",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

{
  "balance_usd": 42.31,
  "currency": "usd",
  "starter_credit_expires_at": "2026-10-01T00:00:00.000Z"
}

Reads never cost anything — the balance, the spend log, a Run you already paid for, a page of Run items. Only work costs money, and work only happens once.

A charge per Run

Each paid operation creates a Run and each Run carries exactly one charge. The Run records both numbers: list_price_usd, what the operation costs at list, and charged_usd, what you actually paid. When those two differ, cached says why.

Every operation’s price is on its entry in the reference. Scoring is the exception to the discount: $0.05, never cached — asking for a score is asking for the fetch.

What makes a result cached

A result is cached when we already hold a stored observation of the same subject that is younger than 24 hours, so answering you needs no upstream fetch. That answer costs 25% of the fresh price — $0.00125 instead of $0.005 on a video lookup.

It is a property of the data, not of your account: another customer asking for the same video a minute before you is what makes your call cheap. You never opt in and you cannot opt out, but you can always see which you got, on the Run and in the spend log.

curl "https://www.shortsintel.com/v1/account/usage?limit=25" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/account/usage?limit=25",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/account/usage?limit=25",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

GET /v1/account/usage · Free. One row per charge, each naming the Run behind it.

Ask the price first

Almost every paid operation takes estimate. `true` returns `{ estimate_usd, cached }` computed from what is already stored, and creates no Run. Nothing is charged. Only `true` or `false`; anything else is a 400. A POST may send it in the body instead; given in both places with different values it is a 400. The exceptions are POST /v1/trackers and POST /v1/trackers/{id}/refresh: they take no estimate and charge when called, so read the price on their reference entry first. You get the two numbers that decide whether to go ahead — what it would cost, and whether that price is the cached one:

curl "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?wait=30&estimate=true" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?wait=30&estimate=true",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?wait=30&estimate=true",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

{
  "estimate_usd": 0.005,
  "cached": false
}

No Run is created, nothing is charged, and the estimate is computed from the same stored state the real call would price itself against, so an agent that estimates and then calls is quoted what it pays. The one thing an estimate cannot promise is time: a stored observation can age past 24 hours between the two calls, and then the real call is fresh work at the fresh price.

Running out of money

The balance is checked against the operation’s quoted price before any work starts — for Research and enriched searches, the worst-case quote. Too little and the call is refused immediately with 402, a code to branch on, and the two numbers you need to say what went wrong:

{
  "type": "https://docs.shortsintel.com/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance does not cover this operation. Top up in the console.",
  "balance_usd": 0.001,
  "required_usd": 0.005
}

Nothing is charged and no Run is created, so a 402 can be retried the moment the balance is topped up. See the errors guide for the rest of the codes.

Failed and partial work

A Run that ends failed costs nothing at all. There is no refund step and no credit to claim: the charge is written when work succeeds, so failed work is never charged in the first place.

A Run that fans out over many items and only lands some of them ends partial, and is charged per item that arrived. The same happens if the balance runs short while it works: the completed items are charged in order up to the balance, the rest fail with insufficient_balance, and a Run that could not pay for any of its work ends failed and costs nothing. GET /v1/runs/{id}/items lists them with their individual charges, so a bill over a big research pass reconciles item by item.

curl "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b/items?limit=25&type=videos" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b/items?limit=25&type=videos",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b/items?limit=25&type=videos",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

Put together, the rule is short enough to hold in your head: you pay once, for work that succeeded, at a quarter price when we did not have to go and fetch it.