> For the complete documentation index, see [llms.txt](https://biggeo.gitbook.io/biggeo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://biggeo.gitbook.io/biggeo/biggeo-ai/understanding-tokens-and-credits.md).

# Understanding Tokens & Credits

## <sub>**How tokens work**</sub>

Every time you ask a location question through BigGeo AI, a small number of tokens is used to run the query and return your answer. Think of it like a prepaid data plan — you have a balance, each query draws it down a little, and you top up when you need more.

## What Affects Token Usage

Queries cost more tokens when they cover larger areas, return more records, or involve complex spatial logic.

**More tokens:**

* Large geographic areas ("across the entire United States")
* High-volume results (returning thousands of records)
* Complex spatial relationships ("within 2 miles of X and near Y and in ZIP code Z")
* Broad, open-ended queries ("find everything in \[state]")

**Fewer tokens:**

* Specific locations ("near Central Park, New York")
* Count queries ("How many X are in Y?")
* Narrow geographic scope (a city, a ZIP code, a radius)
* Well-formed, specific questions

## **Tips to make your tokens go further**

* **Start narrow, then broaden.** Ask about one city before a whole state.
* **Use count queries first.** "How many hospitals are in Denver?" costs less than "List all hospitals in Denver."
* **Refine before re-running.** A clearer question gets a better answer — and doesn't burn tokens on a near-miss.
* **Be specific about geography.** "Near downtown Austin" goes further than "in Texas."

***

## **Checking Your Balance**

1. Log in to DataLab at biggeo.com
2. Go to **Account → Subscription Management**
3. Your current balance and usage history are displayed there

***

## **Buying More Tokens**

1. Go to **Account → Subscription Management**
2. Select your top-up amount
3. Tokens are added to your balance immediately

We recommend topping up before you run out. If you're on a managed plan, your CSM can set up a proactive usage alert.

***

## FAQs

<details>

<summary>Do unused tokens expire?</summary>

It depends on your plan. Some packages include expiry windows; others don't. Check your plan terms in Datalab or ask your CSM.

</details>

<details>

<summary>What happens if I run out mid-query?</summary>

The query won't complete. Top up your balance and re-run it.

</details>

<details>

<summary>Can my whole team share a token balance?</summary>

Yes — your organization's token balance is shared across all team members in your workspace.

</details>

<details>

<summary>Can I set a usage limit per user?</summary>

Contact your CSM or reach us at <support@biggeo.com> to discuss team-level controls.

</details>