# Docs

Source page: https://excessionlabs.ai/docs/

Install Incursion, sign in, and call the Excession API.

## Install

```
# macOS and Linux
curl -fsSL https://excessionlabs.ai/install.sh | sh

# Windows (PowerShell)
irm https://excessionlabs.ai/install.ps1 | iex
```

The script installs Incursion and puts the `excession` command in `~/.local/bin` (Windows: `%LOCALAPPDATA%\Excession\bin`). Set `EXCESSION_INSTALL_DIR` to choose another folder, or `EXCESSION_VERSION` to pin a version.

## Sign in

```
excession
```

On first launch you choose one of the two models, then browser sign-in opens. Your Excession plan credit and balance pay for usage. The defaults are 12 workers and high reasoning.

```
excession login              # sign in again
excession whoami             # plan credit, balance and available
excession billing            # open Billing to add funds or pick a plan
excession billing --use-balance on   # use balance after plan credit
excession logout             # revoke this device login
```

The CLI shows a code like `BCDF-GHJK` and opens [excessionlabs.ai/device](https://excessionlabs.ai/device). Check that the code matches, then press **Approve**. The CLI receives its own API key; you can revoke it on the [API keys](https://excessionlabs.ai/app/keys) page.

Signing in creates your account with $5 API credit, once per new account. No card required. Use it for your first requests, then add funds from $0.50 or pick a plan in [Billing](https://excessionlabs.ai/app/billing). Using the service means you accept the [Acceptable Use Policy](https://excessionlabs.ai/aup/).

## Models and reasoning

`/model` (or `/models`) lists `deepseek/deepseek-v4.1-flash-1017` and `deepseek-v4.1-flash-abliterated`. Both run through the Excession API. `/effort high` sets reasoning directly; `/effort` opens the picker.

The app is fullscreen. Scroll messages with the wheel or PgUp/PgDn; the composer stays at the bottom. Ctrl+End follows the latest message.

## Plan credit and balance

You pay in US dollars. A plan gives plan credit each month; **Add funds** adds balance. Without a plan, requests use your balance.

| Option | You pay | Plan credit or balance | Extra | Unused money |
| --- | --- | --- | --- | --- |
| Pay as you go | **Add funds**: $0.50 to $1,000, card or crypto | Same amount as balance | 0% | Never expires |
| Starter | $20/month | $30/month | +50% | Ends at renewal |
| Pro | $100/month | $175/month | +75% | Ends at renewal |
| Max | $200/month | $400/month | +100% | Ends at renewal |
| Ultra | $500/month | $1,250/month | +150% | Ends at renewal |

Balance never expires while your account is open, including after you cancel a plan. Each plan covers one person.

### Debit order

| Order | Money | When it is empty |
| --- | --- | --- |
| 1st | Plan credit | Balance pays next. If **Use balance after plan credit** is off: HTTP 402 `balance_use_off` |
| 2nd | Balance | HTTP 402 `insufficient_funds` |

The setting is on by default. Change it in [Billing](https://excessionlabs.ai/app/billing) or with `excession billing --use-balance off`. **Available** is what requests can spend now.

### Alerts

The console and the CLI warn you at 80% and 95% of plan credit, when requests move to your balance, and when money is low.

Set **Email me when available funds fall below** in Billing (default $5). We send the email once, and again only after you add funds.

[Streaming latency: measured timings, errors and raw data](https://excessionlabs.ai/blog/deepseek-api-latency-sample/).

### Prices

USD per 1M tokens

| Model, USD per 1M tokens | Input | Cached input | Output |
| --- | --- | --- | --- |
| DeepSeek V4.1 Flash | $0.035 | $0.005 | $0.50 |
| DeepSeek V4.1 Flash Abliterated | $0.20 | $0.025 | $0.80 |

Output includes reasoning tokens. Plans and pay as you go use the same prices. [Compare models](https://excessionlabs.ai/api#models) or [estimate your monthly API cost](https://excessionlabs.ai/api#cost).

A request holds an input estimate plus its maximum output (16,384 tokens by default), then releases what it does not use. If a request does not fit what is available, lower its maximum output.

### Money fields

Field names for each money value in `GET /v1/me` and in an HTTP 402 body.

| Value | GET /v1/me | HTTP 402 body |
| --- | --- | --- |
| Plan credit per month | `plan.credit_usd` | — |
| Plan credit left | `plan.credit_left_usd` | `plan_credit_left_usd` |
| New plan credit on | `plan.resets_at` | `resets_at` |
| Balance | `balance_usd` | `balance_usd` |
| Balance use on or off | `balance_use_enabled` | — |
| Available now | `available_usd` | `available_usd` |
| Cost of the request | — | `required_usd` |
| Where to add funds | `billing_url` | `billing_url` |
| Account state | `state`: `ok`, `low`, `no_funds`, `plan_80`, `plan_95`, `plan_used_balance` or `plan_used_balance_off` | `state`: `ok`, `low`, `no_funds`, `plan_80`, `plan_95`, `plan_used_balance` or `plan_used_balance_off` |

## Referrals

Every account has one referral link, `https://excessionlabs.ai/r/<code>`. Find it on the [Invite](https://excessionlabs.ai/app/invite) page in the console, or run `excession invite`.

| Their first payment | They get, once | You get |
| --- | --- | --- |
| Add funds, for example $50 | 10%: $5.00 | $10.00 |
| Starter, $20 | $2.00 | $10.00 |
| Pro, $100 | $10.00 | $15.00 |
| Max, $200 | $20.00 | $25.00 |
| Ultra, $500 | $50.00 | $50.00 |

- Both rewards go to the balance when the first payment clears. A refund or dispute reverses both.

- A visit to your link counts for 30 days, and only for a new account.

- At most $500.00 of rewards per month (UTC) for each person who invites. Self-referral does not count, including with the same card or Stripe customer.

Each step shows in Activity. See the [Terms](https://excessionlabs.ai/terms/#referrals) for the full rules.

## API

Base URL `https://api.excessionlabs.ai/v1` (also served at `https://excessionlabs.ai/v1`). Send your key as `Authorization: Bearer exl_...` or `x-api-key: exl_...`.

| Endpoint | Format |
| --- | --- |
| `POST /v1/chat/completions` | OpenAI Chat Completions |
| `POST /v1/responses` | OpenAI Responses |
| `POST /v1/messages` | Anthropic Messages |
| `GET /v1/models` | Model list with prices |
| `GET /v1/me` | Account: plan credit, balance and available |

All three formats support streaming and tool calls. Every response carries an `X-Request-Id` header; non-streaming responses also carry `X-Cost-Usd`.

```
curl https://api.excessionlabs.ai/v1/chat/completions \
  -H "Authorization: Bearer $EXCESSION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"hello"}]}'
```

### Errors

Money errors are always HTTP 402. Retrying does not help until you add funds or change the setting. 429 is never a money error: it means a rate limit or a busy model.

| Status | code | Meaning |
| --- | --- | --- |
| 401 | `invalid_api_key` | Missing, wrong or revoked key. |
| 402 | `insufficient_funds` | Not enough funds for this request. Add funds at the `billing_url` in the body, or reduce max output. |
| 402 | `balance_use_off` | Plan credit is used up and you have a balance, but balance use is off. Turn on **Use balance after plan credit** or run `excession billing --use-balance on`. |
| 429 | `rate_limited` / `model_busy` | More than 600 requests per minute on one key, or the model is busy. Wait for `Retry-After` seconds. |
| 503 | `service_unavailable` | Temporary. You were not charged. |

A 402 body gives the numbers in the [money fields](https://excessionlabs.ai/docs/#me).

## Device login for tool builders

Any client can sign in the way the CLI does, using the OAuth 2.0 Device Authorization Grant (RFC 8628).

```
POST /v1/device/code   {"client_name": "excession-cli 0.1 on my-laptop"}
→ {"device_code", "user_code": "BCDF-GHJK", "verification_uri", "verification_uri_complete", "expires_in": 900, "interval": 5}

POST /v1/device/token  {"device_code": "...", "grant_type": "urn:ietf:params:oauth:grant-type:device_code"}
→ 400 {"error": "authorization_pending"}   keep polling every interval seconds
→ 400 {"error": "slow_down"}               add 5 seconds to the interval
→ 400 {"error": "access_denied" | "expired_token"}
→ 200 {"access_token": "exl_...", "token_type": "Bearer", "key_id", "email"}
```

Open `verification_uri_complete` in the browser. The API returns the key once; store it with file mode 0600.