Skip to main content

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

​
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

BucketDefault
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.
MethodEndpointsBudget used
POST/v1/radarsWrite (100/min, 10/sec)
POST/v1/radars/bulkBulk (10/min default, per account)
GET/v1/radars, /v1/radars/:id, /v1/updates, /v1/accountRead (200/min, 10/sec)
DELETE/v1/radars/:idRead (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.
HeaderMeaning
X-RateLimit-LimitYour per-minute budget for this endpoint
X-RateLimit-RemainingTokens remaining after this request
X-RateLimit-ResetSeconds until the bucket fully refills

​
Handling Rate Limits

When you exceed the rate limit you’ll receive a 429 with three headers:
HeaderMeaning
Retry-AfterSeconds until you have enough budget to retry
X-RateLimit-LimitYour per-minute budget
X-RateLimit-RemainingTokens 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?