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

# Authentication & Rate Limits

> Authentication model, request headers, and rate-limit behavior.

# Authentication & Rate Limits

## API Key Authentication

All requests to TAMradar API must include your API key. This key uniquely identifies your account and authorizes access to our services.

### Using Your API Key

Include your API key in the `x-api-key` header with every request:

```bash theme={null}
# Example GET request
curl "https://api.tamradar.com/v1/radars" \
     -H "x-api-key: YOUR_API_KEY"

# Example POST request
curl -X POST "https://api.tamradar.com/v1/radars" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "domain": "example.com",
       "radar_type": "company_job_openings"
     }'
```

### Authentication Errors

If authentication fails, you'll receive a 401 response:

```json theme={null}
{
  "status": "error",
  "code": 401,
  "message": "Invalid or inactive API key",
  "errors": [{ "field": "x-api-key", "reason": "Invalid or inactive API key" }],
  "timestamp": "2024-01-01T12:00:00Z",
  "error_id": "f72ac8d3-4bca-4f4c-b14a-30af90e3eac2"
}
```

## Rate Limits

### Standard Limits

| Bucket                     | Default                       |
| -------------------------- | ----------------------------- |
| Write (create radars)      | 100 per minute, 10 per second |
| Read (GET radars, updates) | 200 per minute, 10 per second |

Higher limits are available on enterprise plans. Contact [support@tamradar.com](mailto:support@tamradar.com).

### How limits are counted

There are two separate budgets, write and read, so a heavy polling client doesn't eat into your creation budget.

| Method   | Endpoints                                                    | Budget used                        |
| -------- | ------------------------------------------------------------ | ---------------------------------- |
| `POST`   | `/v1/radars`                                                 | Write (100/min, 10/sec)            |
| `POST`   | `/v1/radars/bulk`                                            | Bulk (10/min default, per account) |
| `GET`    | `/v1/radars`, `/v1/radars/:id`, `/v1/updates`, `/v1/account` | Read (200/min, 10/sec)             |
| `DELETE` | `/v1/radars/:id`                                             | Read (200/min, 10/sec)             |

**Single creates** (`POST /v1/radars`) deduct 1 token from your per-minute write budget and 1 from your per-second burst budget.

**Bulk submissions** (`POST /v1/radars/bulk`) use a **dedicated bulk bucket** (default 10 submissions per minute per account). Each submission consumes **1 bulk token** regardless of item count.

### Async bulk behavior

Bulk requests are queued asynchronously (`202 Accepted` with `bulk_id`). Item outcomes are produced later through:

* `GET /v1/radars/bulk/:bulk_id`
* Webhook events (`radar_created`, `radar_failure`, `bulk_completed`)

Because item processing is async, you do not receive synchronous per-item `201/207/402/409` bulk responses.

### Response headers

Successful requests include rate-limit headers when applicable. For bulk submissions, `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` are guaranteed on `429`.

| Header                  | Meaning                                  |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Your per-minute budget for this endpoint |
| `X-RateLimit-Remaining` | Tokens remaining after this request      |
| `X-RateLimit-Reset`     | Seconds until the bucket fully refills   |

### Handling Rate Limits

When you exceed the rate limit you'll receive a `429` with three headers:

| Header                  | Meaning                                       |
| ----------------------- | --------------------------------------------- |
| `Retry-After`           | Seconds until you have enough budget to retry |
| `X-RateLimit-Limit`     | Your per-minute budget                        |
| `X-RateLimit-Remaining` | Tokens available right now                    |

The `reason` field tells you which bucket fired:

* `minute` — per-minute budget exhausted, wait `Retry-After` seconds
* `burst` — per-second burst limit hit, retry in 1 second

```json theme={null}
{
  "status": "error",
  "code": 429,
  "message": "Per-minute rate limit exceeded. Retry after 51 seconds.",
  "errors": [{ "field": "rate_limit", "reason": "minute" }],
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### Bulk sizing limits

Async bulk currently allows:

* up to 1000 items per request
* request body up to 1MB

If either limit is exceeded, the request is rejected with `400`.

## Enterprise Options

For higher volume needs, we offer customized plans with:

* Increased rate limits
* Priority support

Contact [support@tamradar.com](mailto:support@tamradar.com) to discuss your requirements.

### Need Help?

* Check our [Error Handling](/guides/error-handling) guide
* Contact [support@tamradar.com](mailto:support@tamradar.com)