Usage Limits

Query subscription tier-based usage limits for services. Limits control feature availability and request frequency based on the customer’s subscription tier. Limits are enforced automatically on every API request.

How Rate Limits Work

Rate limits are enforced per customer account (or per IP for unauthenticated requests). Each limit has a time window (minute, hour, day, or month) that defines the reset period. When a limit is exceeded, the API returns 429 Too Many Requests.

Authenticated requests: Limits are based on the customer’s subscription tier
Unauthenticated requests: IP-based limits apply (typically the “Public” tier)
Unlimited features: A value of -1 means no limit is enforced
Disabled features: A value of 0 means the feature is not available for that tier

Get All Customer Limits

Retrieve all tier limits for the authenticated customer organized by service.

Endpoint: GET https://apis.threatwinds.com/api/billing/v1/limits

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

owner, admin, or user

Request

curl -X GET \
  'https://apis.threatwinds.com/api/billing/v1/limits' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Response (200 OK)

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "tierName": "Pro",
  "limits": {
    "ai-api": {
      "chat_completions_per_month": {
        "value": 5000,
        "window": "month",
        "description": "Chat completions per month"
      },
      "embeddings_per_month": {
        "value": 5000,
        "window": "month",
        "description": "Embedding requests per month"
      }
    },
    "search-api": {
      "entity_lookup_per_minute": {
        "value": 200,
        "window": "minute",
        "description": "Entity lookup requests per minute"
      },
      "simple_search_per_minute": {
        "value": 60,
        "window": "minute",
        "description": "Simple search requests per minute"
      }
    },
    "compute-api": {
      "create_instance_per_minute": {
        "value": 5,
        "window": "minute",
        "description": "Instance creation per minute"
      }
    }
  }
}

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}.{featureKey}.value	integer	Limit value (-1 for unlimited, 0 for disabled)
limits.{service}.{featureKey}.window	string	Time window: `minute`, `hour`, `day`, `month`
limits.{service}.{featureKey}.description	string	Human-readable description

Get Service-Specific Limits

Retrieve tier limits for a specific service only.

Endpoint: GET https://apis.threatwinds.com/api/billing/v1/limits/{serviceName}

Path Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service identifier

Available services: ai-api, search-api, analytics-api, compute-api, feeds-api

Request

curl -X GET \
  'https://apis.threatwinds.com/api/billing/v1/limits/search-api' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Response (200 OK)

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "tierName": "Pro",
  "serviceName": "search-api",
  "limits": {
    "entity_lookup_per_minute": {
      "value": 200,
      "window": "minute",
      "description": "Entity lookup requests per minute"
    },
    "entity_relations_per_minute": {
      "value": 60,
      "window": "minute",
      "description": "Entity relations requests per minute"
    },
    "simple_search_per_minute": {
      "value": 60,
      "window": "minute",
      "description": "Simple search requests per minute"
    },
    "advanced_search_per_minute": {
      "value": 30,
      "window": "minute",
      "description": "Advanced search requests per minute"
    },
    "history_search_per_minute": {
      "value": 30,
      "window": "minute",
      "description": "History search requests per minute"
    },
    "advanced_history_search_per_minute": {
      "value": 20,
      "window": "minute",
      "description": "Advanced history search requests per minute"
    },
    "comments_per_minute": {
      "value": 100,
      "window": "minute",
      "description": "Comments requests per minute"
    }
  }
}

Get Specific Limit Value

Retrieve a single limit value for a specific service and feature.

Endpoint: GET https://apis.threatwinds.com/api/billing/v1/limits/{serviceName}/{featureKey}

Path Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service identifier
featureKey	string	Yes	Feature key name

Request

curl -X GET \
  'https://apis.threatwinds.com/api/billing/v1/limits/ai-api/chat_completions_per_month' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Response (200 OK)

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "tierName": "Pro",
  "serviceName": "ai-api",
  "featureKey": "chat_completions_per_month",
  "value": 5000,
  "window": "month",
  "description": "Chat completions per month"
}

Get All IP Rate Limits

Retrieve IP-based rate limits across all services. This is a public endpoint that does not require authentication.

Endpoint: GET https://apis.threatwinds.com/api/billing/v1/limits/ip

Request

curl -X GET \
  'https://apis.threatwinds.com/api/billing/v1/limits/ip' \
  -H 'accept: application/json'

Response (200 OK)

{
  "ipLimits": {
    "search-api": {
      "serviceName": "search-api",
      "tierName": "Public",
      "limits": {
        "entity_lookup_per_minute": {
          "value": 10,
          "window": "minute",
          "description": "Entity lookup requests per minute"
        },
        "simple_search_per_minute": {
          "value": 3,
          "window": "minute",
          "description": "Simple search requests per minute"
        }
      }
    },
    "feeds-api": {
      "serviceName": "feeds-api",
      "tierName": "Public",
      "limits": {
        "feed_list_per_minute": {
          "value": 10,
          "window": "minute",
          "description": "Feed list requests per minute"
        }
      }
    }
  }
}

Get Service-Specific IP Rate Limits

Retrieve IP-based rate limits for a specific service. Public endpoint, no authentication required.

Endpoint: GET https://apis.threatwinds.com/api/billing/v1/limits/ip/{serviceName}

Path Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service identifier

Request

curl -X GET \
  'https://apis.threatwinds.com/api/billing/v1/limits/ip/search-api' \
  -H 'accept: application/json'

Response (200 OK)

{
  "serviceName": "search-api",
  "tierName": "Public",
  "limits": {
    "entity_lookup_per_minute": {
      "value": 10,
      "window": "minute",
      "description": "Entity lookup requests per minute"
    }
  }
}

Available Rate Limits by Service

AI API (`ai-api`)

Feature Key	Window	Description
chat_completions_per_month	month	Chat completions per month
token_count_per_month	month	Token count requests per month
audio_transcriptions_per_minute	minute	Audio transcriptions per minute
audio_speech_per_minute	minute	Audio speech requests per minute
embeddings_per_month	month	Embedding requests per month
pentests_per_month	month	Pentests per month
targets_per_pentest	month	Targets per pentest
targets_per_month	month	Targets per month

Search API (`search-api`)

Feature Key	Window	Description
entity_lookup_per_minute	minute	Entity lookup requests per minute
entity_relations_per_minute	minute	Entity relations requests per minute
simple_search_per_minute	minute	Simple search requests per minute
advanced_search_per_minute	minute	Advanced search requests per minute
history_search_per_minute	minute	History search requests per minute
advanced_history_search_per_minute	minute	Advanced history search requests per minute
comments_per_minute	minute	Comments requests per minute

Analytics API (`analytics-api`)

Feature Key	Window	Description
entity_details_per_minute	minute	Entity details requests per minute
entity_relations_per_minute	minute	Entity relations requests per minute

Compute API (`compute-api`)

Feature Key	Window	Description
create_instance_per_minute	minute	Instance creation per minute
list_instances_per_minute	minute	List instances per minute
get_instance_per_minute	minute	Get instance per minute
delete_instance_per_minute	minute	Delete instance per minute
start_instance_per_minute	minute	Start instance per minute
stop_instance_per_minute	minute	Stop instance per minute
restart_instance_per_minute	minute	Restart instance per minute
reset_instance_per_minute	minute	Reset instance per minute
list_templates_per_minute	minute	List templates per minute
list_template_zones_per_minute	minute	List template zones per minute

Feeds API (`feeds-api`)

Feature Key	Window	Description
feed_list_per_minute	minute	Feed list requests per minute
feed_download_per_hour	hour	Feed downloads per hour
checksum_download_per_minute	minute	Checksum downloads per minute

Time Windows

Window	Description	Reset Behavior
minute	Per-minute rate limiting	Resets at the start of each minute (UTC)
hour	Per-hour rate limiting	Resets at the start of each hour (UTC)
day	Per-day rate limiting	Resets at midnight UTC
month	Per-month rate limiting	Resets on the first day of each month (UTC)

Special Values

Value	Meaning
-1	Unlimited (no limit enforced)
0	Feature disabled for this tier
> 0	Numeric limit enforced

Rate Limit Response

When a rate limit is exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
x-error: rate limit exceeded
x-error-id: <unique-error-id>

To recover, wait for the current time window to reset or upgrade your subscription tier.

Error Codes

Status Code	Description	Possible Cause
200	OK	Request successful
400	Bad Request	Invalid or empty parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Service or feature not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Usage Limits

How Rate Limits Work

Get All Customer Limits

Headers

Required Roles

Request

Response (200 OK)

Response Schema

Get Service-Specific Limits

Path Parameters

Request

Response (200 OK)

Get Specific Limit Value

Path Parameters

Request

Response (200 OK)

Get All IP Rate Limits

Request

Response (200 OK)

Get Service-Specific IP Rate Limits

Path Parameters

Request

Response (200 OK)

Available Rate Limits by Service

AI API (ai-api)

Search API (search-api)

Analytics API (analytics-api)

Compute API (compute-api)

Feeds API (feeds-api)

Time Windows

Special Values

Rate Limit Response

Error Codes

AI API (`ai-api`)

Search API (`search-api`)

Analytics API (`analytics-api`)

Compute API (`compute-api`)

Feeds API (`feeds-api`)