Usage Limits
Query subscription tier-based usage limits for services. Limits control feature availability and usage quotas based on the customer’s subscription tier.
Get All Customer Limits
Retrieve all tier limits for the authenticated customer organized by service.
Endpoint: https://apis.threatwinds.com/api/billing/v1/limits
Method: GET
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Required Roles
Required role: owner, admin, or user
All authenticated customer members can query limits.
Request
To retrieve all limits, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
A successful response will return all configured limits organized by service.
Success Response (200 OK)
{
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"tierName": "Professional",
"limits": {
"search-api": {
"max_searches_per_minute": {
"value": 100,
"window": "minute",
"description": "Maximum searches per minute"
},
"max_results_per_search": {
"value": 1000,
"window": "day",
"description": "Maximum results per search"
}
},
"ingest-api": {
"max_ingests_per_hour": {
"value": 500,
"window": "hour",
"description": "Maximum data ingests per hour"
}
}
}
}
Response Schema
| Field | Type | Description |
|---|---|---|
| customerId | string (UUID) | Customer unique identifier |
| tierName | string | Subscription tier name |
| limits | object | Limits organized by service name |
| limits.{service} | object | Service-specific limits |
| limits.{service}.{featureKey} | object | Feature limit details |
| limits.{service}.{featureKey}.value | integer | Limit value (-1 for unlimited) |
| limits.{service}.{featureKey}.window | string | Time window: “minute”, “hour”, “day”, “month” |
| limits.{service}.{featureKey}.description | string | Human-readable description |
Business Logic
- Retrieves customer’s subscription to get tier
- Aggregates limits from all services via service discovery
- Each limit includes value, time window, and description
- Value of -1 indicates unlimited usage
- Limits are discovered dynamically from services, not stored in database
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Customer not found or no active subscription |
Get Service-Specific Limits
Retrieve tier limits for a specific service only.
Endpoint: https://apis.threatwinds.com/api/billing/v1/limits/{serviceName}
Method: GET
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| serviceName | string | Yes | Service identifier | search-api, ingest-api, ai-api, feeds-api |
Required Roles
Required role: owner, admin, or user
Request
To retrieve limits for a specific service, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/search-api' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/search-api' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
{
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"tierName": "Professional",
"serviceName": "search-api",
"limits": {
"max_searches_per_minute": {
"value": 100,
"window": "minute",
"description": "Maximum searches per minute"
},
"max_results_per_search": {
"value": 1000,
"window": "day",
"description": "Maximum results per search"
}
}
}
Response Schema
| Field | Type | Description |
|---|---|---|
| customerId | string (UUID) | Customer unique identifier |
| tierName | string | Subscription tier name |
| serviceName | string | Service identifier |
| limits | object | Service-specific limits with value, window, description |
Business Logic
- Returns only limits for specified service
- Returns 404 if service limits not found for tier
- Queries service discovery endpoint for limit configuration
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Empty serviceName parameter |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Customer not found or service limits not configured |
Get Specific Limit Value
Retrieve a single limit value for a specific service and feature.
Endpoint: https://apis.threatwinds.com/api/billing/v1/limits/{serviceName}/{featureKey}
Method: GET
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| serviceName | string | Yes | Service identifier | search-api |
| featureKey | string | Yes | Feature/limit key name | max_queries_per_month |
Required Roles
Required role: owner, admin, or user
Request
To retrieve a specific limit value, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/search-api/max_queries_per_month' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/search-api/max_queries_per_month' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
{
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"tierName": "Professional",
"serviceName": "search-api",
"featureKey": "max_searches_per_minute",
"value": 100,
"window": "minute",
"description": "Maximum searches per minute"
}
Response Schema
| Field | Type | Description |
|---|---|---|
| customerId | string (UUID) | Customer unique identifier |
| tierName | string | Subscription tier name |
| serviceName | string | Service identifier |
| featureKey | string | Feature/limit key name |
| value | integer | Limit value (-1 for unlimited) |
| window | string | Time window: “minute”, “hour”, “day”, “month” |
| description | string | Human-readable description |
Business Logic
- Returns single feature limit from service discovery
- Value of -1 indicates unlimited usage
- Window specifies the time period for the limit
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Empty path parameters |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Limit not found for service and feature combination |
Common Limit Examples
All limits follow the same structure with value, window, and description fields.
Search API Limits
| Feature Key | Window | Description |
|---|---|---|
| max_searches_per_minute | minute | Maximum search queries per minute |
| max_results_per_search | day | Maximum results returned per query |
| concurrent_searches | minute | Maximum concurrent search requests |
Ingest API Limits
| Feature Key | Window | Description |
|---|---|---|
| max_ingests_per_hour | hour | Maximum data ingests per hour |
| max_ingests_per_day | day | Daily data ingestion limit |
| batch_size_max | minute | Maximum batch size for ingestion |
Common Window Values
| Window | Description | Reset Behavior |
|---|---|---|
| minute | Per-minute rate limiting | Resets every 60 seconds |
| hour | Per-hour rate limiting | Resets every hour |
| day | Per-day quotas | Resets at midnight UTC |
| month | Per-month quotas | Resets on first day of month UTC |
Special Values
| Value | Meaning |
|---|---|
| -1 | Unlimited (no limit enforced) |
| 0 | Feature disabled |
| > 0 | Numeric limit enforced |
Using Limits in Your Application
Example: Check Query Limit Before Search
# 1. Get search API limits
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/search-api' \
-H 'Authorization: Bearer <token>'
# Response shows limits with value, window, description:
# {
# "limits": {
# "max_searches_per_minute": {
# "value": 100,
# "window": "minute",
# "description": "Maximum searches per minute"
# }
# }
# }
# 2. Track usage in your application
# 3. Show warning when approaching limit
# 4. Upgrade tier if needed via Stripe Customer Portal
Example: Check Specific Limit
# Check specific limit value
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/search-api/max_searches_per_minute' \
-H 'Authorization: Bearer <token>'
# Response:
# {
# "customerId": "550e8400-e29b-41d4-a716-446655440000",
# "tierName": "Professional",
# "serviceName": "search-api",
# "featureKey": "max_searches_per_minute",
# "value": 100,
# "window": "minute",
# "description": "Maximum searches per minute"
# }
Get All IP Rate Limits
Retrieve IP-based rate limits across all services. This is a public endpoint that doesn’t require authentication.
Endpoint: https://apis.threatwinds.com/api/billing/v1/limits/ip
Method: GET
Authentication
This is a public endpoint and does not require authentication.
Request
To retrieve all IP rate limits, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/ip' \
-H 'accept: application/json'
Response
Success Response (200 OK)
{
"ipLimits": {
"search-api": {
"serviceName": "search-api",
"tierName": "Free",
"limits": {
"max_searches_per_minute": {
"value": 10,
"window": "minute",
"description": "Maximum searches per minute for unauthenticated users"
}
}
},
"ingest-api": {
"serviceName": "ingest-api",
"tierName": "Free",
"limits": {
"max_ingests_per_hour": {
"value": 5,
"window": "hour",
"description": "Maximum ingests per hour for IPs"
}
}
}
}
}
Response Schema
| Field | Type | Description |
|---|---|---|
| ipLimits | object | IP rate limits organized by service name |
| ipLimits.{service} | object | Service-specific IP limit configuration |
| ipLimits.{service}.serviceName | string | Service identifier |
| ipLimits.{service}.tierName | string | Tier name (typically “Free” for IPs) |
| ipLimits.{service}.limits | object | Limit details with value, window, description |
Business Logic
- Public endpoint for checking IP-based rate limits
- Returns rate limits that apply to unauthenticated requests
- IP limits typically use “Free” tier configuration
- Used for API rate limiting and throttling
- Helps clients implement proper backoff strategies
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 500 | Internal Server Error | Database error or service unavailable |
Get Service-Specific IP Rate Limits
Retrieve IP-based rate limits for a specific service. This is a public endpoint that doesn’t require authentication.
Endpoint: https://apis.threatwinds.com/api/billing/v1/limits/ip/{serviceName}
Method: GET
Parameters
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| serviceName | string | Yes | Service identifier | search-api, ingest-api, ai-api, feeds-api |
Authentication
This is a public endpoint and does not require authentication.
Request
To retrieve IP rate limits for a specific service, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/ip/search-api' \
-H 'accept: application/json'
Response
Success Response (200 OK)
{
"serviceName": "search-api",
"tierName": "Free",
"limits": {
"max_searches_per_minute": {
"value": 10,
"window": "minute",
"description": "Maximum searches per minute for IPs"
}
}
}
Response Schema
| Field | Type | Description |
|---|---|---|
| serviceName | string | Service identifier |
| tierName | string | Tier name (typically “Free” for IPs) |
| limits | object | Service-specific IP rate limits with value, window, description |
Business Logic
- Returns IP-based rate limits for the specified service only
- Public endpoint for unauthenticated access
- Returns 404 if service IP limits not found
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Empty serviceName parameter |
| 404 | Not Found | Service not found or IP limits not configured |
| 500 | Internal Server Error | Database error or service unavailable |
IP Rate Limits vs Customer Limits
Understanding the difference between IP-based rate limits and customer tier limits:
| Aspect | IP Rate Limits | Customer Tier Limits |
|---|---|---|
| Authentication | Public (no auth required) | Requires authentication |
| Scope | Per IP address | Per customer account |
| Purpose | Prevent abuse, DDoS protection | Subscription tier quotas |
| Endpoints | /limits/ip/* | /limits/* |
| Time Period | Usually per hour/minute/second | Usually per month/day |
| Example | 100 requests/hour per IP | 10,000 queries/month per tier |
Example: IP Rate Limit Check
# Check IP rate limits before making unauthenticated requests
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/limits/ip/search-api' \
-H 'accept: application/json'
# Response shows:
# {
# "serviceName": "search-api",
# "tierName": "Free",
# "limits": {
# "max_searches_per_minute": {
# "value": 10,
# "window": "minute",
# "description": "Maximum searches per minute for IPs"
# }
# }
# }
# Client can track requests and implement rate limiting
# to stay within 10 searches per minute from this IP