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

# How It Works

> How Glasser retrieves data, charges for Runs, and controls access.

The same rules apply whether you use Glasser through an Agent, MCP, the CLI, or HTTP.

<span id="the-broker-model" />

## From request to data

Glasser connects you to paid data from specialist **Providers**. An **Endpoint**
is one Provider operation, with its own input schema, version, and Price.
Your Glasser Key gives you access without separate Provider accounts.

1. **Search** for an Endpoint that fits your request.
2. **Inspect** its input schema and current Price.
3. **Run** it to retrieve data. Glasser records the result and charge in a **Run**.

Search and Inspect are free. For predefined tasks,
[Solutions](/docs/api-reference/solutions/overview) can select an Endpoint and map
your input for you. Both paths use the same Runs and Workspace balance.

<span id="the-price-is-part-of-the-contract" />

## Understand the Price

Inspect shows how an Endpoint charges:

* **Successful result:** a flat amount, or a metered amount (such as per result or token) with a cap.
* **Other outcomes:** separate rules for no result, Provider errors, timeouts,
  and internal failures (`NO_RESULT`, `PROVIDER_ERROR`, `TIMED_OUT`, `INTERNAL`).

A new Run uses the Price at admission and keeps it through settlement. An
Endpoint version does not lock the Price for future Runs.

Amounts are exact USD decimal strings, such as `"0.005"`. Use decimal arithmetic,
not floating-point arithmetic, when adding them.

<span id="a-runs-life" />

## Run status

Before creating a Run, Glasser checks access and available funds, then places a
**Hold** for the maximum charge. A refused request creates no Run and no charge.
When the Run finishes, Glasser closes the Hold and records the final charge.

| Status | Meaning |
| - | - |
| `QUEUED` | Accepted and waiting for dispatch. |
| `RUNNING` | Execution is in progress. |
| `COMPLETED` | Finished with a Provider response, which can include an error. |
| `FAILED` | Finished without a usable Provider response. Read `failure` for the reason. |
| `STOPPED` | Stopped before dispatch, with no charge. |

A stop request after dispatch does not cancel the Provider's work. Read the
returned status and final charge; see [Stop a Run](/docs/api-reference/runs/stop).

<span id="two-indicators-never-one-status-and-charge" />

## Read the result and charge

Check these fields separately:

| Field | What it tells you |
| - | - |
| `status` | Whether the Run is still in progress or has finished. |
| `provider_response` | Whether the Provider returned data or an error. A Provider 404 or 500 can be a `COMPLETED` Run. |
| `charge_usd` | What the Run charged. A `FAILED` Run can still have a charge under its Price. |

<span id="idempotency-a-retry-is-a-read" />

## Retry without a second charge

After a timeout or lost connection, retry with the **same idempotency key** to
retrieve the original Run without starting or charging for another one.

* Keep `provider`, `endpoint`, `input`, and `endpoint_version` the same.
* Changing those execution parameters with the same key returns a conflict.
* Use a new key only when you intend to start another Run.

Changing `task_id` or `metadata` does not create a new Run or update the original Run.
MCP responses also include `replayed: true` for a retry; HTTP API and CLI responses return
the Run without this field.

## Keys and policy

A **Key** belongs to a **Workspace**. Runs use that Workspace's balance.

An Endpoint must be allowed by both the Workspace's Policy and the Key's Policy.
Search omits Endpoints outside that access; Inspect returns not-found for them.

## Adding funds

Add funds on the [Balance page](https://app.glasser.ai/balance?utm_source=docs\&utm_medium=how-it-works).
The API, CLI, and MCP cannot add funds.

| Way | What it takes |
| - | - |
| Top up | Pay by card. Auto-reload can repeat the payment. |
| Referral | Share your referral link. Both Workspaces receive a Grant on signup; you receive another when the new user tops up and runs something. |
| Share a Run | Share a `COMPLETED` Run to X or LinkedIn, then submit the post link to claim a Grant. Requires an earlier top-up. |

A Grant is free balance: it does not expire and spends like any other balance. Every new
Workspace starts with a signup Grant. Referral and share Grants have lifetime limits per
Workspace; the console shows the current amounts and limits. Grants appear in the balance
history with kind `grant`.

## One model, four surfaces

The same execution, billing, and policy rules apply to the [HTTP API](/docs/api-reference/endpoints/search),
the [CLI](/docs/cli), the [MCP server](/docs/mcp-server), and the agent Skill.


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