Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.byteful.com/llms.txt

Use this file to discover all available pages before exploring further.

The Byteful API supports powerful search operators that enable advanced filtering beyond simple exact matching. These operators let you craft precise queries to find exactly what you need.

​
Available Operators

The following operators are available when searching across most resources:
OperatorDescriptionSupported TypesExample
min_Greater than or equal (≥)Numbers, Timestamps, Datesmin_proxy_user_residential_bytes_limit=1000000
max_Less than or equal (≤)Numbers, Timestamps, Datesmax_proxy_user_residential_bytes_used=500000
like_Contains substring (case-insensitive)Stringslike_service_name=%residential%
not_Not equalAll typesnot_proxy_user_is_deleted=true
exists_Checks Metadata key existenceMetadata keysproxy_user_metadata.exists_client_id=1

​
Using Numeric Comparison Operators

​
Minimum Value (min_)

The min_ prefix finds items where the specified field is greater than or equal to the value: 
GET /public/user/service/search?min_service_quantity=10
This returns services with a quantity of 10 or more.

​
Text Search Operators

​
Substring Matching (like_)

The like_ prefix performs a case-insensitive substring search. You can use the % wildcard character to match any sequence of characters: 
GET /public/user/service/search?like_service_name=%premium%
This returns services with “premium” anywhere in their name (e.g., “Premium ISP”, “ISP Premium Plan”, “premium service”).
The like_ operator is case-insensitive, so like_service_name=%PREMIUM% will also match “premium”, “Premium”, and any other case variation.

​
Boolean Operators

​
Negative Matching (not_)

The not_ prefix finds items where the field does not equal the specified value: 
GET /public/user/proxy/search?not_country_id=us
This returns proxies that are not located in the United States.

​
Existence Operators

​
Key Existence Check (exists_)

For metadata fields, you can check if a key exists: 
GET /public/user/proxy_user/search?proxy_user_metadata.exists_department=1
This returns proxy users that have a “department” key in their metadata.

​
Combining Multiple Filters

You can combine multiple operators in a single request to create complex queries: 
GET /public/user/proxy/search?proxy_type=isp&country_id=gb&not_country_id=us
This returns active ISP proxies in Great Britain created after January 1, 2023.
When you combine multiple filters, they are joined with AND logic. All conditions must be met for an item to be included in the results.

​
Code Examples

# Text search with like operator - find 'premium' services
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/service/search?like_service_name=%premium%' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

# Negative matching - find proxies outside the US
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/proxy/search?not_country_id=us' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

# Minimum value - find services with at least 10 units
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/service/search?min_service_quantity=10' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

# Metadata existence check - find proxy users with department metadata
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/proxy_user/search?proxy_user_metadata.exists_department=true' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'