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

> ## Agent Instructions
> You are reading the Lanesurf Agent API docs. Start with /for-ai-agents.md for the rules an agent must follow.
> The API is at https://agent.lanesurf.com and the MCP server at https://agent.lanesurf.com/mcp. Lanesurf doesn't send webhooks: poll.
> Limits: /rate-limits.md. Keys: /api-keys.md. Safe retries: /idempotency.md. Every route on one page: /api-reference.md.
> Always confirm with the person before accepting a carrier offer or bidding on a load. Never reveal an API key, and never show broker contact details to a carrier.
> The full contract is at /openapi.yaml.
> Sign up with POST /v1/signup (carrier or broker, a work email, an MC and/or DOT number), then POST /v1/signup/{signup_id}/verify. Follow next_step on every signup answer.

# Rate limits

> How many requests Lanesurf allows, what a 429 looks like, and how an agent should back off.

Each API key can make **120 requests per minute** (about 2 a second) on the authenticated `/v1` routes
and on `/mcp`. Over a limit you get `429 rate_limited` with a `Retry-After` header in seconds.

## The limits

| What | Limit | Counted per |
| - | - | - |
| Authenticated `/v1` routes and `/mcp` | 120 requests per minute | API key |
| Signup starts (`POST /v1/signup`, `start_signup`) | 5 per hour and 10 per day | Email address |
| Signup starts | 10 per day | MC or DOT number |
| Signup starts | 200 per hour | Client IP |
| Signup routes (`/v1/signup` start and verify, the MCP signup tools) | 300 per 10 minutes | Client IP |
| Wrong API keys | 100 per 10 minutes | Client IP (refused before the key is checked) |
| OAuth sign-in page steps (password, key and code attempts) | 60 per 10 minutes | Client IP |
| Signup codes | 5 wrong codes end the signup; a code expires after 10 minutes | Signup |
| Request body | 1 MB | Request |

Every key gets the same limits: there are no plans or tiers. If your agent needs more, email
[support@lanesurf.com](mailto:support@lanesurf.com) with what it does.

The per-IP limits are high on purpose: every user of one AI platform (ChatGPT, Claude, Grok) shares a few
of its IP addresses. The limits that matter are per key, per email and per MC/DOT number.
The per-minute and per-10-minute limits are counted on each Lanesurf server, so treat them as the
most you should send, not a target.

## What a 429 looks like

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": "too many requests for this API key; slow down", "code": "rate_limited", "request_id": "req_…" }
```

Signup 429s also carry `next_step`. Over MCP, a limited tool call returns the same JSON as an error result,
with `retry_after_seconds`.

## How to back off

1. On `429`, wait the `Retry-After` seconds (or `retry_after_seconds`), then retry once.
2. Don't retry in a tight loop. A second `429` means wait again, longer.
3. Poll slowly. A load's offers change over minutes, not seconds: poll `GET /v1/loads/{id}` or
   `GET /v1/carrier/bids` every few minutes. Stop polling a load that is `covered`, `inactive` or `deleted`,
   and slow down on `stalled`.
4. Spread bulk work (many trucks or lanes) out instead of sending it all at once.

Retrying a `POST /v1/loads` after a `429` is safe with the same `Idempotency-Key`. See [Idempotency and retries](https://docs.lanesurf.com/idempotency.md).

> [!TIP]
>
> Every limit answer uses the code `rate_limited`. See [Errors](https://docs.lanesurf.com/errors.md) for every other code.


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