> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pramaan.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use your own provider key

> Run calls to a service on your own account with it: Pramaan charges nothing for them.

Most data and AI capabilities run on Pramaan's key for the service behind them, and you pay
Pramaan per call. If you already have an account with one of those services, you can save your
own key for it. Your calls to that service then run on your key, and Pramaan charges nothing for
them. The service bills you directly.

This is separate from [connections](https://docs.pramaan.dev/guides/connections.md), which cover services that only ever
run on your own account (your email sender, your payments account, your database).

## Ask Pramaan to turn it on

Own keys are off for every account until Pramaan turns them on for yours. Ask Pramaan. They can
allow every covered service or a chosen list, and can limit it to chosen capabilities. Until
then the **Your own provider keys** section shows "Using your own provider keys is not enabled
for your account", saving a key is refused, and every call runs on Pramaan's key.

* You see, and can save a key for, only the services Pramaan allowed for your account.
* A service or capability outside what Pramaan allowed behaves as if you had no key: the call
  runs on Pramaan's key and is charged as usual.
* If Pramaan later narrows what you are allowed or turns it off, your saved keys are kept but
  not used, and you cannot change or remove them while they are outside your allowance. When
  Pramaan widens it again they are back in use, with nothing to enter again. To have a saved
  key deleted while it is switched off, ask Pramaan.
* A job that was running on your key when it was switched off fails with a clear error instead
  of finishing on Pramaan's key. Start it again.

## Connect a key

1. Open **Connections** in the dashboard and scroll to **Your own provider keys**.
2. Pick the service, open **Use your own key** and paste the fields it asks for. Most ask for
   one API key; a few also take an account, workspace or project id. Every required field must
   be yours: nothing of Pramaan's account is ever sent beside your key.
3. Save. The next call runs on your key.

Your key is encrypted at rest, decrypted only for the call that needs it, and never shown again:
the page lists which fields are set, not their values. To rotate, save the new key over the old
one. To stop, remove it; the next call is back on Pramaan's key and charged as usual.

Pramaan does not test the key when you save it. A wrong key fails its first call.

## What is free

A call that ran on your key has no Pramaan fee and no provider cost on your Pramaan bill.
Nothing is held and nothing is charged. `X-Pramaan-Price-Micro` is `0`.

Unchanged, because they are Pramaan's own resources and not the provider's:

* **Stored files.** A result saved to Pramaan's file storage (generated audio, images, exports)
  is kept and limited like any other file of yours. Storage has no separate charge today.
* **Rentals.** Numbers, inboxes, domains, monitors and other things billed by the month are
  billed as before. The services that rent them are not covered here (see below).

## Which calls use your key

Once you save a key for a service, every capability that service can serve runs on your key,
and only there. It does not quietly move to another service on Pramaan's key, even when yours
is slow or down. Capabilities the service does not serve are unaffected.

* **Jobs** start and poll on the key in place when you requested them. If you change or remove
  the key while a job is running, the job fails with a clear error instead of finishing on a
  different key. Start it again.
* **Things you created** on your key (anything a call returned a `ref` for, and rows of a list
  that carry a `ref`) are followed up on that key only. Things created before you saved a key
  stay on Pramaan's key.
* **A job that fell back** to Pramaan's key finishes there and is charged, even if you change or
  remove your key meanwhile.
* **Bulk runs** use the key in place when the run was requested, for every row.

## When your key fails

If the service refuses your key, your account there is out of credit, or it rate limits you, the
call fails with the usual error and a note:

```json theme={null}
{
  "error": {
    "code": "upstream_unavailable",
    "message": "The data source is unavailable. It ran on your own key. Turn on \"fall back to Pramaan's key\" for this connection to retry there.",
    "request_id": "req_01J...",
    "retryable": false,
    "effect": "none",
    "reason": "own_key"
  }
}
```

`reason` is `own_key` and, for a read, `effect` is `none`: nothing happened on Pramaan's side
and nothing was charged.

## The fallback setting

Each key has a **fall back to Pramaan's key** switch. It is off unless you turn it on, or Pramaan
set your account so new keys start with it on. Pramaan can also switch the fallback off for your
whole account: the switch then disappears from the page, every key behaves as **Off**, and your
own setting is kept for when it is allowed again.

* **Off:** a call never runs on Pramaan's key while yours is saved. A failure is an error.
* **On:** a read that failed on your key for one of the reasons above is retried once on
  Pramaan's key for the same service. That call is charged like any Pramaan call. While the
  switch is on, a call is checked against your balance and its estimate is set aside while it
  runs, exactly like a Pramaan call; when your key answered, the amount is given back and
  nothing is charged.

Actions (anything that sends, posts, buys or changes something) are never retried on another
key once the request has reached the service, whatever the switch says. Retry those yourself
with the same `Idempotency-Key`.

## Which services are covered

The **Your own provider keys** list in the dashboard is the full, current list: search, scraping
and enrichment sources, language and embedding models, speech and translation, maps, weather,
security and company data.

Not covered, because the account behind the key needs setup of its own that a key alone does
not carry:

* **Texting, calls, two-way email and social** run on an account Pramaan opens for your
  organisation, with numbers, senders and registrations attached to it.
* **Services that call Pramaan back** (webhooks and job callbacks are registered to Pramaan's
  address and signed with Pramaan's secret).
* **Services that rent standing things** through Pramaan (monitors, indexes, inboxes).
* **App integrations** (`apps.*`), where your users' connected accounts live on Pramaan's
  account.
* Services that are already yours to connect under [connections](https://docs.pramaan.dev/guides/connections.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.