> ## 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) |
| `DELETE` | `/v1/radars/bulk` | Shared bulk bucket (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 operations** (`POST` or `DELETE /v1/radars/bulk`) share a **dedicated bulk bucket** (default 10 operations per minute per account). Each request 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.

### Synchronous bulk deactivation

`DELETE /v1/radars/bulk` returns final per-item outcomes in the same response.
It shares the bulk rate-limit bucket with bulk create, but it does not create a
pollable job or consume an additional generic DELETE token.

### 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)


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