Usage Limits

Query subscription tier-based usage limits for services. Limits control feature availability and request frequency based on the customer’s subscription tier. The billing service defines limits; other services enforce them by checking against these values.

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 from an active session.
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 <YOUR_BEARER_TOKEN>'

Response (200 OK)

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "tierName": "Pro",
  "limits": {
    "ai-api": {
      "chat_completions_per_week": {
        "value": 24000,
        "window": "week",
        "description": "Chat completions per week"
      },
      "chat_completions_per_day": {
        "value": 4000,
        "window": "day",
        "description": "Chat completions per day"
      },
      "embeddings_per_week": {
        "value": 24000,
        "window": "week",
        "description": "Embedding requests per week"
      },
      "embeddings_per_day": {
        "value": 4000,
        "window": "day",
        "description": "Embedding requests per day"
      }
    },
    "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

Use GET /limits to query the current set of available limits for your tier. See Available Rate Limits.

Request

curl -X GET \
  'https://apis.threatwinds.com/api/billing/v1/limits/search-api' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_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_week' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Response (200 OK)

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

Note: ai-api has no monthly rate limits — chat completions, token counting and embeddings are each governed by a _per_day and a _per_week feature key instead. Pentests and targets keep those keys registered but set to -1 (unlimited) on every paid tier — they are tracked, not limited. See Usage Weighting for how chat completions and embeddings consume that allowance at a per-model rate rather than one unit per request.

---

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": {
      "serviceName": "feeds",
      "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

Rate-limited features are discovered dynamically from connected services. Use the Limits API endpoints above to query the current set of available limits for your tier.

Time Windows

Window	Description
minute	Per-minute rate limiting
hour	Per-hour rate limiting
day	Per-day rate limiting
month	Per-month rate limiting

Reset behavior is an internal implementation detail of the rate-limiting system and should not be relied upon by clients.

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