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:

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

{
  "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.

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

{
  "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 to discuss your requirements.

Need Help?

Check our Error Handling guide
Contact support@tamradar.com

Introduction / Overview

Getting Started

Core Guides

Agentic Setup

API Reference

Bulk

Webhooks

Authentication & Rate Limits

Authentication & Rate Limits

API Key Authentication

Using Your API Key

Authentication Errors

Rate Limits

Standard Limits

How limits are counted

Async bulk behavior

Synchronous bulk deactivation

Response headers

Handling Rate Limits

Bulk sizing limits

Enterprise Options

Need Help?

​Authentication & Rate Limits

​API Key Authentication

​Using Your API Key

​Authentication Errors

​Rate Limits

​Standard Limits

​How limits are counted

​Async bulk behavior

​Synchronous bulk deactivation

​Response headers

​Handling Rate Limits

​Bulk sizing limits

​Enterprise Options

​Need Help?

Authentication & Rate Limits

API Key Authentication

Using Your API Key

Authentication Errors

Rate Limits

Standard Limits

How limits are counted

Async bulk behavior

Synchronous bulk deactivation

Response headers

Handling Rate Limits

Bulk sizing limits

Enterprise Options

Need Help?