# Authentication
Source: https://documentation.byteful.com/api-basics/authentication
Authenticating with the Byteful API
The Byteful API uses API keys for authentication. Each request must include both your public and private API keys in the request headers. This ensures that only authorized users can access the API.
## API Keys
You'll need to use two keys for authentication:
* **Public API Key**: Identifies your account
* **Private API Key**: Verifies your identity (keep this secure)
These keys must be included in the headers of every request to the API.
## Authentication Headers
Include the following headers in all your API requests:
| Header | Description |
| ------------------- | -------------------- |
| `X-API-Public-Key` | Your public API key |
| `X-API-Private-Key` | Your private API key |
## Security Best Practices
* **Never share your private key**: Keep your private API key confidential
* **Use environment variables**: Store keys in environment variables rather than hardcoding them
* **Rotate keys periodically**: Change your API keys regularly as a security best practice
## Basic Authentication Example
This example shows how to authenticate and retrieve customer information using the `/customer/retrieve` endpoint:
```bash cURL theme={null}
# Basic authentication and customer information retrieval
curl --request GET \
--url 'https://api.byteful.com/1.0/public/customer/retrieve' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
```python Python theme={null}
import requests
import json
# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.byteful.com/1.0/public"
# Headers for authentication
headers = {
"X-API-Public-Key": API_PUBLIC_KEY,
"X-API-Private-Key": API_PRIVATE_KEY
}
# Retrieve customer information
def get_customer_info():
url = f"{BASE_URL}/user/customer/retrieve"
response = requests.get(url, headers=headers)
# Parse the response
data = response.json()
# Check for errors
if response.status_code != 200:
error_message = data.get('message', 'Unknown error')
api_request_id = data.get('api_request_id', 'None')
error_code = data.get('code', 'None')
raise Exception(f"Error {error_code}: {error_message} (Request ID: {api_request_id})")
return data
# Example usage
if __name__ == "__main__":
try:
customer_info = get_customer_info()
print("Authentication successful!")
print(f"Customer information: {json.dumps(customer_info, indent=2)}")
except Exception as e:
print(f"Authentication failed: {e}")
```
```javascript JavaScript theme={null}
// API credentials
const API_PUBLIC_KEY = 'your_public_key';
const API_PRIVATE_KEY = 'your_private_key';
const BASE_URL = 'https://api.byteful.com/1.0/public';
// Headers for authentication
const headers = {
'X-API-Public-Key': API_PUBLIC_KEY,
'X-API-Private-Key': API_PRIVATE_KEY
};
// Retrieve customer information
async function getCustomerInfo() {
const url = `${BASE_URL}/user/customer/retrieve`;
const response = await fetch(url, { headers });
const data = await response.json();
// Check for errors
if (!response.ok) {
const errorMessage = data.message || 'Unknown error';
const apiRequestId = data.api_request_id || 'None';
const errorCode = data.code || 'None';
throw new Error(`Error ${errorCode}: ${errorMessage} (Request ID: ${apiRequestId})`);
}
return data;
}
// Example usage
async function main() {
try {
const customerInfo = await getCustomerInfo();
console.log('Authentication successful!');
console.log('Customer information:', JSON.stringify(customerInfo, null, 2));
} catch (error) {
console.error(`Authentication failed: ${error.message}`);
}
}
main();
```
```php PHP theme={null}
getMessage() . "\n";
}
?>
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
// API credentials
const (
apiPublicKey = "your_public_key"
apiPrivateKey = "your_private_key"
baseURL = "https://api.byteful.com/1.0/public"
)
// ApiError represents an error response from the API
type ApiError struct {
Code string `json:"code"`
Message string `json:"message"`
ApiRequestID string `json:"api_request_id"`
}
// CustomerResponse represents the customer info API response
type CustomerResponse struct {
Message string `json:"message"`
Data interface{} `json:"data"`
}
// GetCustomerInfo retrieves authenticated customer information
func GetCustomerInfo() (interface{}, error) {
url := baseURL + "/user/customer/retrieve"
// Create a new request
req, err := http.NewRequest("GET", url, nil)
if err != nil {
return nil, err
}
// Add authentication headers
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Read the response body
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
// Check for errors
if resp.StatusCode != 200 {
var apiError ApiError
if err := json.Unmarshal(body, &apiError); err != nil {
return nil, fmt.Errorf("API request failed with status code: %d", resp.StatusCode)
}
return nil, fmt.Errorf("Error %s: %s (Request ID: %s)",
apiError.Code, apiError.Message, apiError.ApiRequestID)
}
// Parse the response
var response CustomerResponse
if err := json.Unmarshal(body, &response); err != nil {
return nil, err
}
return response, nil
}
func main() {
customerInfo, err := GetCustomerInfo()
if err != nil {
fmt.Printf("Authentication failed: %v\n", err)
return
}
// Format the output as JSON
customerJSON, _ := json.MarshalIndent(customerInfo, "", " ")
fmt.Println("Authentication successful!")
fmt.Printf("Customer information: %s\n", string(customerJSON))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
public class PingProxiesAuthentication {
// API credentials
private static final String API_PUBLIC_KEY = "your_public_key";
private static final String API_PRIVATE_KEY = "your_private_key";
private static final String BASE_URL = "https://api.byteful.com/1.0/public";
private static final HttpClient client = HttpClient.newHttpClient();
private static final ObjectMapper mapper = new ObjectMapper();
// API Error class
@JsonIgnoreProperties(ignoreUnknown = true)
static class ApiError {
public String code;
public String message;
@JsonProperty("api_request_id")
public String apiRequestId;
}
// Customer response class
@JsonIgnoreProperties(ignoreUnknown = true)
static class CustomerResponse {
public String message;
public Object data;
}
// Retrieve customer information
public static CustomerResponse getCustomerInfo() throws IOException, InterruptedException {
String url = BASE_URL + "/user/customer/retrieve";
// Create the request with authentication headers
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.GET()
.build();
// Execute the request
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
// Check for errors
if (response.statusCode() != 200) {
ApiError error = mapper.readValue(response.body(), ApiError.class);
throw new IOException(String.format("Error %s: %s (Request ID: %s)",
error.code, error.message, error.apiRequestId));
}
// Parse the response
return mapper.readValue(response.body(), CustomerResponse.class);
}
public static void main(String[] args) {
try {
CustomerResponse customerInfo = getCustomerInfo();
System.out.println("Authentication successful!");
System.out.println("Customer information: " +
mapper.writerWithDefaultPrettyPrinter().writeValueAsString(customerInfo));
} catch (Exception e) {
System.out.println("Authentication failed: " + e.getMessage());
}
}
}
```
## Troubleshooting Authentication Issues
If you encounter authentication errors, check the following:
| Error | Possible Cause | Solution |
| ---------------- | ---------------- | ------------------------------------------------------- |
| 401 Unauthorized | Invalid API keys | Verify your API keys are correct and properly formatted |
| No response | Network issues | Check your network connection and firewall settings |
## API Key Management
You can manage your API keys through the Byteful dashboard:
1. Log in to your account
2. Navigate to the API Keys section
3. View your current keys or generate new ones
# Error Handling
Source: https://documentation.byteful.com/api-basics/error-handling
Understanding and handling errors in the Byteful API
The Byteful API uses standard HTTP status codes and consistent error response formats to help you identify and resolve issues with your API requests.
## Error Response Format
All API errors follow a consistent JSON format:
```json theme={null}
{
"error": "Error Type",
"message": "Human-readable error description",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Error Response Fields
| Field | Description |
| ---------------- | ---------------------------------------------------------------------------- |
| `error` | A short string identifying the error type |
| `message` | A human-readable description of what went wrong |
| `api_request_id` | A unique identifier for the request that can be used when contacting support |
## HTTP Status Codes
The API uses the following HTTP status codes for error responses:
| Status Code | Error Type | Description |
| ----------- | --------------------- | --------------------------------------------------------------------------- |
| 400 | Bad Request | The request was invalid or improperly formatted |
| 401 | Unauthorized | Authentication credentials were missing or invalid |
| 403 | Forbidden | Authentication succeeded but you don't have permission |
| 404 | Not Found | The requested resource doesn't exist |
| 409 | Conflict | The request conflicts with the current state |
| 422 | Unprocessable Entity | The request was well-formed but couldn't be processed due to business logic |
| 429 | Too Many Requests | You've exceeded the rate limit |
| 500 | Internal Server Error | Something went wrong on our servers |
## Common Error Types
### Authentication Errors (401)
```json theme={null}
{
"error": "Unauthorized",
"message": "API key authentication is required.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Permission Errors (403)
```json theme={null}
{
"error": "Forbidden",
"message": "You don't have permission to access this resource.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Resource Not Found (404)
```json theme={null}
{
"error": "Not Found",
"message": "The requested proxy could not be found.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Validation Errors (400)
```json theme={null}
{
"error": "Bad Request",
"message": "The proxy_user_id field is required.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Conflict Errors (409)
```json theme={null}
{
"error": "Conflict",
"message": "A proxy user with this ID already exists.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Business Logic Errors (422)
```json theme={null}
{
"error": "Unprocessable",
"message": "This service cannot be canceled before the minimum contract period.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Rate Limit Errors (429)
```json theme={null}
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please try again in 45 seconds.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
### Server Errors (500)
```json theme={null}
{
"error": "Internal Server Error",
"message": "An unexpected error occurred. Please try again later.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
## Error Handling Best Practices
### 1. Check HTTP Status Codes
Always check the HTTP status code first to understand the general category of error:
* 4xx errors indicate client-side issues (your request)
* 5xx errors indicate server-side issues (our systems)
### 2. Parse Error Messages
Error messages provide specific information about what went wrong. Parse them to:
* Display to users when appropriate
* Log for debugging
* Handle programmatically
### 3. Include Request ID in Support Inquiries
Always include the `api_request_id` when contacting support about an API error. This helps us quickly locate the specific request in our logs.
By following these error handling best practices, you can build robust applications that gracefully manage API errors and provide a better experience for your users.
# Rate Limiting
Source: https://documentation.byteful.com/api-basics/rate-limiting
Understanding and working with API rate limits
To ensure fair usage and system stability, the Byteful API implements rate limiting. This page explains our rate limits and how to work with them effectively.
## Rate Limit Policy
The Byteful API enforces a default rate limit of **10 requests per second** per customer. This applies to most endpoints, with some exceptions:
* Some resource-intensive endpoints may have lower rate limits
Rate limiting helps us:
* Protect the API from excessive traffic
* Ensure fair access for all users
* Maintain reliable service performance
## Rate Limit Exceeded Response
If you exceed the rate limit, you'll receive a `429 Too Many Requests` response with a body like:
```json theme={null}
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please try again later.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
## Increase Your Rate Limit
We can customize rate limits on a per-customer basis with proper justification.
Contact our development team at [developers@byteful.com](mailto:developers@byteful.com) to discuss your specific needs.
# Structure
Source: https://documentation.byteful.com/api-basics/structure
Understanding the Byteful API structure, URL patterns, HTTP methods, and data formats
The Byteful API follows RESTful principles with consistent URL patterns, standard HTTP methods, and JSON-formatted requests and responses. This page explains the core structural components of the API.
## Base URL
All API requests should be made to the following base URL:
```
https://api.byteful.com/1.0/
```
## URL Structure
The API URLs follow a consistent pattern:
```
/[version]/[scope]/[resource]/[action]/[identifier]
```
### Components
| Component | Description | Examples |
| ------------ | ----------------------------- | -------------------------------------- |
| `version` | API version | `1.0` |
| `scope` | Access level | `public`, `private` |
| `resource` | The resource type | `proxy`, `service`, `proxy_user` |
| `action` | Operation to perform | `retrieve`, `search`, `create`, `edit` |
| `identifier` | Resource ID (when applicable) | `{proxy_id}`, `{service_id}` |
All Public API therefore follow this URL format:
```
https://api.byteful.com/1.0/public/user/[resource]/[action]/[identifier]
```
### Example URLs
```
/1.0/public/user/proxy/search
/1.0/public/user/proxy/retrieve/{proxy_id}
/1.0/public/user/proxy_user/create
/1.0/public/user/service/edit/{service_id}
```
## HTTP Methods
The API uses standard HTTP methods to perform different actions:
| Method | Description | Example Usage |
| -------- | ------------- | ---------------------------------------------- |
| `GET` | Retrieve data | Fetch a proxy, list services, search resources |
| `POST` | Create data | Create a new proxy user, generate a checkout |
| `PATCH` | Update data | Edit a proxy user, update service metadata |
| `DELETE` | Remove data | Cancel a service, delete a proxy user |
**Inconsistent HTTP Method**: The route `POST /public/user/proxy/list_by_id` violates the established HTTP method convention.
According to the convention, retrieval operations should use the GET method, but this endpoint uses POST for a retrieval operation. This is an intentional deviation to support sending large lists of UUIDs in the request body, which wouldn't be practical with query parameters in a GET request.
### Method and URL Mapping
The HTTP method and URL structure work together to define the operation:
| Operation | HTTP Method | URL Pattern | Example |
| ----------- | ----------- | -------------------------------------------------- | ------------------------------- |
| List/Search | `GET` | `/resource/search` | `GET /proxy/search` |
| Retrieve | `GET` | `/resource/retrieve/{id}` | `GET /proxy/retrieve/123` |
| Create | `POST` | `/resource/create` | `POST /proxy_user/create` |
| Update | `PATCH` | `/resource/edit/{id}` | `PATCH /service/edit/123` |
| Delete | `DELETE` | `/resource/delete/{id}` or `/resource/cancel/{id}` | `DELETE /proxy_user/delete/123` |
## Request Format
### Headers
All requests should include the following headers:
| Header | Description | Required |
| ------------------- | ------------------------------------------- | -------------- |
| `X-API-Public-Key` | Your public API key | Yes |
| `X-API-Private-Key` | Your private API key | Yes |
| `Content-Type` | `application/json` for requests with a body | For POST/PATCH |
### Request Body
For `POST` and `PATCH` requests, data should be sent as JSON in the request body:
```json theme={null}
{
"proxy_user_id": "example_user",
"proxy_user_password": "secure_password",
"proxy_user_metadata": {
"department": "Marketing",
"project": "Q2 Campaign"
}
}
```
### Query Parameters
For `GET` requests, parameters are passed in the URL query string:
```
/proxy/search?country_id=us&proxy_type=datacenter&page=1&per_page=25
```
Common query parameters include:
| Parameter | Description | Example |
| ---------- | ---------------------------------------- | -------------------------------- |
| `page` | Page number for pagination | `page=2` |
| `per_page` | Items per page | `per_page=50` |
| `sort_by` | Field to sort by with optional direction | `sort_by=creation_datetime_desc` |
## Response Format
All API responses are JSON objects with a consistent structure:
```json theme={null}
{
"data": {
// Resource data or array of resources
},
"message": "Operation successful message",
"page": 1, // Only in paginated responses
"per_page": 25, // Only in paginated responses
"total_count": 157, // Only in paginated responses
"item_count": 25 // Only in paginated responses
}
```
### Success Responses
Successful responses include:
* HTTP status code in the 200 range
* `data` field containing the requested resource(s)
* `message` field with a success message
Example of a successful retrieve operation:
```json theme={null}
{
"data": {
"proxy_id": "abc123",
"proxy_ip_address": "192.168.1.1",
"proxy_status": "active"
// Additional fields...
},
"message": "Proxy successfully retrieved."
}
```
Example of a successful search operation:
```json theme={null}
{
"data": [
{
"proxy_id": "abc123",
"proxy_ip_address": "192.168.1.1"
// Additional fields...
},
{
"proxy_id": "def456",
"proxy_ip_address": "192.168.1.2"
// Additional fields...
}
],
"message": "Proxy search successful.",
"page": 1,
"per_page": 25,
"total_count": 157,
"item_count": 25
}
```
### Error Responses
Error responses include:
* HTTP status code in the 400 or 500 range
* `error` field with the error type
* `message` field with a description of the error
* `api_request_id` field for reference when contacting support
Example error response:
```json theme={null}
{
"error": "Bad Request",
"message": "The proxy_user_id field is required.",
"api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}
```
## HTTP Status Codes
The API uses standard HTTP status codes to indicate the result of a request:
| Code | Description | Common Scenarios |
| ---- | --------------------- | -------------------------------------------------------- |
| 200 | OK | Successful GET, PATCH operations |
| 201 | Created | Successful POST operation |
| 400 | Bad Request | Invalid parameters or data |
| 401 | Unauthorized | Invalid or missing authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource already exists |
| 422 | Unprocessable Entity | Valid request but operation failed due to business logic |
| 500 | Internal Server Error | Server-side error |
## Data Types
The API uses standard JSON data types:
| Type | JSON Representation | Example |
| -------- | --------------------- | ------------------------------------------------------ |
| String | `"text"` | `"proxy_type": "datacenter"` |
| Number | `123` or `123.45` | `"proxy_http_port": 8080` |
| Boolean | `true` or `false` | `"proxy_user_is_strict_security": true` |
| Object | `{ "key": "value" }` | `"proxy_user_metadata": { "department": "Marketing" }` |
| Array | `[ value1, value2 ]` | `"restricted_service_ids": ["123-456", "789-012"]` |
| Null | `null` | `"service_promotional_code": null` |
| Datetime | `2023-09-15 00:00:00` | `"service_creation_datetime": "2023-09-15 00:00:00"` |
## Date and Time Format
All date and time values in the API use the format below:
```
YYYY-MM-DDT hh:mm:ss
```
Example: `"2023-09-15 14:30:00"`
When filtering by dates, you can use:
* Format: `2023-09-15 14:30:00`
* Date only: `2023-09-15`
# Changelog
Source: https://documentation.byteful.com/api-changelog
What we've changed and added to Byteful. A straightforward timeline of our improvements.
## List proxies with the OS parameter and retrieve active node counts
* Residential & Mobile list endpoints now accept an list\_os parameter within the options of windows, linux, and android.
* A generated Residential or Mobile proxy with an OS target will utilize a proxy node with that Operating System.
* The same node counts you are used to with geo-located proxies are available for OS parameter selection.
## Filter Proxies by Availability
* Proxy search now accepts a `proxy_is_online` parameter. Pass `proxy_is_online=true` to return only proxies whose subnet is currently online, so proxies affected by an ongoing network incident are left out of your list.
* `proxy_is_online=false` returns only the affected proxies, and omitting the parameter returns all proxies as before.
## Multi Location Checkout
* Public checkout routes now support new syntax for multi location checkout; backwards compatibility maintained for old syntax.
* Proxy Username & Proxy Password fields deprecated; please use Proxy User authentication.
* Public service routes now return associated `service_line_item` objects in the response.
## Improved Proxy Observability and Debugging
* Proxy error code returned under `x-byteful-status-code` header.
* Proxy request ID returned under `x-byteful-request-id` header.
* More informative proxy error codes.
## Mobile Proxies Support
* Added new endpoints to support mobile proxies.
* Changes to the customer object to include mobile proxies information.
## Analytics Changes
* We may now summarise hostnames in the format \*.hostname.TLD when we detect high cardinality between a large number of hostnames. This will improve observability performance for customers with lots of logs.
## Proxy List Options & Proxy User ID Search
* Added proxy list options for more flexible proxy listing configurations.
* Added ability to search proxies by proxy user ID.
## Bug Fixes & Minor Improvements
* Fixed analytics route hourly interval bug
## Improved Proxy User Authentication System, Speed Improvements & Bug Fixs
* Added Proxy User ACL routes for fine grained proxy user access control by service ID or proxy ID.
* Stock retrieval is now much faster. This speeds up several endpoints.
* Customer promotion system added.
* Various bugs fixed.
## Proxy Testing add to API
* Endpoint added to search for available proxy testing servers
* Endpoint added to create a proxy test run and test proxies against a list of URL's
## Residential Availability Counts added to API
* Endpoints added to view online peer counts by country, state, asn and other variables.
## New Residential Generation Options Added
* Residential list generation endpoint now supports US States and global zip codes along with AI Optimization features.
## Breakdown Analytics Endpoint Added
* Endpoint which provides proxy analytics broken down by hostname, proxy user and network.
## KYC Support Added
* Changes to customer object to support KYC levels and verification. KYC level can be seen in the public API but verifications must be initiated via the dashboard.
## Bug Fixes & Minor Improvements
* Pagination total\_count value now supports -1 value to indicate large number of objects which can not be fully counted.
## Bug Fixes & Minor Improvements
* Fixed error responses and formating in specific routes
## Bug Fixes
* Repeated automatic overage refund bug fixed
## Automatic Overage Refunds
* Data overages, where bytes exceed an opposed limit, are now refunded via automatic entries to the residential ledgr with type `overage_adjustment`
## Bug Fixes & Minor Improvements
* Fixed subnet\_id proxy filtering issue
* Apply default sorting rules for all objects based on alphabetical name order or creation datetime desc, depending
* Fixes to Checkout API endpoints and service\_fulfillment\_filter searching
* Proxy object updates to show proxy\_user\_ids list
# Metadata
Source: https://documentation.byteful.com/api-core-features/metadata
Using and working with metadata in the Byteful API
Metadata provides a flexible way to store additional information with your resources. The Byteful API supports metadata on several resources, allowing you to add custom attributes without changing the core API structure.
Metadata is particularly useful for resellers who want to store information about their customers on our systems, or users who want to label or add information to specific proxy users or services.
## Supported Resources with Metadata
The following resources support metadata fields:
* **Proxy Users** (`proxy_user_metadata`)
* **Services** (`service_metadata`)
## Metadata Structure
Metadata is stored as a JSON object with key-value pairs. For example:
```json theme={null}
{
"customer_reference_id": "CR-12345",
"department": "Marketing",
"project": "Q2 Campaign",
"is_priority": true,
"employee_id": 1500
}
```
## Supported Value Types
Metadata supports the following value types:
* **String**: Text values (e.g., `"department": "Marketing"`)
* **Integer**: Whole numbers (e.g., `"employee_id": 1500`)
* **Float**: Decimal numbers (e.g., `"success_rate": 98.6`)
* **Boolean**: True/false values (e.g., `"is_priority": true`)
To store datetime objects, we recommend using timestamps as integers since they're more efficiently stored and queried. They can also be compared using the min\_ and max\_ operators.
## Constraints
When working with metadata in the Byteful API, keep these constraints in mind:
* **Non-nested structure**: Metadata must be a flat JSON object (no nested objects)
* **Limited keys**: Maximum of 30 keys per metadata object
* **Value length**: Each value's string representation must be ≤ 300 characters
* **Size limit**: Total metadata size must be ≤ 32KB
* **Supported value types**: String, boolean, float, and integer values
## Adding Metadata
You can add metadata when creating or updating resources. For example, when creating a proxy user:
```json theme={null}
{
"proxy_user_id": "stevejobs",
"proxy_user_metadata": {
"department": "Marketing",
"cost_center": "CC-45678",
"manager": "Jane Smith"
}
}
```
## Updating Metadata
When updating metadata, you must provide the complete metadata object. The API will replace the existing metadata with your new object, not merge them.
For example, to update a service's metadata:
```json theme={null}
{
"service_metadata": {
"project": "Updated Project Name",
"department": "Sales",
"priority": "high"
}
}
```
## Searching by Metadata
The API allows filtering resources based on their metadata values. This is particularly powerful for organizing and retrieving resources based on your custom attributes.
### Metadata Search Operators
When searching, you can use the following formats:
* **Exact match**: `proxy_user_metadata.department=Marketing`
* **Minimum value**: `proxy_user_metadata.min_employee_id=1000`
* **Maximum value**: `proxy_user_metadata.max_employee_id=2000`
* **Contains substring**: `proxy_user_metadata.like_project=%Campaign%`
* **Not equal**: `proxy_user_metadata.not_department=IT`
* **Existence check**:
* `proxy_user_metadata.exists_project=true` (key must exist)
* `proxy_user_metadata.exists_project=false` (key must not exist)
## Code Examples
```bash cURL theme={null}
# Creating a proxy user with metadata
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_id": "john_marketing",
"proxy_user_metadata": {
"department": "Marketing",
"cost_center": "CC-45678",
"project": "Summer Campaign",
"is_priority": true,
"employee_id": 1500
}
}'
# Updating a service's metadata
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/service/update' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"service_id": "srv-12345",
"service_metadata": {
"project": "Fall Campaign",
"department": "Sales",
"priority": "high"
}
}'
# Searching for proxy users in the Marketing department
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/search?proxy_user_metadata.department=Marketing' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
# Searching for high-priority services
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/service/search?proxy_user_metadata.priority=high' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
```python Python theme={null}
import requests
import json
# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.byteful.com/1.0/public/user"
# Headers for authentication
headers = {
"X-API-Public-Key": API_PUBLIC_KEY,
"X-API-Private-Key": API_PRIVATE_KEY,
"Content-Type": "application/json"
}
# Create a proxy user with metadata
def create_proxy_user_with_metadata(proxy_user_id, metadata):
url = f"{BASE_URL}/proxy_user/create"
payload = {
"proxy_user_id": proxy_user_id,
"proxy_user_metadata": metadata
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
return response.json()
# Update a service's metadata
def update_service_metadata(service_id, metadata):
url = f"{BASE_URL}/service/update"
payload = {
"service_id": service_id,
"service_metadata": metadata
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
return response.json()
# Search for proxy users by metadata
def search_proxy_users_by_metadata(metadata_key, metadata_value):
url = f"{BASE_URL}/proxy_user/search"
params = {
f"proxy_user_metadata.{metadata_key}": metadata_value
}
response = requests.get(url, headers=headers, params=params)
return response.json()
# Example usage
if __name__ == "__main__":
# Create a proxy user with metadata
user_metadata = {
"department": "Marketing",
"cost_center": "CC-45678",
"project": "Summer Campaign",
"is_priority": True,
"employee_id": 1500
}
create_result = create_proxy_user_with_metadata("john_marketing", user_metadata)
print(f"Created proxy user: {create_result}")
# Update a service's metadata
service_metadata = {
"project": "Fall Campaign",
"department": "Sales",
"priority": "high"
}
update_result = update_service_metadata("srv-12345", service_metadata)
print(f"Updated service metadata: {update_result}")
# Search for proxy users in the Marketing department
search_result = search_proxy_users_by_metadata("department", "Marketing")
print(f"Found {search_result['total_count']} proxy users in Marketing")
```
```javascript JavaScript theme={null}
// API credentials
const API_PUBLIC_KEY = 'your_public_key';
const API_PRIVATE_KEY = 'your_private_key';
const BASE_URL = 'https://api.byteful.com/1.0/public/user';
// Headers for authentication
const headers = {
'X-API-Public-Key': API_PUBLIC_KEY,
'X-API-Private-Key': API_PRIVATE_KEY,
'Content-Type': 'application/json'
};
// Create a proxy user with metadata
async function createProxyUserWithMetadata(proxyUserId, metadata) {
const url = `${BASE_URL}/proxy_user/create`;
const payload = {
proxy_user_id: proxyUserId,
proxy_user_metadata: metadata
};
const response = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(payload)
});
return await response.json();
}
// Update a service's metadata
async function updateServiceMetadata(serviceId, metadata) {
const url = `${BASE_URL}/service/update`;
const payload = {
service_id: serviceId,
service_metadata: metadata
};
const response = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(payload)
});
return await response.json();
}
// Search for proxy users by metadata
async function searchProxyUsersByMetadata(metadataKey, metadataValue) {
const url = new URL(`${BASE_URL}/proxy_user/search`);
url.searchParams.append(`proxy_user_metadata.${metadataKey}`, metadataValue);
const response = await fetch(url, { headers });
return await response.json();
}
// Example usage
async function main() {
try {
// Create a proxy user with metadata
const userMetadata = {
department: 'Marketing',
cost_center: 'CC-45678',
project: 'Summer Campaign',
is_priority: true,
employee_id: 1500
};
const createResult = await createProxyUserWithMetadata('john_marketing', userMetadata);
console.log(`Created proxy user: ${JSON.stringify(createResult)}`);
// Update a service's metadata
const serviceMetadata = {
project: 'Fall Campaign',
department: 'Sales',
priority: 'high'
};
const updateResult = await updateServiceMetadata('srv-12345', serviceMetadata);
console.log(`Updated service metadata: ${JSON.stringify(updateResult)}`);
// Search for proxy users in the Marketing department
const searchResult = await searchProxyUsersByMetadata('department', 'Marketing');
console.log(`Found ${searchResult.total_count} proxy users in Marketing`);
} catch (error) {
console.error('Error working with metadata:', error);
}
}
main();
```
```php PHP theme={null}
$proxyUserId,
'proxy_user_metadata' => $metadata
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Update a service's metadata
function updateServiceMetadata($baseUrl, $headers, $serviceId, $metadata) {
$url = $baseUrl . '/service/update';
$payload = json_encode([
'service_id' => $serviceId,
'service_metadata' => $metadata
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Search for proxy users by metadata
function searchProxyUsersByMetadata($baseUrl, $headers, $metadataKey, $metadataValue) {
$url = $baseUrl . '/proxy_user/search?proxy_user_metadata.' . $metadataKey . '=' . urlencode($metadataValue);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Example usage
try {
// Create a proxy user with metadata
$userMetadata = [
'department' => 'Marketing',
'cost_center' => 'CC-45678',
'project' => 'Summer Campaign',
'is_priority' => true,
'employee_id' => 1500
];
$createResult = createProxyUserWithMetadata($baseUrl, $headers, 'john_marketing', $userMetadata);
echo "Created proxy user: " . json_encode($createResult) . "\n";
// Update a service's metadata
$serviceMetadata = [
'project' => 'Fall Campaign',
'department' => 'Sales',
'priority' => 'high'
];
$updateResult = updateServiceMetadata($baseUrl, $headers, 'srv-12345', $serviceMetadata);
echo "Updated service metadata: " . json_encode($updateResult) . "\n";
// Search for proxy users in the Marketing department
$searchResult = searchProxyUsersByMetadata($baseUrl, $headers, 'department', 'Marketing');
echo "Found " . $searchResult['total_count'] . " proxy users in Marketing\n";
} catch (Exception $e) {
echo "Error working with metadata: " . $e->getMessage() . "\n";
}
?>
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
// API credentials
const (
apiPublicKey = "your_public_key"
apiPrivateKey = "your_private_key"
baseURL = "https://api.byteful.com/1.0/public/user"
)
// Response structure for API
type ApiResponse struct {
Message string `json:"message"`
Data json.RawMessage `json:"data"`
}
// SearchResponse structure for search endpoints
type SearchResponse struct {
Data []map[string]interface{} `json:"data"`
ItemCount int `json:"item_count"`
Message string `json:"message"`
Page int `json:"page"`
PerPage int `json:"per_page"`
TotalCount int `json:"total_count"`
}
// CreateProxyUserWithMetadata creates a proxy user with metadata
func CreateProxyUserWithMetadata(proxyUserId string, metadata map[string]interface{}) (*ApiResponse, error) {
url := baseURL + "/proxy_user/create"
// Create the payload
payload := map[string]interface{}{
"proxy_user_id": proxyUserId,
"proxy_user_metadata": metadata,
}
payloadBytes, err := json.Marshal(payload)
if err != nil {
return nil, err
}
// Create the request
req, err := http.NewRequest("POST", url, bytes.NewBuffer(payloadBytes))
if err != nil {
return nil, err
}
// Add headers
req.Header.Add("Content-Type", "application/json")
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Read and parse the response
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var response ApiResponse
err = json.Unmarshal(body, &response)
if err != nil {
return nil, err
}
return &response, nil
}
// UpdateServiceMetadata updates a service's metadata
func UpdateServiceMetadata(serviceId string, metadata map[string]interface{}) (*ApiResponse, error) {
url := baseURL + "/service/update"
// Create the payload
payload := map[string]interface{}{
"service_id": serviceId,
"service_metadata": metadata,
}
payloadBytes, err := json.Marshal(payload)
if err != nil {
return nil, err
}
// Create the request
req, err := http.NewRequest("POST", url, bytes.NewBuffer(payloadBytes))
if err != nil {
return nil, err
}
// Add headers
req.Header.Add("Content-Type", "application/json")
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Read and parse the response
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var response ApiResponse
err = json.Unmarshal(body, &response)
if err != nil {
return nil, err
}
return &response, nil
}
// SearchProxyUsersByMetadata searches for proxy users by metadata
func SearchProxyUsersByMetadata(metadataKey, metadataValue string) (*SearchResponse, error) {
requestURL := fmt.Sprintf("%s/proxy_user/search?proxy_user_metadata.%s=%s",
baseURL, metadataKey, url.QueryEscape(metadataValue))
// Create the request
req, err := http.NewRequest("GET", requestURL, nil)
if err != nil {
return nil, err
}
// Add headers
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Read and parse the response
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var response SearchResponse
err = json.Unmarshal(body, &response)
if err != nil {
return nil, err
}
return &response, nil
}
func main() {
// Create a proxy user with metadata
userMetadata := map[string]interface{}{
"department": "Marketing",
"cost_center": "CC-45678",
"project": "Summer Campaign",
"is_priority": true,
"employee_id": 1500,
}
createResult, err := CreateProxyUserWithMetadata("john_marketing", userMetadata)
if err != nil {
fmt.Printf("Error creating proxy user: %v\n", err)
} else {
fmt.Printf("Created proxy user: %s\n", createResult.Message)
}
// Update a service's metadata
serviceMetadata := map[string]interface{}{
"project": "Fall Campaign",
"department": "Sales",
"priority": "high",
}
updateResult, err := UpdateServiceMetadata("srv-12345", serviceMetadata)
if err != nil {
fmt.Printf("Error updating service metadata: %v\n", err)
} else {
fmt.Printf("Updated service metadata: %s\n", updateResult.Message)
}
// Search for proxy users in the Marketing department
searchResult, err := SearchProxyUsersByMetadata("department", "Marketing")
if err != nil {
fmt.Printf("Error searching for proxy users: %v\n", err)
} else {
fmt.Printf("Found %d proxy users in Marketing\n", searchResult.TotalCount)
}
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
public class PingProxiesMetadata {
// API credentials
private static final String API_PUBLIC_KEY = "your_public_key";
private static final String API_PRIVATE_KEY = "your_private_key";
private static final String BASE_URL = "https://api.byteful.com/1.0/public/user";
private static final HttpClient client = HttpClient.newHttpClient();
private static final ObjectMapper mapper = new ObjectMapper();
// Basic API response
static class ApiResponse {
public String message;
public Object data;
}
// Search response
static class SearchResponse {
public List> data;
@JsonProperty("item_count")
public int itemCount;
public String message;
public int page;
@JsonProperty("per_page")
public int perPage;
@JsonProperty("total_count")
public int totalCount;
}
// Create a proxy user with metadata
public static ApiResponse createProxyUserWithMetadata(String proxyUserId, Map metadata)
throws IOException, InterruptedException {
String url = BASE_URL + "/proxy_user/create";
// Create the payload
Map payload = new HashMap<>();
payload.put("proxy_user_id", proxyUserId);
payload.put("proxy_user_metadata", metadata);
String jsonPayload = mapper.writeValueAsString(payload);
// Create the request
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
.build();
// Execute the request
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return mapper.readValue(response.body(), ApiResponse.class);
}
// Update a service's metadata
public static ApiResponse updateServiceMetadata(String serviceId, Map metadata)
throws IOException, InterruptedException {
String url = BASE_URL + "/service/update";
// Create the payload
Map payload = new HashMap<>();
payload.put("service_id", serviceId);
payload.put("service_metadata", metadata);
String jsonPayload = mapper.writeValueAsString(payload);
// Create the request
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
.build();
// Execute the request
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return mapper.readValue(response.body(), ApiResponse.class);
}
// Search for proxy users by metadata
public static SearchResponse searchProxyUsersByMetadata(String metadataKey, String metadataValue)
throws IOException, InterruptedException {
String encodedValue = URLEncoder.encode(metadataValue, StandardCharsets.UTF_8);
String url = BASE_URL + "/proxy_user/search?proxy_user_metadata." + metadataKey + "=" + encodedValue;
// Create the request
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.GET()
.build();
// Execute the request
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return mapper.readValue(response.body(), SearchResponse.class);
}
public static void main(String[] args) {
try {
// Create a proxy user with metadata
Map userMetadata = new HashMap<>();
userMetadata.put("department", "Marketing");
userMetadata.put("cost_center", "CC-45678");
userMetadata.put("project", "Summer Campaign");
userMetadata.put("is_priority", true);
userMetadata.put("employee_id", 1500);
ApiResponse createResult = createProxyUserWithMetadata("john_marketing", userMetadata);
System.out.println("Created proxy user: " + createResult.message);
// Update a service's metadata
Map serviceMetadata = new HashMap<>();
serviceMetadata.put("project", "Fall Campaign");
serviceMetadata.put("department", "Sales");
serviceMetadata.put("priority", "high");
ApiResponse updateResult = updateServiceMetadata("srv-12345", serviceMetadata);
System.out.println("Updated service metadata: " + updateResult.message);
// Search for proxy users in the Marketing department
SearchResponse searchResult = searchProxyUsersByMetadata("department", "Marketing");
System.out.println("Found " + searchResult.totalCount + " proxy users in Marketing");
} catch (Exception e) {
System.out.println("Error working with metadata: " + e.getMessage());
e.printStackTrace();
}
}
}
```
## Example Use Cases
* **Reseller customer tracking**: Store client-specific identifiers and attributes
* **Client organization**: Track which client or project a resource belongs to
* **Custom grouping**: Create your own grouping scheme beyond the API's built-in categories
* **Usage tracking**: Add purpose or usage details to track resource utilization
By effectively using metadata, you can extend the Byteful API to fit your organization's specific needs and workflows.
# Pagination
Source: https://documentation.byteful.com/api-core-features/pagination
Working with paginated responses in the Byteful API
The Byteful API uses pagination to manage large result sets efficiently. Without pagination, endpoints that return many items could slow down your application and consume unnecessary data.
## How Pagination Works
When you make a request to an endpoint that returns multiple items (like search endpoints), the API divides the results into pages and returns one page at a time. This approach:
* Improves performance for large datasets
* Reduces data consumption
* Provides more predictable response times
* Makes responses easier to process
Some /search endpoints may return total\_count as -1 in cases where the number of objects is too large to count efficiently and quickly.
## Pagination Parameters
Byteful API uses the following query parameters to control pagination:
| Parameter | Type | Description | Default |
| ---------- | ------- | ---------------------------------- | ------- |
| `page` | integer | The page number to retrieve | 1 |
| `per_page` | integer | Number of items to return per page | 100 |
### Example Request
```bash theme={null}
GET https://api.byteful.com/1.0/public/user/proxy/search?page=2&per_page=25
```
This request would retrieve the second page of proxies, with 25 proxies per page.
## Pagination Response
Paginated responses include metadata to help you navigate through all available results. Here's what you'll find in a typical paginated response:
```json theme={null}
{
"data": [
// Array of items for the current page
],
"item_count": 25, // Number of items in the current page
"message": "Search successful",
"page": 2, // Current page number
"per_page": 25, // Items per page
"total_count": 134 // Total items across all pages
}
```
### Pagination Response Fields
| Field | Description |
| ------------- | ---------------------------------------------------------------------- |
| `data` | Array containing the items for the current page |
| `item_count` | Number of items returned in the current page |
| `page` | Current page number |
| `per_page` | Number of items requested per page |
| `total_count` | Total number of items that match your search criteria across all pages |
## Calculating Total Pages
To calculate the total number of pages, use:
```
total_pages = Math.ceil(total_count / per_page)
```
## Pagination Limits
* **Minimum `per_page`**: 1
* **Maximum `per_page`**: 100
* **Default `per_page`**: 100
* **Minimum `page`**: 1
If you request a page beyond the available data, you'll receive an empty data array
## Code Examples
```bash cURL theme={null}
# Basic pagination example with cURL
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy/search?page=2&per_page=25' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
# Fetch all pages sequentially with bash
#!/bin/bash
page=1
per_page=100
total_items=0
total_pages=0
# First request to get total count
response=$(curl -s \
--url "https://api.byteful.com/1.0/public/user/proxy/search?page=${page}&per_page=${per_page}" \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key')
total_items=$(echo $response | jq -r '.total_count')
total_pages=$(( (total_items + per_page - 1) / per_page ))
echo "Total items: $total_items, Total pages: $total_pages"
# Fetch each page
for ((page=1; page<=total_pages; page++)); do
echo "Fetching page $page of $total_pages"
curl -s \
--url "https://api.byteful.com/1.0/public/user/proxy/search?page=${page}&per_page=${per_page}" \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
> "page_${page}.json"
done
```
```python Python theme={null}
import requests
import math
import asyncio
import aiohttp
# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.byteful.com/1.0/public/user/proxy/search"
# Headers for authentication
headers = {
"X-API-Public-Key": API_PUBLIC_KEY,
"X-API-Private-Key": API_PRIVATE_KEY
}
# Sequential pagination
def fetch_all_pages_sequential():
per_page = 100
page = 1
all_items = []
# Make initial request to get total count
response = requests.get(
BASE_URL,
params={"page": page, "per_page": per_page},
headers=headers
)
data = response.json()
# Calculate total pages
total_count = data["total_count"]
total_pages = math.ceil(total_count / per_page)
print(f"Found {total_count} items across {total_pages} pages")
# Add first page results
all_items.extend(data["data"])
# Fetch remaining pages
for page in range(2, total_pages + 1):
print(f"Fetching page {page} of {total_pages}")
response = requests.get(
BASE_URL,
params={"page": page, "per_page": per_page},
headers=headers
)
data = response.json()
all_items.extend(data["data"])
return all_items
# Parallel pagination with asyncio
async def fetch_page(session, page, per_page):
"""Fetch a specific page of results"""
params = {"page": page, "per_page": per_page}
async with session.get(BASE_URL, params=params, headers=headers) as response:
return await response.json()
async def fetch_all_pages_parallel(total_count, per_page=100):
"""Fetch all pages in parallel"""
total_pages = math.ceil(total_count / per_page)
all_items = []
async with aiohttp.ClientSession() as session:
# Create tasks for each page request
page_tasks = []
for page in range(1, total_pages + 1):
page_tasks.append(fetch_page(session, page, per_page))
# Run all page requests concurrently
all_results = await asyncio.gather(*page_tasks)
# Extract data from each page
for result in all_results:
all_items.extend(result["data"])
return all_items
# Usage example
async def main():
# First get total count
response = requests.get(
BASE_URL,
params={"page": 1, "per_page": 1},
headers=headers
)
data = response.json()
total_count = data["total_count"]
# Get all items in parallel
results = await fetch_all_pages_parallel(total_count)
print(f"Fetched {len(results)} items using parallel pagination")
if __name__ == "__main__":
# For sequential approach
# all_items = fetch_all_pages_sequential()
# print(f"Fetched {len(all_items)} items using sequential pagination")
# For parallel approach
asyncio.run(main())
```
```javascript JavaScript theme={null}
// Using fetch and async/await for pagination
const API_PUBLIC_KEY = 'your_public_key';
const API_PRIVATE_KEY = 'your_private_key';
const BASE_URL = 'https://api.byteful.com/1.0/public/user/proxy/search';
// Headers for authentication
const headers = {
'X-API-Public-Key': API_PUBLIC_KEY,
'X-API-Private-Key': API_PRIVATE_KEY
};
// Sequential pagination
async function fetchAllPagesSequential() {
const perPage = 100;
let page = 1;
let allItems = [];
// Make initial request to get total count
const response = await fetch(`${BASE_URL}?page=${page}&per_page=${perPage}`, { headers });
const data = await response.json();
// Calculate total pages
const totalCount = data.total_count;
const totalPages = Math.ceil(totalCount / perPage);
console.log(`Found ${totalCount} items across ${totalPages} pages`);
// Add first page results
allItems = allItems.concat(data.data);
// Fetch remaining pages
for (page = 2; page <= totalPages; page++) {
console.log(`Fetching page ${page} of ${totalPages}`);
const pageResponse = await fetch(`${BASE_URL}?page=${page}&per_page=${perPage}`, { headers });
const pageData = await pageResponse.json();
allItems = allItems.concat(pageData.data);
}
return allItems;
}
// Parallel pagination with Promise.all
async function fetchAllPagesParallel() {
const perPage = 100;
// First get total count
const countResponse = await fetch(`${BASE_URL}?page=1&per_page=1`, { headers });
const countData = await countResponse.json();
const totalCount = countData.total_count;
const totalPages = Math.ceil(totalCount / perPage);
console.log(`Found ${totalCount} items across ${totalPages} pages`);
// Create an array of promises for each page
const pagePromises = [];
for (let page = 1; page <= totalPages; page++) {
const pagePromise = fetch(`${BASE_URL}?page=${page}&per_page=${perPage}`, { headers })
.then(response => response.json())
.then(data => data.data);
pagePromises.push(pagePromise);
}
// Wait for all requests to complete
const pageResults = await Promise.all(pagePromises);
// Flatten the array of arrays into a single array
const allItems = pageResults.flat();
return allItems;
}
// Usage
async function main() {
try {
// Choose which method to use
// const allItems = await fetchAllPagesSequential();
const allItems = await fetchAllPagesParallel();
console.log(`Successfully fetched ${allItems.length} items`);
// Process your items here
} catch (error) {
console.error('Error fetching paginated data:', error);
}
}
main();
```
```php PHP theme={null}
$ch) {
$response = curl_multi_getcontent($ch);
$data = json_decode($response, true);
$allItems = array_merge($allItems, $data['data']);
// Clean up
curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);
return $allItems;
}
// Usage
try {
// Choose which method to use
// $allItems = fetchAllPagesSequential($baseUrl, $headers);
$allItems = fetchAllPagesParallel($baseUrl, $headers);
echo "Successfully fetched " . count($allItems) . " items\n";
// Process your items here
} catch (Exception $e) {
echo "Error fetching paginated data: " . $e->getMessage() . "\n";
}
?>
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"math"
"net/http"
"sync"
)
// API credentials
const (
apiPublicKey = "your_public_key"
apiPrivateKey = "your_private_key"
baseURL = "https://api.byteful.com/1.0/public/user/proxy/search"
)
// Response structure for paginated API
type PaginatedResponse struct {
Data []map[string]interface{} `json:"data"`
ItemCount int `json:"item_count"`
Message string `json:"message"`
Page int `json:"page"`
PerPage int `json:"per_page"`
TotalCount int `json:"total_count"`
}
// fetchPage retrieves a single page of results
func fetchPage(page, perPage int) (*PaginatedResponse, error) {
// Create a new request
req, err := http.NewRequest("GET", baseURL, nil)
if err != nil {
return nil, err
}
// Add query parameters
q := req.URL.Query()
q.Add("page", fmt.Sprintf("%d", page))
q.Add("per_page", fmt.Sprintf("%d", perPage))
req.URL.RawQuery = q.Encode()
// Add headers
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Read and parse the response
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var response PaginatedResponse
err = json.Unmarshal(body, &response)
if err != nil {
return nil, err
}
return &response, nil
}
// fetchAllPagesSequential retrieves all pages one after another
func fetchAllPagesSequential() ([]map[string]interface{}, error) {
perPage := 100
allItems := []map[string]interface{}{}
// Get first page to determine total count
firstPage, err := fetchPage(1, perPage)
if err != nil {
return nil, err
}
// Calculate total pages
totalCount := firstPage.TotalCount
totalPages := int(math.Ceil(float64(totalCount) / float64(perPage)))
fmt.Printf("Found %d items across %d pages\n", totalCount, totalPages)
// Add first page results
allItems = append(allItems, firstPage.Data...)
// Fetch remaining pages
for page := 2; page <= totalPages; page++ {
fmt.Printf("Fetching page %d of %d\n", page, totalPages)
pageData, err := fetchPage(page, perPage)
if err != nil {
return nil, err
}
allItems = append(allItems, pageData.Data...)
}
return allItems, nil
}
// fetchAllPagesParallel retrieves all pages concurrently
func fetchAllPagesParallel() ([]map[string]interface{}, error) {
perPage := 100
// Get first page to determine total count
firstPage, err := fetchPage(1, 1)
if err != nil {
return nil, err
}
// Calculate total pages
totalCount := firstPage.TotalCount
totalPages := int(math.Ceil(float64(totalCount) / float64(perPage)))
fmt.Printf("Found %d items across %d pages\n", totalCount, totalPages)
// Channel to collect results
resultsChan := make(chan []map[string]interface{}, totalPages)
errChan := make(chan error, totalPages)
// WaitGroup to track completion
var wg sync.WaitGroup
// Fetch all pages concurrently
for page := 1; page <= totalPages; page++ {
wg.Add(1)
go func(p int) {
defer wg.Done()
pageData, err := fetchPage(p, perPage)
if err != nil {
errChan <- err
return
}
resultsChan <- pageData.Data
}(page)
}
// Wait for all goroutines to complete
go func() {
wg.Wait()
close(resultsChan)
close(errChan)
}()
// Check for errors
select {
case err := <-errChan:
if err != nil {
return nil, err
}
default:
}
// Collect all results
allItems := []map[string]interface{}{}
for pageData := range resultsChan {
allItems = append(allItems, pageData...)
}
return allItems, nil
}
func main() {
// Choose which method to use
// allItems, err := fetchAllPagesSequential()
allItems, err := fetchAllPagesParallel()
if err != nil {
fmt.Printf("Error fetching paginated data: %v\n", err)
return
}
fmt.Printf("Successfully fetched %d items\n", len(allItems))
// Process your items here
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;
import java.util.stream.IntStream;
import com.fasterxml.jackson.databind.ObjectMapper;
public class PingProxiesPagination {
// API credentials
private static final String API_PUBLIC_KEY = "your_public_key";
private static final String API_PRIVATE_KEY = "your_private_key";
private static final String BASE_URL = "https://api.byteful.com/1.0/public/user/proxy/search";
private static final HttpClient client = HttpClient.newHttpClient();
private static final ObjectMapper mapper = new ObjectMapper();
// Response class to hold paginated data
static class PaginatedResponse {
public List> data;
public int item_count;
public String message;
public int page;
public int per_page;
public int total_count;
}
// Fetch a single page
private static PaginatedResponse fetchPage(int page, int perPage) throws IOException, InterruptedException {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "?page=" + page + "&per_page=" + perPage))
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return mapper.readValue(response.body(), PaginatedResponse.class);
}
// Fetch a single page asynchronously
private static CompletableFuture fetchPageAsync(int page, int perPage) {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "?page=" + page + "&per_page=" + perPage))
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.GET()
.build();
return client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
.thenApply(HttpResponse::body)
.thenApply(body -> {
try {
return mapper.readValue(body, PaginatedResponse.class);
} catch (IOException e) {
throw new RuntimeException(e);
}
});
}
// Sequential pagination
public static List> fetchAllPagesSequential() throws IOException, InterruptedException {
int perPage = 100;
List> allItems = new ArrayList<>();
// Get first page to determine total count
PaginatedResponse firstPage = fetchPage(1, perPage);
// Calculate total pages
int totalCount = firstPage.total_count;
int totalPages = (int) Math.ceil((double) totalCount / perPage);
System.out.printf("Found %d items across %d pages%n", totalCount, totalPages);
// Add first page results
allItems.addAll(firstPage.data);
// Fetch remaining pages
for (int page = 2; page <= totalPages; page++) {
System.out.printf("Fetching page %d of %d%n", page, totalPages);
PaginatedResponse pageData = fetchPage(page, perPage);
allItems.addAll(pageData.data);
}
return allItems;
}
// Parallel pagination
public static List> fetchAllPagesParallel() throws IOException, InterruptedException {
int perPage = 100;
// Get first page to determine total count
PaginatedResponse firstPage = fetchPage(1, 1);
// Calculate total pages
int totalCount = firstPage.total_count;
int totalPages = (int) Math.ceil((double) totalCount / perPage);
System.out.printf("Found %d items across %d pages%n", totalCount, totalPages);
// Create a list of futures for all pages
List> pageFutures =
IntStream.rangeClosed(1, totalPages)
.mapToObj(page -> fetchPageAsync(page, perPage))
.collect(Collectors.toList());
// Combine all futures into a single future that completes when all page requests are done
CompletableFuture allFutures = CompletableFuture.allOf(
pageFutures.toArray(new CompletableFuture[0])
);
// When all futures complete, collect all the items from all pages
List> allItems = allFutures.thenApply(v ->
pageFutures.stream()
.map(CompletableFuture::join)
.flatMap(response -> response.data.stream())
.collect(Collectors.toList())
).join();
return allItems;
}
public static void main(String[] args) {
try {
// Choose which method to use
// List> allItems = fetchAllPagesSequential();
List> allItems = fetchAllPagesParallel();
System.out.printf("Successfully fetched %d items%n", allItems.size());
// Process your items here
} catch (Exception e) {
System.out.println("Error fetching paginated data: " + e.getMessage());
e.printStackTrace();
}
}
}
```
## Efficient Pagination Strategies
### Sequential Paging
The simplest approach is to request page 1, then page 2, and so on. This is demonstrated in the code examples above for each language.
### Parallel Paging
For faster data collection, you can calculate the total pages and make multiple concurrent requests. This approach is particularly useful when you need to retrieve a large dataset quickly.
The parallel examples above show how to implement this pattern in different languages.
Use parallel paging cautiously to avoid rate limiting. Consider how many concurrent requests you're making to the API.
# Filter Operators
Source: https://documentation.byteful.com/api-core-features/search-operators
Advanced filtering with operators in the Byteful API
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:
| Operator | Description | Supported Types | Example |
| --------- | ------------------------------------- | -------------------------- | ------------------------------------------------ |
| `min_` | Greater than or equal (≥) | Numbers, Timestamps, Dates | `min_proxy_user_residential_bytes_limit=1000000` |
| `max_` | Less than or equal (≤) | Numbers, Timestamps, Dates | `max_proxy_user_residential_bytes_used=500000` |
| `like_` | Contains substring (case-insensitive) | Strings | `like_service_name=%residential%` |
| `not_` | Not equal | All types | `not_proxy_user_is_deleted=true` |
| `exists_` | Checks Metadata key existence | Metadata keys | `proxy_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¬_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
```bash cURL theme={null}
# 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'
```
```python Python theme={null}
import requests
# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.byteful.com/1.0/public/user"
# Headers for authentication
headers = {
"X-API-Public-Key": API_PUBLIC_KEY,
"X-API-Private-Key": API_PRIVATE_KEY
}
# Text search with like operator - find 'premium' services
def search_premium_services():
params = {"like_service_name": "%premium%"}
url = f"{BASE_URL}/service/search"
response = requests.get(url, params=params, headers=headers)
return response.json()
# Negative matching - find active proxies
def get_active_proxies():
params = {"not_proxy_status": "inactive"}
url = f"{BASE_URL}/proxy/search"
response = requests.get(url, params=params, headers=headers)
return response.json()
# Minimum value - find services with at least 10 units
def get_services_min_quantity(min_quantity=10):
params = {"min_service_quantity": min_quantity}
url = f"{BASE_URL}/service/search"
response = requests.get(url, params=params, headers=headers)
return response.json()
# Metadata existence check - find proxy users with department metadata
def get_users_with_department():
params = {"proxy_user_metadata.exists_department": "1"}
url = f"{BASE_URL}/proxy_user/search"
response = requests.get(url, params=params, headers=headers)
return response.json()
# Example usage
if __name__ == "__main__":
premium_services = search_premium_services()
non_us_proxies = get_non_us_proxies()
high_quantity_services = get_services_min_quantity(10)
users_with_dept = get_users_with_department()
print(f"Premium services: {premium_services['total_count']}")
print(f"Non-US proxies: {non_us_proxies['total_count']}")
print(f"Services with 10+ units: {high_quantity_services['total_count']}")
print(f"Users with department metadata: {users_with_dept['total_count']}")
```
```javascript JavaScript theme={null}
// API credentials
const API_PUBLIC_KEY = 'your_public_key';
const API_PRIVATE_KEY = 'your_private_key';
const BASE_URL = 'https://api.byteful.com/1.0/public/user';
// Headers for authentication
const headers = {
'X-API-Public-Key': API_PUBLIC_KEY,
'X-API-Private-Key': API_PRIVATE_KEY
};
// Text search with like operator - find 'premium' services
async function searchPremiumServices() {
const url = new URL(`${BASE_URL}/service/search`);
url.searchParams.append('like_service_name', '%premium%');
const response = await fetch(url, { headers });
return await response.json();
}
// Negative matching - find active proxies
async function getActiveProxies() {
const url = new URL(`${BASE_URL}/proxy/search`);
url.searchParams.append('not_proxy_status', 'inactive');
const response = await fetch(url, { headers });
return await response.json();
}
// Minimum value - find services with at least 10 units
async function getServicesMinQuantity(minQuantity = 10) {
const url = new URL(`${BASE_URL}/service/search`);
url.searchParams.append('min_service_quantity', minQuantity);
const response = await fetch(url, { headers });
return await response.json();
}
// Metadata existence check - find proxy users with department metadata
async function getUsersWithDepartment() {
const url = new URL(`${BASE_URL}/proxy_user/search`);
url.searchParams.append('proxy_user_metadata.exists_department', '1');
const response = await fetch(url, { headers });
return await response.json();
}
// Example usage
async function main() {
try {
const premiumServices = await searchPremiumServices();
const nonUsProxies = await getNonUsProxies();
const highQuantityServices = await getServicesMinQuantity(10);
const usersWithDept = await getUsersWithDepartment();
console.log(`Premium services: ${premiumServices.total_count}`);
console.log(`Non-US proxies: ${nonUsProxies.total_count}`);
console.log(`Services with 10+ units: ${highQuantityServices.total_count}`);
console.log(`Users with department metadata: ${usersWithDept.total_count}`);
} catch (error) {
console.error('Error fetching filtered data:', error);
}
}
main();
```
```php PHP theme={null}
getMessage() . "\n";
}
?>
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
// API credentials
const (
apiPublicKey = "your_public_key"
apiPrivateKey = "your_private_key"
baseURL = "https://api.byteful.com/1.0/public/user"
)
// Response structure for API
type ApiResponse struct {
Data []map[string]interface{} `json:"data"`
ItemCount int `json:"item_count"`
Message string `json:"message"`
Page int `json:"page"`
PerPage int `json:"per_page"`
TotalCount int `json:"total_count"`
}
// makeRequest is a helper function to make API requests
func makeRequest(requestURL string) (*ApiResponse, error) {
// Create a new request
req, err := http.NewRequest("GET", requestURL, nil)
if err != nil {
return nil, err
}
// Add headers
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Read and parse the response
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var response ApiResponse
err = json.Unmarshal(body, &response)
if err != nil {
return nil, err
}
return &response, nil
}
// SearchPremiumServices finds services with "premium" in the name
func SearchPremiumServices() (*ApiResponse, error) {
requestURL := fmt.Sprintf("%s/service/search?like_service_name=%s", baseURL, url.QueryEscape("%premium%"))
return makeRequest(requestURL)
}
// GetActiveProxies finds proxies that are not inactive
func GetActiveProxies() (*ApiResponse, error) {
requestURL := fmt.Sprintf("%s/proxy/search?not_proxy_status=inactive", baseURL)
return makeRequest(requestURL)
}
// GetServicesMinQuantity finds services with at least specified quantity
func GetServicesMinQuantity(minQuantity int) (*ApiResponse, error) {
requestURL := fmt.Sprintf("%s/service/search?min_service_quantity=%d", baseURL, minQuantity)
return makeRequest(requestURL)
}
// GetUsersWithDepartment finds proxy users with department metadata
func GetUsersWithDepartment() (*ApiResponse, error) {
requestURL := fmt.Sprintf("%s/proxy_user/search?proxy_user_metadata.exists_department=1", baseURL)
return makeRequest(requestURL)
}
func main() {
// Text search with like operator
premiumServices, err := SearchPremiumServices()
if err != nil {
fmt.Printf("Error fetching premium services: %v\n", err)
} else {
fmt.Printf("Premium services: %d\n", premiumServices.TotalCount)
}
// Negative matching - non-US proxies
nonUsProxies, err := GetNonUsProxies()
if err != nil {
fmt.Printf("Error fetching non-US proxies: %v\n", err)
} else {
fmt.Printf("Non-US proxies: %d\n", nonUsProxies.TotalCount)
}
// Minimum value
highQuantityServices, err := GetServicesMinQuantity(10)
if err != nil {
fmt.Printf("Error fetching high quantity services: %v\n", err)
} else {
fmt.Printf("Services with 10+ units: %d\n", highQuantityServices.TotalCount)
}
// Metadata existence check
usersWithDept, err := GetUsersWithDepartment()
if err != nil {
fmt.Printf("Error fetching users with department: %v\n", err)
} else {
fmt.Printf("Users with department metadata: %d\n", usersWithDept.TotalCount)
}
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
public class PingProxiesFilterOperators {
// API credentials
private static final String API_PUBLIC_KEY = "your_public_key";
private static final String API_PRIVATE_KEY = "your_private_key";
private static final String BASE_URL = "https://api.byteful.com/1.0/public/user";
private static final HttpClient client = HttpClient.newHttpClient();
private static final ObjectMapper mapper = new ObjectMapper();
// Response class to hold API data
static class ApiResponse {
public List> data;
@JsonProperty("item_count")
public int itemCount;
public String message;
public int page;
@JsonProperty("per_page")
public int perPage;
@JsonProperty("total_count")
public int totalCount;
}
// Helper method to make API requests
private static ApiResponse makeRequest(String url) throws IOException, InterruptedException {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return mapper.readValue(response.body(), ApiResponse.class);
}
// Text search with like operator - find 'premium' services
public static ApiResponse searchPremiumServices() throws IOException, InterruptedException {
String encodedPattern = URLEncoder.encode("%premium%", StandardCharsets.UTF_8);
String url = BASE_URL + "/service/search?like_service_name=" + encodedPattern;
return makeRequest(url);
}
// Negative matching - find active proxies
public static ApiResponse getActiveProxies() throws IOException, InterruptedException {
String url = BASE_URL + "/proxy/search?not_proxy_status=inactive";
return makeRequest(url);
}
// Minimum value - find services with at least 10 units
public static ApiResponse getServicesMinQuantity(int minQuantity) throws IOException, InterruptedException {
String url = BASE_URL + "/service/search?min_service_quantity=" + minQuantity;
return makeRequest(url);
}
// Metadata existence check - find proxy users with department metadata
public static ApiResponse getUsersWithDepartment() throws IOException, InterruptedException {
String url = BASE_URL + "/proxy_user/search?proxy_user_metadata.exists_department=1";
return makeRequest(url);
}
public static void main(String[] args) {
try {
ApiResponse premiumServices = searchPremiumServices();
ApiResponse activeProxies = getActiveProxies();
ApiResponse highQuantityServices = getServicesMinQuantity(10);
ApiResponse usersWithDept = getUsersWithDepartment();
System.out.println("Premium services: " + premiumServices.data.size());
System.out.println("Active proxies: " + activeProxies.data.size());
System.out.println("Services with 10+ units: " + highQuantityServices.data.size());
System.out.println("Users with department metadata: " + usersWithDept.data.size());
} catch (Exception e) {
System.out.println("Error fetching filtered data: " + e.getMessage());
e.printStackTrace();
}
}
}
```
# Sorting
Source: https://documentation.byteful.com/api-core-features/sorting
Controlling result order with the sort_by parameter in the Byteful API
The Byteful API provides sorting capabilities that allow you to control the order of returned results. Proper sorting is essential for creating intuitive, user-friendly interfaces and for optimizing data processing workflows.
## The `sort_by` Parameter
All search endpoints in the Byteful API support the `sort_by` parameter, which allows you to specify fields to sort by and the direction of the sort.
## Basic Sorting
The simplest form of sorting uses a single field name without any suffix, which sorts in ascending order (A-Z, oldest to newest):
```
GET /public/user/proxy/search?sort_by=proxy_last_update_datetime
```
This sorts results by the creation datetime in ascending order (oldest to newest).
## Sort Direction
You can specify the sort direction by adding a direction suffix:
* Ascending: Add `_asc` suffix (default when no suffix is specified)
* Descending: Add `_desc` suffix
```
GET /public/user/service/search?sort_by=service_expiry_datetime_desc
```
This sorts services by expiry date in descending order (expiring soonest first).
```
GET /public/user/proxy/search?sort_by=country_id_asc
```
This sorts proxies by country ID in ascending order (A-Z).
## Special Sorting Options
### Random Sorting
Some endpoints support a special `random` sort option:
```
GET /public/user/proxy/search?sort_by=random
```
This returns results in a random order, which can be useful for:
* Load balancing across multiple proxies
* Selecting random samples for testing
* Presenting different options to users
Random sorting should not be used with pagination if you need to access the complete randomly ordered set, as each page will have its own random order.
## Sorting and Pagination
Sorting works in conjunction with pagination. When you specify both a sort order and pagination parameters, the API:
1. Applies the sort to the entire result set
2. Divides the sorted results into pages
3. Returns the requested page
For example:
```
GET /public/user/proxy/search?sort_by=proxy_last_update_datetime_desc&page=2&per_page=25
```
This returns the second page of proxies, with 25 proxies per page, sorted by creation date from newest to oldest.
## Code Examples
```bash cURL theme={null}
# Sort by creation date (newest first)
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy/search?sort_by=proxy_last_update_datetime_desc' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
# Sort alphabetically by country
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy/search?sort_by=country_id_asc' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
# Sort randomly
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy/search?sort_by=random' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
# Sort by expiry date and paginate
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/service/search?sort_by=service_expiry_datetime_asc&page=1&per_page=10' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
```python Python theme={null}
import requests
# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.byteful.com/1.0/public/user/proxy/search"
# Headers for authentication
headers = {
"X-API-Public-Key": API_PUBLIC_KEY,
"X-API-Private-Key": API_PRIVATE_KEY
}
# Sort by creation date (newest first)
def get_newest_proxies(limit=10):
params = {
"sort_by": "proxy_last_update_datetime_desc",
"per_page": limit
}
response = requests.get(BASE_URL, params=params, headers=headers)
return response.json()
# Sort alphabetically by country
def get_proxies_by_country():
params = {
"sort_by": "country_id_asc",
"per_page": 100
}
response = requests.get(BASE_URL, params=params, headers=headers)
return response.json()
# Sort randomly - useful for load balancing
def get_random_proxies(limit=5):
params = {
"sort_by": "random",
"per_page": limit
}
response = requests.get(BASE_URL, params=params, headers=headers)
return response.json()
# Sort by expiry date (closest first) with pagination
def get_expiring_proxies(page=1, per_page=25):
service_url = "https://api.byteful.com/1.0/public/user/service/search"
params = {
"sort_by": "service_expiry_datetime_asc",
"page": page,
"per_page": per_page
}
response = requests.get(service_url, params=params, headers=headers)
return response.json()
# Example usage
if __name__ == "__main__":
# Get 10 newest proxies
newest_proxies = get_newest_proxies(10)
print(f"Newest proxies: {len(newest_proxies['data'])} items")
# Get proxies sorted by country
country_sorted = get_proxies_by_country()
print(f"Country-sorted proxies: {len(country_sorted['data'])} items")
# Get 5 random proxies
random_proxies = get_random_proxies(5)
print(f"Random proxies: {len(random_proxies['data'])} items")
# Get first page of soon-to-expire services
expiring_services = get_expiring_proxies(1, 25)
print(f"Expiring services: {len(expiring_services['data'])} items")
```
```javascript JavaScript theme={null}
// API credentials
const API_PUBLIC_KEY = 'your_public_key';
const API_PRIVATE_KEY = 'your_private_key';
const BASE_URL = 'https://api.byteful.com/1.0/public/user/proxy/search';
// Headers for authentication
const headers = {
'X-API-Public-Key': API_PUBLIC_KEY,
'X-API-Private-Key': API_PRIVATE_KEY
};
// Sort by creation date (newest first)
async function getNewestProxies(limit = 10) {
const url = new URL(BASE_URL);
url.searchParams.append('sort_by', 'proxy_last_update_datetime_desc');
url.searchParams.append('per_page', limit);
const response = await fetch(url, { headers });
return await response.json();
}
// Sort alphabetically by country
async function getProxiesByCountry() {
const url = new URL(BASE_URL);
url.searchParams.append('sort_by', 'country_id_asc');
url.searchParams.append('per_page', 100);
const response = await fetch(url, { headers });
return await response.json();
}
// Sort randomly - useful for load balancing
async function getRandomProxies(limit = 5) {
const url = new URL(BASE_URL);
url.searchParams.append('sort_by', 'random');
url.searchParams.append('per_page', limit);
const response = await fetch(url, { headers });
return await response.json();
}
// Sort by expiry date (closest first) with pagination
async function getExpiringServices(page = 1, perPage = 25) {
const serviceUrl = 'https://api.byteful.com/1.0/public/user/service/search';
const url = new URL(serviceUrl);
url.searchParams.append('sort_by', 'service_expiry_datetime_asc');
url.searchParams.append('page', page);
url.searchParams.append('per_page', perPage);
const response = await fetch(url, { headers });
return await response.json();
}
// Example usage
async function main() {
try {
// Get 10 newest proxies
const newestProxies = await getNewestProxies(10);
console.log(`Newest proxies: ${newestProxies.data.length} items`);
// Get proxies sorted by country
const countrySorted = await getProxiesByCountry();
console.log(`Country-sorted proxies: ${countrySorted.data.length} items`);
// Get 5 random proxies
const randomProxies = await getRandomProxies(5);
console.log(`Random proxies: ${randomProxies.data.length} items`);
// Get first page of soon-to-expire services
const expiringServices = await getExpiringServices(1, 25);
console.log(`Expiring services: ${expiringServices.data.length} items`);
} catch (error) {
console.error('Error fetching sorted data:', error);
}
}
main();
```
```php PHP theme={null}
getMessage() . "\n";
}
?>
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
// API credentials
const (
apiPublicKey = "your_public_key"
apiPrivateKey = "your_private_key"
baseURL = "https://api.byteful.com/1.0/public/user/proxy/search"
)
// Response structure for API
type ApiResponse struct {
Data []map[string]interface{} `json:"data"`
ItemCount int `json:"item_count"`
Message string `json:"message"`
Page int `json:"page"`
PerPage int `json:"per_page"`
TotalCount int `json:"total_count"`
}
// makeRequest is a helper function to make API requests
func makeRequest(url string) (*ApiResponse, error) {
// Create a new request
req, err := http.NewRequest("GET", url, nil)
if err != nil {
return nil, err
}
// Add headers
req.Header.Add("X-API-Public-Key", apiPublicKey)
req.Header.Add("X-API-Private-Key", apiPrivateKey)
// Execute the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
// Check status code
if resp.StatusCode != 200 {
return nil, fmt.Errorf("API request failed with status code: %d", resp.StatusCode)
}
// Read and parse the response
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var response ApiResponse
err = json.Unmarshal(body, &response)
if err != nil {
return nil, err
}
return &response, nil
}
// getNewestProxies gets proxies sorted by creation date (newest first)
func getNewestProxies(limit int) (*ApiResponse, error) {
url := fmt.Sprintf("%s?sort_by=proxy_last_update_datetime_desc&per_page=%d", baseURL, limit)
return makeRequest(url)
}
// getProxiesByCountry gets proxies sorted alphabetically by country
func getProxiesByCountry() (*ApiResponse, error) {
url := fmt.Sprintf("%s?sort_by=country_id_asc&per_page=100", baseURL)
return makeRequest(url)
}
// getRandomProxies gets randomly sorted proxies
func getRandomProxies(limit int) (*ApiResponse, error) {
url := fmt.Sprintf("%s?sort_by=random&per_page=%d", baseURL, limit)
return makeRequest(url)
}
// getExpiringServices gets services sorted by expiry date (closest first) with pagination
func getExpiringServices(page, perPage int) (*ApiResponse, error) {
serviceURL := "https://api.byteful.com/1.0/public/user/service/search"
url := fmt.Sprintf("%s?sort_by=service_expiry_datetime_asc&page=%d&per_page=%d", serviceURL, page, perPage)
return makeRequest(url)
}
func main() {
// Get 10 newest proxies
newestProxies, err := getNewestProxies(10)
if err != nil {
fmt.Printf("Error fetching newest proxies: %v\n", err)
} else {
fmt.Printf("Newest proxies: %d items\n", len(newestProxies.Data))
}
// Get proxies sorted by country
countrySorted, err := getProxiesByCountry()
if err != nil {
fmt.Printf("Error fetching country-sorted proxies: %v\n", err)
} else {
fmt.Printf("Country-sorted proxies: %d items\n", len(countrySorted.Data))
}
// Get 5 random proxies
randomProxies, err := getRandomProxies(5)
if err != nil {
fmt.Printf("Error fetching random proxies: %v\n", err)
} else {
fmt.Printf("Random proxies: %d items\n", len(randomProxies.Data))
}
// Get first page of soon-to-expire services
expiringServices, err := getExpiringServices(1, 25)
if err != nil {
fmt.Printf("Error fetching expiring services: %v\n", err)
} else {
fmt.Printf("Expiring services: %d items\n", len(expiringServices.Data))
}
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
public class PingProxiesSorting {
// API credentials
private static final String API_PUBLIC_KEY = "your_public_key";
private static final String API_PRIVATE_KEY = "your_private_key";
private static final String BASE_URL = "https://api.byteful.com/1.0/public/user/proxy/search";
private static final HttpClient client = HttpClient.newHttpClient();
private static final ObjectMapper mapper = new ObjectMapper();
// Response class to hold API data
static class ApiResponse {
public List> data;
@JsonProperty("item_count")
public int itemCount;
public String message;
public int page;
@JsonProperty("per_page")
public int perPage;
@JsonProperty("total_count")
public int totalCount;
}
// Helper method to make API requests
private static ApiResponse makeRequest(String url) throws IOException, InterruptedException {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("X-API-Public-Key", API_PUBLIC_KEY)
.header("X-API-Private-Key", API_PRIVATE_KEY)
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
throw new IOException("API request failed with status code: " + response.statusCode());
}
return mapper.readValue(response.body(), ApiResponse.class);
}
// Get proxies sorted by creation date (newest first)
public static ApiResponse getNewestProxies(int limit) throws IOException, InterruptedException {
String url = BASE_URL + "?sort_by=proxy_last_update_datetime_desc&per_page=" + limit;
return makeRequest(url);
}
// Get proxies sorted alphabetically by country
public static ApiResponse getProxiesByCountry() throws IOException, InterruptedException {
String url = BASE_URL + "?sort_by=country_id_asc&per_page=100";
return makeRequest(url);
}
// Get randomly sorted proxies
public static ApiResponse getRandomProxies(int limit) throws IOException, InterruptedException {
String url = BASE_URL + "?sort_by=random&per_page=" + limit;
return makeRequest(url);
}
// Get services sorted by expiry date (closest first) with pagination
public static ApiResponse getExpiringServices(int page, int perPage) throws IOException, InterruptedException {
String serviceUrl = "https://api.byteful.com/1.0/public/user/service/search";
String url = serviceUrl + "?sort_by=service_expiry_datetime_asc&page=" + page + "&per_page=" + perPage;
return makeRequest(url);
}
public static void main(String[] args) {
try {
// Get 10 newest proxies
ApiResponse newestProxies = getNewestProxies(10);
System.out.println("Newest proxies: " + newestProxies.data.size() + " items");
// Get proxies sorted by country
ApiResponse countrySorted = getProxiesByCountry();
System.out.println("Country-sorted proxies: " + countrySorted.data.size() + " items");
// Get 5 random proxies
ApiResponse randomProxies = getRandomProxies(5);
System.out.println("Random proxies: " + randomProxies.data.size() + " items");
// Get first page of soon-to-expire services
ApiResponse expiringServices = getExpiringServices(1, 25);
System.out.println("Expiring services: " + expiringServices.data.size() + " items");
} catch (Exception e) {
System.out.println("Error fetching sorted data: " + e.getMessage());
e.printStackTrace();
}
}
}
```
## Examples for Common Use Cases
### Show newest items first
```
GET /public/user/service/search?sort_by=service_creation_datetime_desc
```
### Alphabetical order by name
```
GET /public/user/proxy_user/search?sort_by=proxy_user_id_asc
```
### Find proxies expiring soon (earliest first)
```
GET /public/user/service/search?sort_by=service_expiry_datetime_asc
```
By effectively using the sorting capabilities of the Byteful API, you can create more intuitive and efficient applications that present data in the most useful order for your specific needs.
# Analytics and Usage Tracking
Source: https://documentation.byteful.com/api-explainers/analytics
Understanding the analytics, logging, and tracking systems in the Byteful API
The Byteful API provides comprehensive analytics and usage tracking capabilities to help you monitor and optimize your proxy infrastructure. This guide explains the different components of the tracking system, how they work together, and how to access them through the API.
## Analytics Components
Byteful employs multiple complementary systems to track and analyze proxy usage:
* **Raw Logs (`log`)**: Detailed individual request data, retained for 7 days
* **Log Summaries (`log_summary`)**: Aggregated daily usage patterns, retained for 90+ days
* **Residential Ledger (`residential_ledger`)**: Residential data accounting records, retained indefinitely
* **Mobile Ledger (`mobile_ledger`)**: Mobile data accounting records, retained indefinitely
* **Analytics Graphs**: Visualizations generated from logs and summaries, with indefinite historical data access
The `/analytics/graph` endpoint processes data from both logs and log summaries to provide comprehensive visualizations regardless of the age of the data being analyzed.
## Log Objects
### Raw Logs (`log`)
Raw logs represent individual proxy requests and provide the most detailed information. They are stored for 7 days.
* Tracked at the `proxy_user_id` level
* Created for every single proxy request
* Contains detailed information such as:
* Client IP address
* Request size in bytes
* HTTP status/error codes
* Precise request datetime
* Authentication type
* Hostname being accessed
* Geographic information (country, city)
* ASN information
Example raw log object:
```json theme={null}
{
"log_id": "123e4567-e89b-12d3-a456-426614174000",
"proxy_user_id": "stevejobs",
"log_network": "isp",
"log_protocol": "http",
"log_hostname": "apple.com",
"log_client_ip_address": "17.172.224.1",
"log_total_bytes": 5120,
"log_request_datetime": "2025-04-01 13:00:00",
"country_id": "us",
"city_alias": "cupertino",
"asn_id": 1299
}
```
### Log Summaries (`log_summary`)
Log summaries aggregate raw logs into daily summaries. They provide an efficient way to analyze usage patterns without storing every individual request.
* Initially organized by `proxy_user_id`, `network`, and `hostname` for the first 90 days
* After 90 days, further consolidated to just `proxy_user_id` and `network` level (hostname details are removed)
* Includes metrics like:
* Total requests
* Total bytes transferred
* Success/error counts
Example log summary object:
```json theme={null}
{
"log_summary_id": "456e7890-e89b-12d3-a456-426614174000",
"proxy_user_id": "stevejobs",
"log_summary_network": "residential",
"log_summary_hostname": "apple.com",
"log_summary_requests": 100,
"log_summary_bytes": 10000,
"log_summary_period": "2025-04-01 00:00:00"
}
```
### Residential Ledger (`residential_ledger`)
The residential ledger specifically tracks data usage for residential proxies, which operate on a data-based billing model rather than a per-proxy model.
* Tracks daily residential data usage at the customer account level
* Records various types of data changes:
* Usage (decrements)
* Top-ups (increments when purchasing additional data)
* Service purchases (addition of data with new residential services)
* Refunds and adjustments (manual or automatic credits)
* Provides a complete audit trail of all changes to your residential data allocation
* Critical for billing and quota management
Example residential ledger object:
```json theme={null}
{
"residential_ledger_id": "123e4567-e89b-12d3-a456-426614174000",
"residential_ledger_bytes": 128290101,
"residential_ledger_requests": 1244,
"residential_ledger_period_date": "2025-04-01",
"residential_ledger_reason": "usage"
}
```
### Mobile Ledger (`mobile_ledger`)
The mobile ledger specifically tracks data usage for mobile proxies, which operate on a data-based billing model rather than a per-proxy model.
* Tracks daily mobile data usage at the customer account level
* Records various types of data changes:
* Usage (decrements)
* Top-ups (increments when purchasing additional data)
* Service purchases (addition of data with new mobile services)
* Refunds and adjustments (manual or automatic credits)
* Provides a complete audit trail of all changes to your mobile data allocation
* Critical for billing and quota management
Example mobile ledger object:
```json theme={null}
{
"mobile_ledger_id": "123e4567-e89b-12d3-a456-426614174000",
"mobile_ledger_bytes": 128290101,
"mobile_ledger_requests": 1244,
"mobile_ledger_period_date": "2025-04-01",
"mobile_ledger_reason": "usage"
}
```
## Data Flow Process
The tracking system follows specific data flows depending on the proxy type:
### Datacenter and ISP Proxy Requests
1. When a request is made through a datacenter or ISP proxy:
* A `log` record is created
* The corresponding `log_summary` is incremented or created if it doesn't exist
### Residential Proxy Requests
Residential proxies involve an additional tracking layer due to their data-based billing model:
1. When a request is made through a residential proxy:
* A `log` record is created
* The corresponding `log_summary` is incremented or created
* The customer's `residential_ledger` usage record is incremented or created
### Mobile Proxy Requests
Mobile proxies involve an additional tracking layer due to their data-based billing model:
1. When a request is made through a mobile proxy:
* A `log` record is created
* The corresponding `log_summary` is incremented or created
* The customer's `mobile_ledger` usage record is incremented or created
## Accessing Analytics Data
### Residential & Mobile Ledger Endpoints
To monitor residential data usage:
```
GET /public/user/residential_ledger/search
GET /public/user/residential_ledger/retrieve/{residential_ledger_id}
```
These endpoints allow you to track daily customer usage and top-ups for residential proxies.
To monitor mobile data usage:
```
GET /public/user/mobile_ledger/search
GET /public/user/mobile_ledger/retrieve/{mobile_ledger_id}
```
These endpoints allow you to track daily customer usage and top-ups for mobile proxies.
### Analytics Graph Endpoint
For visualizing usage patterns and trends:
```
GET /public/user/analytics/graph
```
This powerful endpoint:
* Automatically analyzes logs and log summary records
* Produces summaries and graphing data over specified time periods
* Supports filtering by proxy user, network, and hostname
* Offers flexible time intervals (minute, hour, day, month)
### Raw Log Endpoints
For detailed troubleshooting within the 7-day retention window:
```
GET /public/user/log/search
GET /public/user/log/retrieve/{log_id}
```
### Log Summary Endpoints
For aggregated historical data analysis:
```
GET /public/user/log_summary/search
GET /public/user/log_summary/retrieve/{log_summary_id}
```
## Endpoint Selection Guide
Use `/analytics/graph` for most monitoring needs. Use `/log` or `/log_summary` for detailed breakdowns by hostname, proxy user, or network. Use `/residential_ledger` for residential data tracking and `/mobile_ledger` for mobile data tracking.
## Reference Table: Analytics Endpoints
| Endpoint | Purpose | Retention | Granularity |
| ------------------------------------------------------ | ------------------------------------ | ---------- | ---------------------- |
| `/log/search` | Search raw logs | 7 days | Individual requests |
| `/log/retrieve/{log_id}` | Get specific raw log | 7 days | Individual request |
| `/log_summary/search` | Search log summaries | 90+ days | Daily aggregations |
| `/log_summary/retrieve/{log_summary_id}` | Get specific log summary | 90+ days | Daily aggregation |
| `/residential_ledger/search` | Search residential usage records | Indefinite | Daily usage |
| `/residential_ledger/retrieve/{residential_ledger_id}` | Get specific residential usage entry | Indefinite | Daily usage |
| `/mobile_ledger/search` | Search mobile usage records | Indefinite | Daily usage |
| `/mobile_ledger/retrieve/{mobile_ledger_id}` | Get specific mobile usage entry | Indefinite | Daily usage |
| `/analytics/graph` | Visualize usage patterns | Indefinite | Configurable intervals |
| `/residential/summary` | Get overall residential data status | Current | Account-level summary |
| `/mobile/summary` | Get overall mobile data status | Current | Account-level summary |
# Purchasing via API
Source: https://documentation.byteful.com/api-explainers/api-purchasing
How to programmatically purchase and manage proxies through the Byteful API
# Purchasing via API
The Byteful API enables complete programmatic control over the purchasing and management of proxy services. This guide covers how to browse available products, generate quotes, create checkouts, and manage ongoing services.
## Overview of the Purchasing Process
![API Purchase Flow]()
![API Purchase Flow]()
## Browsing Available Products
Start by retrieving the available products through the catalog endpoint:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/checkout/catalog' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": {
"datacenter_us": {
"country_id": "us",
"product_cycle_options": ["1:month", "3:month", "1:year"],
"product_is_available": true,
"product_is_per_ip": true,
"product_name": "Datacenter Proxies [US]",
"product_protocol": "ipv4",
"product_stock": 10,
"product_type": "datacenter"
},
"isp_gb": {
"country_id": "gb",
"product_cycle_options": ["1:month", "3:month", "1:year"],
"product_is_available": true,
"product_is_per_ip": true,
"product_name": "Static Residential ISP Proxies [GB]",
"product_protocol": "ipv4",
"product_stock": 181,
"product_type": "isp"
},
"residential_global": {
"country_id": null,
"product_cycle_options": ["1:month"],
"product_is_available": true,
"product_is_per_ip": false,
"product_name": "Residential Proxies (Global)",
"product_protocol": null,
"product_stock": null,
"product_type": "residential"
},
"mobile_global": {
"country_id": null,
"product_cycle_options": ["1:month"],
"product_is_available": true,
"product_is_per_ip": false,
"product_name": "Mobile Proxies (Global)",
"product_protocol": null,
"product_stock": null,
"product_type": "mobile"
}
},
"message": "Checkout catalog successfully retrieved."
}
```
For more detailed product information, you can use the product search endpoint:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/product/search?product_type=isp&country_id=us' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Generating a Quote
Before completing a purchase, generate a quote to check pricing, availability, and any applicable discounts:
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/checkout/quote' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"product_code": "isp_us",
"quantity": 5,
"cycle_interval": "month",
"cycle_interval_count": 1,
"promotional_code": "WELCOME10"
}'
```
Response:
```json theme={null}
{
"data": {
"before_discount_total": 1750,
"credit_balance": 500,
"credit_only_checkout": false,
"customer_credit_balance_applied": true,
"customer_credit_balance_applied_amount": 500,
"discount": 175,
"discounted": true,
"is_valid": true,
"line_items": [
{
"item_country_id": "us",
"item_name": "Static Residential ISP Proxies [US]",
"item_per_unit_amount": 350,
"item_price_id": "price_1QJx2DB2BUlqim5lxmO3aT2v",
"item_price_type": "recurring",
"item_quantity": 5,
"item_total": 1750,
"item_type": "isp",
"service_fulfillment_filter": {}
}
],
"promotional_code": "WELCOME10",
"promotional_code_id": "promo_1RbySPB2BUlqim5lZkfUaYdE",
"total": 1575,
"total_after_applied_credit": 1075
},
"message": "Quote generated successfully."
}
```
The quote provides detailed information including:
* Original price before discounts
* Any promotional discounts applied
* Credit balance that will be applied
* Final amount due
## Creating a Checkout
Once you're satisfied with the quote, create a checkout to complete the purchase:
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/checkout/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"product_code": "isp_us",
"quantity": 5,
"cycle_interval": "month",
"cycle_interval_count": 1,
"promotional_code": "WELCOME10",
"service_fulfillment_filter": {
"asn_id": 7018
}
}'
```
Response:
```json theme={null}
{
"data": {
"created": ["API-1234-5678"],
"invoice_is_paid": false,
"invoice_url": "https://invoice.stripe.com/i/acct_1H7dAB2BUlqim5l/test_YWNjdF8xSGIzUEFCMkJabsEyzPS3Aag",
"proxies": [],
"proxy_edited": [],
"residential_ledger_created": [],
"mobile_ledger_created": [],
"service": {
"country_id": "us",
"customer_id": 1976,
"open_invoice_id": "in_1TsPgdB2BUlqim5lkTytLb8K",
"payment_method_id": null,
"product_id": "prod_AT7018",
"service_creation_datetime": "2025-03-25 14:25:36",
"service_cycle": "1:month",
"service_dispatch_datetime": null,
"service_earliest_cancellation_datetime": "2025-03-25 14:25:36",
"service_expiry_datetime": "2025-04-25 14:25:36",
"service_fulfillment_filter": {"asn_id": 7018},
"service_id": "API-1234-5678",
"service_image": "https://files.stripe.com/links/MDB8YWNjdF8xSDdkOEFCMkJVbHFpbTVsfGZsX2xpdmVfZFZ6TTZjUG01Q0NuR1IzSTZsVzNjVVFX00kUPPfQE9",
"service_is_automatic_collection": true,
"service_is_cancellable": true,
"service_is_off_catalog": false,
"service_is_pending_cancellation": false,
"service_is_reconfigurable": true,
"service_last_update_datetime": "2025-03-25 14:25:36",
"service_metadata": {},
"service_name": "AT&T ISP Proxies [US]",
"service_price_id": "price_1QJx2DB2BUlqim5lxmO3aT2v",
"service_promotional_code": "WELCOME10",
"service_protocol": "ipv4",
"service_quantity": 5,
"service_status": "awaiting_fulfillment",
"service_subscription_id": "sub_1QxSHmB2BUlqim5lTUH8HvKa",
"service_subscription_is_paused": false,
"service_total": 1575,
"service_type": "isp",
"subscription_schedule_id": null
},
"service_id": "API-1234-5678"
},
"message": "Successfully created checkout. Please complete payment at the invoice URL."
}
```
### Payment Processing
If your account has sufficient credit, `invoice_is_paid` will be `true` and the service provisions immediately. Otherwise, use the `invoice_url` to complete payment.
## Service Fulfillment Filters
For certain proxy types, you can specify service fulfillment filters to customize the provisioning:
```json theme={null}
"service_fulfillment_filter": {
"asn_id": 7018, // Specific ASN (e.g., AT&T)
"subdivision_id": "us-tx", // Specific region (e.g., Texas)
"city_id": 75202 // Specific city (e.g., Dallas)
}
```
These filters allow you to target proxies with specific attributes such as:
* Network provider (ASN)
* Geographic location (country, subdivision, city)
* Protocol preferences (IPv4, IPv6, dual-stack)
## Managing Account Credit
Your account credit serves as a prepaid balance that can be applied to any purchase. This credit balance can come from:
1. **Direct top-ups**: Adding funds to your account
2. **Refunds**: Credits issued for service issues
3. **Promotional credits**: Special credits from promotional campaigns
### Viewing Credit Balance
Check your current credit balance:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/customer/retrieve' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
The response includes your current credit balance:
```json theme={null}
{
"data": {
"credit_balance": 500,
// Other customer fields...
},
"message": "Customer successfully retrieved."
}
```
### Adding Credit
To top up your credit balance, use the checkout endpoint with the credit product:
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/checkout/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"product_code": "credit",
"quantity": 1,
"cycle_interval": "month",
"cycle_interval_count": 1,
"top_up_amount": 5000
}'
```
Response:
```json theme={null}
{
"data": {
"invoice_is_paid": false,
"invoice_url": "https://invoice.stripe.com/i/acct_1H7dAB2BUlqim5l/test_YWNjdF8xSGIzUEFCMkJabsEyzPS3Aag",
"credit_added": true
},
"message": "Successfully created checkout. Please complete payment at the invoice URL."
}
```
## Residential and Mobile Data Management
For residential and mobile proxies, which use a data-based model instead of a per-proxy model, you can monitor your data usage:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/summary' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Use `/1.0/public/user/mobile/summary` for mobile data
Response:
```json theme={null}
{
"data": {
"residential_bytes": 10737418240, // Total allocated data (10 GB)
"residential_bytes_used": 3221225472, // Used data (3 GB)
"residential_bytes_left": 7516192768, // Remaining data (7 GB)
"residential_requests": 145022, // Total number of requests
"service_expiry_datetime": "2025-04-25 14:25:36",
"service_id": "121-0220-821",
"proxy_user_ids": ["default_user", "stevejobs"]
},
"message": "Residential summary successfully generated."
}
```
## Best Practices
* Test purchases with small quantities before automating
* Monitor credit balance to ensure sufficient funds for automated purchases
* Implement robust error handling for checkout responses
* Track service IDs returned from successful purchases
For high-volume purchasing needs or custom fulfillment requirements, contact [sales@byteful.com](mailto:sales@byteful.com).
# Billing Cycles & Credit System
Source: https://documentation.byteful.com/api-explainers/billing
Understanding billing cycles and the credit system in the Byteful API
The Byteful billing system is built on Stripe's subscription architecture, providing flexible billing cycles and a credit balance system for managing your proxy services.
### Best Practices
1. **Maintain sufficient credit balance**: Ensure smooth service continuity by keeping your credit balance topped up
2. **Use quarterly or annual billing** for better pricing on long-term commitments
3. **Top up before API purchases** since credit is required for all API-initiated purchases
## Credit System
The credit system serves as a prepaid balance that is used for all API purchases.
### API Purchasing Requirement
Services can only be purchased via the API using your account credit balance. You must top up your account with credit prior to using the API to make purchases.
### Viewing Your Credit Balance
You can check your current credit balance through the API:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/customer/retrieve' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
The response includes your current credit balance:
```json theme={null}
{
"data": {
"credit_balance": 500, #displayed in cents
// Other customer fields...
},
"message": "Customer successfully retrieved."
}
```
### Adding Credit
You can add credit to your account via the dashboard top up flow. Credit can be added by card payment, cryptocurrency or ACH payment.
![Add Byteful Credit]()
## Invoice Generation & Credit Application
Invoices are generated at key points in the service lifecycle:
1. **Initial Purchase**: When you first purchase a service
2. **Renewal**: At the end of each billing cycle
3. **Service Reconfigurations or Top Ups**: When service quantity or billing cycloe is reconfigured
### Automatic Credit Application
When an invoice is generated, the system automatically:
1. Checks your available credit balance
2. Applies the credit to reduce the invoice amount
3. Updates your remaining credit balance
Example of how credit is applied during checkout:
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/checkout/quote' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"product_code": "isp_us",
"quantity": 5,
"cycle_interval": "month",
"cycle_interval_count": 1
}'
```
Quote response showing credit application:
```json theme={null}
{
"data": {
"before_discount_total": 1750,
"credit_balance": 500,
"customer_credit_balance_applied": true,
"customer_credit_balance_applied_amount": 500,
"total": 1750,
"total_after_applied_credit": 1250
},
"message": "Quote generated successfully."
}
```
### Credit Return on Voided Invoices
If an invoice with applied credit is voided or canceled due to lack of payment after 48 hours, the credit is automatically released back to your account balance.
## Invoice Statuses
Invoices can exist in several states:
| Status | Description |
| ------- | ------------------------------------------------------------ |
| `draft` | Invoice has been created but not finalized |
| `open` | Invoice has been finalized and awaiting payment |
| `paid` | Invoice has been paid (either with credit or payment method) |
| `void` | Invoice has been voided and will not be paid |
For API purchases, invoices are typically in either 'paid' status (if covered by credit) or 'open' status (if additional payment is needed).
## Billing Cycle & Invoice Flow
1. **Service Creation**: A service is purchased through the API using account credit
2. **Initial Invoice**: Generated and marked as paid (if fully covered by credit)
3. **Service Activation**: Service becomes active after payment
4. **Renewal Invoice**: Generated at the end of the billing cycle
5. **Automatic Credit Application**: Available credit is applied to the renewal invoice
6. **Service Continuation**: Service continues if invoice is paid successfully within 48 hours of generation.
## Checking Invoice Status
You can view open invoices requiring payment:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/invoice/search?invoice_status=open' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
You can view invoices associated with a service:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/service/retrieve/API-1234-5678' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
The response will include the `open_invoice_id` field if there's a pending invoice:
```json theme={null}
{
"data": {
"service_id": "API-1234-5678",
"service_name": "AT&T ISP Proxies [US]",
"service_status": "active",
"open_invoice_id": "in_1TsPgdB2BUlqim5lkTytLb8K",
// Other service fields...
},
"message": "Service successfully retrieved."
}
```
# Common Object Relationships
Source: https://documentation.byteful.com/api-explainers/common-object-relationships
Understanding how proxy objects relate to geographic and network entities in the Byteful API
The Byteful API organizes resources in a hierarchical structure that mirrors the real-world relationships between network and geographic entities. Understanding these relationships is crucial for effectively managing and filtering proxies.
## Geographic Hierarchy
```
Continent > Country > Subdivision > City
```
This hierarchical structure allows you to target proxies at different geographic levels:
* **Continent**: The broadest geographic division (e.g., `eu` for Europe)
* **Country**: Countries within continents (e.g., `fr` for France)
* **Subdivision**: States, provinces, regions (e.g., `fr-idf` for Île-de-France)
* **City**: Specific cities (e.g., `paris` with city\_id 379657)
## Network Hierarchy
```
ASN > Subnet > IP Address > Proxy
```
* **ASN (Autonomous System Number)**: Identifies a network operator like AT\&T (ASN 7018)
* **Subnet**: A range of IP addresses (e.g., `107.225.72.0/22`)
* **IP Address**: The specific address assigned to a proxy
* **Proxy**: The actual proxy service with ports and authentication
## How Objects Connect
### Proxy Objects
A proxy object represents a single proxy instance. It connects to both geographic and network hierarchies:
```json theme={null}
{
"proxy_id": "7a018d34-76c2-4c23-b14d-f7b9a7054e25",
"proxy_ip_address": "107.225.73.142",
"proxy_http_port": 8080,
"proxy_socks5_port": 1080,
"proxy_type": "isp",
"proxy_protocol": "ipv4",
"proxy_status": "in_use",
// Network hierarchy connections
"asn_id": 7018,
"asn_name": "AT&T Enterprises, LLC",
"subnet_id": "107.225.72.0/22",
// Geographic hierarchy connections
"country_id": "us",
"country_name": "United States",
"subdivision_id": "us-tx",
"subdivision_name": "Texas",
"city_id": 75202,
"city_name": "Dallas",
"city_timezone": "America/Chicago",
"city_latitude": 32.7767,
"city_longitude": -96.797
}
```
### Service Objects and Proxies
Services are container objects that group proxies:
```
Service > Proxies
```
A service represents a purchased group of proxies, and may contain multiple proxy objects:
```json theme={null}
{
"service_id": "API-1234-5678",
"service_name": "AT&T ISP Proxies [US]",
"service_type": "isp",
"service_protocol": "ipv4",
"service_quantity": 5,
"service_status": "active",
"country_id": "us",
// Service may contain multiple proxies
"proxies": [
{
"proxy_id": "7a018d34-76c2-4c23-b14d-f7b9a7054e25",
"proxy_ip_address": "107.225.73.142",
// Additional proxy details...
},
// More proxies...
]
}
```
## Residential/Mobile Proxy Generation and Object Relationships
Residential and mobile proxies differ from datacenter and ISP proxies in that they're generated on demand rather than being persistent objects. When generating residential or mobile proxies, you specify geographic and network attributes to target specific types of exit nodes.
### Residential Proxy Example
```bash theme={null}
# Generate 5 residential proxies in London, UK
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=gb&city_alias=london&list_count=5' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": [
"socks5h://stevejobs_c_gb_city_london_s_DDINPY7TQ0781XEO:apple1984@residential.byteful.com:8000",
"socks5h://stevejobs_c_gb_city_london_s_XIINPY7TQ0781XEA:apple1984@residential.byteful.com:8000"
],
"message": "Residential list successfully created."
}
```
### Mobile Proxy Example
```bash theme={null}
# Generate 5 mobile proxies in London, UK
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?country_id=gb&city_alias=london&list_count=5' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": [
"socks5h://stevejobs_c_gb_city_london_s_DDINPY7TQ0781XEO:apple1984@mobile.byteful.com:8000",
"socks5h://stevejobs_c_gb_city_london_s_XIINPY7TQ0781XEA:apple1984@mobile.byteful.com:8000"
],
"message": "Mobile list successfully created."
}
```
You can also filter residential and mobile proxies by ASN to target specific network providers.
## Exploring Available Options
To explore the available ASNs, countries, subdivisions, and cities, you can use the corresponding search endpoints:
```bash theme={null}
# List all available ASNs
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/asn/search' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
# List all cities in a specific country
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/city/search?country_id=gb' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
By understanding these object relationships, you can more effectively utilize the Byteful API to precisely target and manage your proxy infrastructure according to your specific needs.
# Proxy Testing Overview
Source: https://documentation.byteful.com/api-explainers/proxy-tester
How proxy testing works on the Byteful API.
In an increasingly interconnected world, measuring proxy performance across different regions is critical. Our global infrastructure spans the United States, Europe, and Asia, allowing you to test your proxies from multiple vantage points. This way, you gain a clear understanding of real-world latency and reliability, ensuring that your users experience consistently high performance, no matter where they are located.
Below you can see how the Byteful API distributes proxy tests across multiple servers and returns combined results.
The Python script example shows how to simply create a test run for a single proxy.
## What happens when you create a proxy tester?
```mermaid theme={null}
graph TD
A["Create Proxy Test Run
[POST] /public/user/proxy_test_run/create"]:::userAction
A --> B[("Distribute Tests Across Servers")]:::systemAction
B --> C1[("Server 1
Execute Tests")]:::serverAction
B --> C2[("Server 2
Execute Tests")]:::serverAction
B --> C3[("Server 3
Execute Tests")]:::serverAction
C1 --> D[("Collect & Combine Results")]:::systemAction
C2 --> D
C3 --> D
D --> E["Proxy Test Results Returned"]:::userAction
%% User actions styled in purple
classDef userAction fill:#A192EC,stroke:#553c9a,stroke-width:2px,color:#fff
%% System actions styled as green clouds
classDef systemAction fill:#48bb78,stroke:#1fb356,stroke-width:2px,color:#fff
%% Server actions styled as blue clouds
classDef serverAction fill:#4299e1,stroke:#2b6cb0,stroke-width:2px,color:#fff
```
## Example Python Script
```python theme={null}
import requests
import sys
# API credentials
API_PRIVATE_KEY = "your_private_key"
API_PUBLIC_KEY = "your_public_key"
BASE_URL = "https://api.byteful.com/1.0/public/user"
# Headers
headers = {
"X-API-Public-Key": API_PUBLIC_KEY,
"X-API-Private-Key": API_PRIVATE_KEY,
"Content-Type": "application/json"
}
# Hardcoded proxy and test configuration
PROXY_STRING = "192.168.1.100:8080:username:password" # Replace with your actual proxy
TARGET_URL = "https://byteful.com"
TEST_SERVER_ID = "newyork-3-digitalocean-proxytester-1" # Replace with actual server ID
# Create the test payload
payload = {
"proxies": [{"proxy_string": PROXY_STRING}],
"proxy_tester_server_id": [TEST_SERVER_ID],
"urls": [TARGET_URL],
}
try:
response = requests.post(f"{BASE_URL}/proxy_test_run/create", json=payload, headers=headers)
if response.status_code != 200:
print(f"❌ Error: {response.status_code}")
print(f"Response: {response.text}")
sys.exit(1)
result = response.json()
print("\n✅ Proxy test created successfully!")
print(f"Response: {result}")
# Extract and display key results
if "data" in result:
for run_id, test_data in result["data"].items():
if "results" in test_data:
for test_result in test_data["results"]:
is_successful = test_result.get("proxy_test_result_is_successful", "N/A")
error_code = test_result.get("proxy_test_result_error_code", "N/A")
response_time = test_result.get("proxy_test_result_response_time", "N/A")
city = test_result.get("proxy_tester_proxy_city_name", "N/A")
country = test_result.get("proxy_tester_proxy_country_id", "N/A")
print(f"\nTest Results:")
print(f"Is Successful: {is_successful}")
print(f"Error Code: {error_code}")
print(f"Response Time: {response_time}ms")
print(f"Location: {city}, {country}")
except Exception as e:
print(f"❌ Unexpected error: {e}")
```
**Rate Limit** API users can create a maximum of `5000` proxy\_test\_run sessions per day through the API by standard. Contact our support team with justification if you would like to test more proxies than this.
## Best Practices
* Use test servers in regions where you plan to use the proxies
* Test against different website types (search engines, APIs, content sites) to ensure broad compatibility
* Implement regular testing to maintain service quality and catch degraded proxies early
* Verify that proxy exit locations match your targeting requirements
# Proxy Types Overview
Source: https://documentation.byteful.com/api-explainers/proxy-types
This guide explains the different proxy types available through Byteful, helping you choose the right option for your needs.
Byteful offers Dedicated Datacenter, Dedicated Static Residential ISP, Residential, and Mobile proxies.
| Feature | Datacenter | Static Residential ISP | Residential | Mobile |
| -------------- | ------------------------------ | ------------------------------ | --------------------- | --------------------- |
| IP Type | Datacenter | ISP-assigned consumer | Real residential | Mobile carrier |
| Ownership | Dedicated | Dedicated | Shared | Shared |
| Speed | Very fast | Very fast | Moderate (varies) | Moderate (varies) |
| Stability | Highly stable | Highly stable | Variable | Variable |
| Detection Risk | Higher | Low | Very low | Very low |
| IP Rotation | Fixed IPs | Fixed IPs | Supports rotation | Supports rotation |
| Geo-targeting | Country-level | Country-level | City & carrier-level | City & carrier-level |
| Pricing Model | Per proxy | Per proxy | Data-based | Data-based |
| Access Control | Proxy User Service Restriction | Proxy User Service Restriction | Proxy User Data Limit | Proxy User Data Limit |
| API Access | /proxy/search | /proxy/search | /residential/list | /mobile/list |
| API Proxy Type | `datacenter` | `isp` | `residential` | `mobile` |
### Datacenter Proxies
* **Source**: Commercial datacenters
* **Key Benefits**: Highest speed (1Gbps+), very stable connections
* **Pricing**: Per proxy with unlimited data
* **Best For**: High-speed data collection where pure performance matters most
### Static Residential ISP Proxies
* **Source**: Major Internet Service Providers
* **Key Benefits**: Balance of legitimacy and performance, fixed IPs with ISP credibility
* **Pricing**: Per proxy with unlimited data
* **Best For**: E-commerce automation, social media management, SEO monitoring
### Residential Proxies
* **Source**: Real consumer connections
* **Key Benefits**: Maximum legitimacy, rotating IPs, finest geo-targeting
* **Pricing**: Data-based (pay for what you use)
* **Best For**: Accessing geo-restricted content, price comparison, brand protection
### Mobile Proxies
* **Source**: Real mobile devices
* **Key Benefits**: Maximum legitimacy, rotating IPs, carrier-level targeting
* **Pricing**: Data-based (pay for what you use)
* **Best For**: Mobile app testing, mobile-specific content access, carrier-specific testing
## Choosing the Right Type
* Choose **Datacenter** for raw speed and reliability at lower cost
* Choose **Static Residential ISP** for the best balance of legitimacy and performance
* Choose **Residential** for maximum legitimacy and rotating IPs
* Choose **Mobile** for mobile carrier IPs and mobile-specific use cases
## Getting Available Products
You can retrieve available product options using the catalog endpoint:
```
GET /public/user/checkout/catalog
```
This endpoint returns all available products with their pricing, features, and availability without requiring complex search parameters.
# Proxy User Access Control
Source: https://documentation.byteful.com/api-explainers/proxy-user-access-control
Understanding and implementing granular access control for your proxy users
Proxy User Access Control allows you to restrict which proxies a proxy user can access. This is essential for organizing teams, managing customer access in reselling scenarios, and implementing security policies.
Default Proxy Users cannot have ACL rules applied and have access to all proxies on your account.
## Access Control Model
Access control in Byteful uses a two-part system:
1. **`proxy_user_access_type`** - Set on the Proxy User object
2. **Proxy User ACL entries** - Individual permission grants
### The Three Access Types
#### 1. Unrestricted Access (`"all"`)
**Default setting.** The proxy user can access all proxies in your account.
```json theme={null}
{
"proxy_user_id": "admin_user",
"proxy_user_access_type": "all"
}
```
**Best for:**
* Admin or internal users
* Development and testing
* Small teams with full proxy access
**ACL requirements:** None - no ACL entries needed
***
#### 2. Service-Restricted Access (`"service_restricted"`)
The proxy user can only access proxies within specific services. You grant access by creating Proxy User ACL entries with `service_id`.
```json theme={null}
{
"proxy_user_id": "seo_team",
"proxy_user_access_type": "service_restricted"
}
```
Then create ACL entries to grant service access:
```json theme={null}
{
"proxy_user_id": "seo_team",
"service_id": "API-SEO-POOL-001"
}
```
**Best for:**
* Department or team segregation (Marketing, SEO, Research teams)
* Organizing proxies by purpose (Social media, Web scraping, Ad verification)
* Multi-tenant scenarios where each customer gets specific services
**ACL requirements:** At least one ACL entry with `service_id`
***
#### 3. Proxy-Restricted Access (`"proxy_restricted"`)
The proxy user can only access specific individual proxies. You grant access by creating Proxy User ACL entries with `proxy_id`.
```json theme={null}
{
"proxy_user_id": "customer_123",
"proxy_user_access_type": "proxy_restricted"
}
```
Then create ACL entries for each proxy:
```json theme={null}
{
"proxy_user_id": "customer_123",
"proxy_id": "550e8400-e29b-41d4-a716-446655440001"
}
```
**Best for:**
* Reselling individual proxies to end customers
* Maximum security with fine-grained control
* Dedicated proxy assignments
**ACL requirements:** At least one ACL entry with `proxy_id`
## Decision Tree: Which Access Type Should I Use?
```mermaid theme={null}
graph TD
Start[Which access type?] --> Q1{Need to restrict access?}
Q1 -->|No| All[Use 'all']
Q1 -->|Yes| Q2{Organize by groups/services?}
Q2 -->|Yes| Service[Use 'service_restricted']
Q2 -->|No| Q3{Need individual proxy control?}
Q3 -->|Yes| Proxy[Use 'proxy_restricted']
Q3 -->|No| Service2[Consider 'service_restricted']
```
**Quick guide:**
* **Full access needed?** → Use `"all"`
* **Organize by teams/services?** → Use `"service_restricted"`
* **Control individual proxies?** → Use `"proxy_restricted"`
## Implementation Workflow
### Setting Up Service-Restricted Access
**Step 1:** Create the proxy user with service-restricted access type
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_id": "seo_team",
"proxy_user_password": "securepass123",
"proxy_user_access_type": "service_restricted"
}'
```
**Step 2:** Grant access to services by creating ACL entries
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/proxy_user_acl/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_id": "seo_team",
"service_id": "API-SEO-POOL-001"
}'
```
Repeat Step 2 to grant access to additional services.
### Setting Up Proxy-Restricted Access
**Step 1:** Create the proxy user with proxy-restricted access type
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_id": "customer_123",
"proxy_user_password": "securepass456",
"proxy_user_access_type": "proxy_restricted"
}'
```
**Step 2:** Grant access to individual proxies
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/proxy_user_acl/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_id": "customer_123",
"proxy_id": "550e8400-e29b-41d4-a716-446655440001"
}'
```
## Managing Access Control
### View Current ACLs
Search for all ACL entries for a specific proxy user:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy_user_acl/search?proxy_user_id=seo_team' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
### Remove Access
Delete an ACL entry to revoke access:
```bash theme={null}
curl --request DELETE \
--url 'https://api.byteful.com/1.0/public/user/proxy_user_acl/delete/{proxy_user_acl_id}' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
### Change Access Type
To change from restricted to unrestricted access:
```bash theme={null}
curl --request PATCH \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/edit/seo_team' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_access_type": "all",
"clear_proxy_user_acl": true
}'
```
When changing `access_type` to `"all"`, you must set `clear_proxy_user_acl: true` to remove existing ACL entries. When changing between `"service_restricted"` and `"proxy_restricted"`, you can optionally clear ACLs or leave them (though they won't be used unless the access type matches).
## Important Notes
* ACL entries can only be created for proxy users with `access_type` of `"service_restricted"` or `"proxy_restricted"`
* You cannot mix service and proxy ACLs for the same proxy user - the access type determines which is valid
* The service or proxy in an ACL must belong to your customer account
* Deleting a proxy user automatically deletes all associated ACL entries
* When a proxy user has restricted access but no ACL entries, they cannot access any proxies
## Related Documentation
* [Proxy User Object](/api-objects/proxy-user) - Core proxy user attributes
* [Proxy User ACL Object](/api-objects/proxy-user-acl) - ACL entry details
* [Create Proxy User with Service Access](/api-examples/create-proxy-user-with-service-access) - Full example
* [Manage Proxy User ACLs](/api-examples/manage-proxy-user-acls) - ACL management examples
# Residential & Mobile Data
Source: https://documentation.byteful.com/api-explainers/residential-mobile-data
Understanding and managing residential/mobile data allocation in the Byteful API
Unlike datacenter and ISP proxies that operate on a per-proxy model, residential and mobile proxies use a data-based allocation system. This guide explains how residential and mobile data is managed in the Byteful API.
## Data Fundamentals
Residential and mobile data in Byteful works as follows:
* **Account-Wide Pool**: Data is added to your customer account as a shared resource
* **No Expiration**: Once data is added to your account, it never expires until it is consumed
* **Proxy User Allocation**: Data can be allocated to different proxy users with specific limits
* **Usage Tracking**: All data usage is tracked and can be monitored via the API
## Managing Data via API
### Checking Data Usage
To check your current residential data status:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/summary' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": {
"residential_bytes": 10737418240, // Total allocated data (10 GB)
"residential_bytes_used": 3221225472, // Used data (3 GB)
"residential_bytes_left": 7516192768, // Remaining data (7 GB)
"residential_requests": 145022, // Total number of requests
"proxy_user_ids": ["default_user", "stevejobs"] // Any other proxy users which have access to the data
},
"message": "Residential summary successfully generated."
}
```
To check your current mobile data status:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/summary' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": {
"mobile_bytes": 10737418240, // Total allocated data (10 GB)
"mobile_bytes_used": 3221225472, // Used data (3 GB)
"mobile_bytes_left": 7516192768, // Remaining data (7 GB)
"mobile_requests": 145022, // Total number of requests
"proxy_user_ids": ["default_user", "stevejobs"] // Any other proxy users which have access to the data
},
"message": "Mobile summary successfully generated."
}
```
### Setting Proxy User Data Limits
While the total data is purchased through the dashboard, you can control how much data each proxy user can consume via the API:
```bash theme={null}
curl --request PATCH \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/edit/stevejobs' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_residential_bytes_limit": 2147483648
}'
```
This sets a 2 GB limit for the "stevejobs" proxy user, preventing them from using more than that amount from the account's total residential data.
`proxy_user_mobile_bytes_limit` can be used to set this for mobile.
### Creating Proxy Users with Data Limits
When creating a new proxy user, you can set their data limit immediately:
```bash theme={null}
curl --request POST \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/create' \
--header 'Content-Type: application/json' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key' \
--data '{
"proxy_user_id": "research_team",
"proxy_user_password": "secure_password",
"proxy_user_residential_bytes_limit": 3221225472
}'
```
This creates a new proxy user with a 3 GB data limit. You can use `null` for unlimited data.
`proxy_user_mobile_bytes_limit` can be used to set this for mobile.
### Viewing Individual Proxy User Data Usage
To check a specific proxy user's data usage:
```bash theme={null}
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy_user/retrieve/research_team' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response includes data fields:
```json theme={null}
{
"data": {
"proxy_user_id": "research_team",
// Residential
"proxy_user_residential_bytes_limit": 3221225472,
"proxy_user_residential_bytes_used": 1073741824,
"residential_bytes_left": 2147483648,
// Mobile
"proxy_user_mobile_bytes_limit": 3221225472,
"proxy_user_mobile_bytes_used": 1073741824,
"mobile_bytes_left": 2147483648,
// ... other proxy user fields
},
"message": "Proxy User successfully retrieved."
}
```
## Topping Up Data
While data limits can be managed via the API, purchasing additional data must be done through the dashboard:
1. Log into your Byteful dashboard
2. Click "Add Data" next to your residential or mobile data total on the summary page
3. Choose the amount of data to add
4. Complete the purchase
Once purchased, the additional data is immediately added to your account's pool and never expires.
# Service Adjustments Explained
Source: https://documentation.byteful.com/api-explainers/service-adjustments
Understanding the service adjustment audit trail in the Byteful API
# Service Adjustments
Service Adjustments provide an audit trail of all service modifications, tracking what changed, who made the change, when it occurred, and the values before and after the adjustment.
## Key Components of a Service Adjustment
Each Service Adjustment contains detailed information to fully document a change:
### Identifiers and Metadata
| Field | Description |
| ----------------------------------------- | ---------------------------------------------- |
| `service_adjustment_id` | Unique identifier for the adjustment record |
| `service_id` | ID of the service that was modified |
| `invoice_id` | ID of any invoice generated by this adjustment |
| `service_adjustment_creation_datetime` | When the adjustment was created |
| `service_adjustment_last_update_datetime` | When the adjustment was last updated |
### Type and Status
| Field | Description |
| --------------------------- | -------------------------------------------------- |
| `service_adjustment_type` | The type of adjustment (see types below) |
| `service_adjustment_status` | Current status: `pending`, `complete`, or `failed` |
### Source Tracking
| Field | Description |
| ------------------------------------- | ------------------------------------------------ |
| `service_adjustment_is_administrator` | Whether an administrator made the change |
| `service_adjustment_is_automatic` | Whether the system made the change automatically |
| `service_adjustment_is_customer` | Whether a customer made the change |
### Change Documentation
| Field | Description |
| ------------------------- | ---------------------------------------------------- |
| `service_adjustment_pre` | JSON snapshot of service state before the adjustment |
| `service_adjustment_post` | JSON snapshot of service state after the adjustment |
| `service_adjustment_eval` | Side-by-side comparison of changed values |
## Service Adjustment Types
Service adjustments can be of various types, each representing a different kind of modification:
| Type | Description |
| ------------------------ | --------------------------------------------------------- |
| `ingestion` | Initial creation of a service |
| `fulfillment` | Allocation of proxies to a service |
| `remove_proxy` | Removal of proxies from a service |
| `additional_fulfillment` | Adding more proxies to an existing service |
| `update` | General update to service attributes |
| `proxy_replacement` | Replacing proxies with new ones |
| `extension` | Extending the service period |
| `top_up` | Adding additional data to a residential or mobile service |
| `top_up_and_extension` | Both extending service and adding data |
| `cancel` | Cancellation of a service |
## Understanding the Adjustment Evaluation
The `service_adjustment_eval` field is particularly useful as it provides a clear, side-by-side comparison of the changed values. This field contains an object where:
* Each key represents a field that was changed
* Each value is an array with two elements:
* The first element is the value before the change
* The second element is the value after the change
For example:
```json theme={null}
{
"service_expiry_datetime": ["2023-09-14 18:30:00", "2024-09-14 18:30:00"],
"service_quantity": [5, 10]
}
```
This evaluation shows that the service expiry was extended by one year and the quantity was increased from 5 to 10.
## Special Adjustment Types
### Proxy Replacements
For `proxy_replacement` adjustments, the object will include additional data in a `proxy_replacements` array, which contains records of each proxy that was replaced:
```json theme={null}
{
"proxy_replacements": [
{
"proxy_replacement_id": 7018,
"proxy_replacement_ip_address_ipv4": "107.225.73.142",
"proxy_replacement_new_ip_address_ipv4": "107.225.74.89",
"proxy_replacement_reason": "customer_request"
}
]
}
```
This shows the old and new IP addresses, as well as the reason for the replacement.
## Where Adjustments Come From
Service adjustments are created automatically in response to various events:
1. **Customer Actions**:
* Manually editing a service through the dashboard
* Making changes via the API
* Canceling a service
* Adding data to a residential or mobile service
2. **Administrative Actions**:
* Support staff making changes to services
* Manual adjustments by the Byteful team
3. **Automated System Actions**:
* Automatic fulfillment of newly purchased services
* Scheduled service renewals
* System-initiated proxy replacements
* Error recovery processes
## Accessing Service Adjustments
Service adjustments can be accessed through the API using:
* **Retrieve by ID**: To get details of a specific adjustment
* **Search**: To find adjustments for a particular service or type
When retrieving a service adjustment with a proxy replacement, the response will include details of all replaced proxies to provide a complete picture of what changed.
## How Adjustments Connect to Other Objects
* **Services**: Each adjustment belongs to a specific service
* **Invoices**: Adjustments that involve billing changes reference the corresponding invoice
* **Proxy Replacements**: When proxies are replaced, the adjustment contains replacement details
* **Residential Ledger**: For residential services, data adjustments may link to ledger entries
* **Mobile Ledger**: For mobile services, data adjustments may link to ledger entries
# API Introduction
Source: https://documentation.byteful.com/api-introduction
Welcome to the Byteful API documentation
![Hero Light]()
![Hero Dark]()
## Welcome to the Byteful API
The Byteful API enables you to programmatically manage your proxy infrastructure. Whether you're building a custom integration, automating workflows, or scaling your proxy usage, our RESTful API provides the tools you need.
## Getting Started
Follow these steps to start using the Byteful API:
Sign up for a Byteful account to access our API services
Create API keys in your dashboard to authenticate your API requests
## Core Features
Our API offers comprehensive functionality to manage all aspects of your proxy infrastructure:
Search, retrieve, and manage your proxy inventory programmatically
Create and manage proxy users for secure access control
Manage service subscriptions, view proxy usage, and handle billing
Access detailed analytics and logs for your proxy usage
Services can only be purchased via the API using your account credit balance. You must top up your account with credit prior to using the API to make purchases.
## Examples and Use Cases
Here are some common use cases for the Byteful API:
```bash theme={null}
# Example: Retrieve all ISP proxies in the United States
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/proxy/search?proxy_type=isp&country_id=us' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Create and rotate through proxies to collect data reliably
Handle proxy infrastructure for your AI agents.
Monitor search rankings from various locations globally
## Need Help?
Our team is ready to assist you with API integration and usage:
Reach out to our support team for technical assistance
# ASN
Source: https://documentation.byteful.com/api-objects/asn
Understanding the ASN object and its role in the Byteful API
The ASN (Autonomous System Number) object represents a network or group of networks operated by a single organization in the Byteful system. ASNs are globally unique identifiers assigned to organizations that control blocks of IP addresses, such as internet service providers, hosting companies, and large enterprises.
## Key Attributes
| Attribute | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------- |
| `asn_id` | integer | The unique identifier for the ASN (e.g., 7018 for AT\&T) |
| `asn_name` | string | The name of the organization that owns the ASN |
| `asn_type` | string | Category of the ASN (e.g., isp, hosting, business, cdn, education, gov) |
| `asn_rir` | string | Regional Internet Registry that assigned the ASN (arin, ripe, apnic, lacnic, afrinic) |
| `asn_ip_address_count` | integer | The number of IP addresses allocated to this ASN |
| `country_id` | string | The primary country where the ASN is registered |
## Object Relationships
The ASN object connects with several other objects in the Byteful API:
* **Proxies**: ASNs are assigned to specific proxies, determining their network identity
* **IP Addresses**: Each IP address belongs to an ASN
* **Subnets**: Groups of IP addresses within an ASN
* **Services**: Proxy services may be filtered or targeted by ASN
* **Countries**: ASNs are typically associated with specific countries
```mermaid theme={null}
graph TD
ASN --> Proxies
ASN --> IPAddresses["IP Addresses"]
ASN --> Subnets
Country --> ASN
ASN --> Services
```
## Related Endpoints
| Endpoint | Description |
| ----------------------------------------------- | ------------------------------------------- |
| `GET /public/user/asn/retrieve/{asn_id}` | Retrieve a specific ASN by ID |
| `GET /public/user/asn/search` | Search ASNs using various filters |
| `GET /public/user/proxy/search?asn_id={asn_id}` | Find proxies associated with a specific ASN |
## Usage Notes
* ASNs provide important context about the quality, type, and reputation of proxies
* For residential proxies, you can target specific ASNs in the `/residential/list` endpoint
* For mobile proxies, you can target specific ASNs in the `/mobile/list` endpoint
* The `asn_ip_address_count` gives an indication of the size and potential diversity of IPs within an ASN
## ASN Type Categories
ASNs are categorized into several types, each with distinct characteristics:
| ASN Type | Description | Examples |
| ----------- | -------------------------------------- | ------------------------------- |
| `isp` | Consumer internet service providers | AT\&T (7018), Comcast (7922) |
| `hosting` | Cloud and hosting providers | AWS (16509), Cloudflare (13335) |
| `business` | Enterprise/corporate networks | Apple (714), Microsoft (8075) |
| `cdn` | Content delivery networks | Akamai (20940), Fastly (54113) |
| `education` | Universities and research institutions | MIT (3), Stanford (32) |
| `gov` | Government institutions | US Department of Defense (721) |
When selecting proxies for specific use cases, the ASN type often matters more than the specific ASN itself, as it indicates the general traffic pattern and reputation of the network.
# City
Source: https://documentation.byteful.com/api-objects/city
Understanding the City object and its role in the Byteful API
The City object represents a geographic city in the Byteful system. It contains essential information about a city including its name, location coordinates, timezone, and relationships to larger geographic divisions like countries and subdivisions. The City object is fundamental to the geographic targeting capabilities of proxies, especially for residential proxy services.
## Key Attributes
| Attribute | Type | Description |
| ----------------------- | ------- | ------------------------------------------------------------------------ |
| `city_id` | integer | Unique identifier for the city |
| `city_name` | string | Full name of the city (e.g., "Paris") |
| `city_alias` | string | Human-friendly unique identifier for the city (e.g., "city\_of\_lights") |
| `city_latitude` | number | Latitude coordinates of the city |
| `city_longitude` | number | Longitude coordinates of the city |
| `city_timezone` | string | Timezone of the city (e.g., "Europe/Paris") |
| `city_population` | integer | Population of the city |
| `city_is_populous` | boolean | Indicates if the city is among the populous cities in its region |
| `city_example_postcode` | string | Example postal/zip code for the city |
| `subdivision_id` | string | ID of the subdivision (state/province) where the city is located |
## Object Relationships
The City object is connected to several other objects in the Byteful API:
* **Subdivision**: Each city belongs to a subdivision (state, province, region)
* **Country**: Through the subdivision hierarchy, cities are associated with countries
* **Continent**: Through the country hierarchy, cities are associated with continents
* **Proxies**: Proxies can be geo-located in specific cities
* **Residential Proxies**: Residential proxy generation can target specific cities
* **Mobile Proxies**: Mobile proxy generation can target specific cities
```mermaid theme={null}
graph TD
Continent --> Country
Country --> Subdivision
Subdivision --> City
City --> Proxy
City --> GeneratedResidentialProxy
City --> GeneratedMobileProxy
```
## Related Endpoints
| Endpoint | Description |
| ----------------------------------------------------------- | ------------------------------------------------ |
| `GET /public/user/city/retrieve/{city_id}` | Retrieve a specific city by ID |
| `GET /public/user/city/search` | Search cities using various filters |
| `GET /public/user/residential/list?city_alias={city_alias}` | Generate residential proxies for a specific city |
| `GET /public/user/mobile/list?city_alias={city_alias}` | Generate mobile proxies for a specific city |
## Example Response
```json theme={null}
{
"data": {
"city_alias": "chittagong",
"city_creation_datetime": "2024-07-03 13:48:00",
"city_example_postcode": null,
"city_id": 377157,
"city_is_populous": true,
"city_last_update_datetime": "2024-07-03 13:48:00",
"city_latitude": 22.3384,
"city_longitude": 91.83168,
"city_name": "Chattogram",
"city_node_count": 0,
"city_population": 3920222,
"city_timezone": "asia/dhaka",
"subdivision_id": "bd-b"
},
"message": "City successfully retrieved."
}
```
## Usage Notes
* The `city_alias` is particularly important for residential/mobile proxy targeting
* The `city_is_populous` flag indicates cities that are among the top ten largest in their timezone with at least 300,000 population
* Geographic targeting by city provides the most granular level of geographic control for proxy selection
* Not all cities are available for residential/mobile proxy targeting - generally only those with `city_is_populous` set to true
* The `city_timezone` attribute is useful for time-sensitive operations that need to account for local time
* When searching for cities, you can filter by country using the `country_id` parameter or by subdivision using the `subdivision_id` parameter
* The combination of city latitude and longitude can be used for geolocation services and mapping integrations
# Continent
Source: https://documentation.byteful.com/api-objects/continent
Understanding the Continent object and its role in the Byteful API
The Continent object represents a geographical continent in the Byteful system. It serves as the highest level in the geographic hierarchy and contains essential information about continents including their identifiers, names, and aliases.
## Key Attributes
| Attribute | Type | Description |
| ----------------- | ------ | ----------------------------------------------------------- |
| `continent_id` | string | Unique identifier for the continent (e.g., `eu` for Europe) |
| `continent_name` | string | Full name of the continent (e.g., `Europe`) |
| `continent_alias` | string | Alternative identifier or shorthand for the continent |
## Object Relationships
The Continent object sits at the top of the geographic hierarchy in the Byteful API:
* **Countries**: Each continent contains multiple countries
* **Subdivisions**: Indirectly related through countries
* **Cities**: Indirectly related through countries and subdivisions
* **Proxies**: Proxies can be filtered or grouped by continent through their country associations
```mermaid theme={null}
graph TD
Continent --> Countries
Countries --> Subdivisions
Subdivisions --> Cities
Countries --> Proxies
```
## Related Endpoints
| Endpoint | Description |
| ------------------------------------------------------------- | ------------------------------------------ |
| `GET /public/user/continent/retrieve/{continent_id}` | Retrieve a specific continent by ID |
| `GET /public/user/continent/search` | Search continents using various filters |
| `GET /public/user/country/search?continent_id={continent_id}` | Find countries within a specific continent |
## Example Response
```json theme={null}
{
"data": {
"continent_id": "eu",
"continent_name": "Europe",
"continent_alias": "eu"
},
"message": "Continent successfully retrieved."
}
```
## Usage Notes
* Continents provide the broadest geographic categorization in the system
* The `continent_id` typically uses a two-letter code (e.g., `eu`, `na`, `as`)
* When filtering proxy locations, using continent-level filtering provides the broadest geographic targeting
* The continent object is primarily used for reference and categorization rather than direct operations
* For more precise geographic targeting, use the country, subdivision, or city objects instead
## Continent Codes
The system uses the following standard continent codes:
| Code | Continent |
| ---- | ------------- |
| `af` | Africa |
| `an` | Antarctica |
| `as` | Asia |
| `eu` | Europe |
| `na` | North America |
| `oc` | Oceania |
| `sa` | South America |
These continent codes are consistent throughout the API and provide a standardized way to reference continents when performing geographic filtering or categorization.
# Country
Source: https://documentation.byteful.com/api-objects/country
Understanding the Country object and its role in the Byteful API
The Country object represents a geographic country entity in the Byteful system. It contains essential information about countries including their identifiers, names, geographic location, and special designations such as EU membership status.
## Key Attributes
| Attribute | Type | Description |
| --------------------------- | ------- | ---------------------------------------------------------------------- |
| `country_id` | string | Unique two-letter identifier for the country (ISO 3166-1 alpha-2 code) |
| `country_name` | string | Full name of the country |
| `country_alias` | string | Alternative or shortened identifier for the country |
| `continent_id` | string | Identifier of the continent where the country is located |
| `country_is_european_union` | boolean | Indicates if the country is a member of the European Union |
## Object Relationships
The Country object is connected to several other objects in the Byteful API:
* **Continent**: Each country belongs to a specific continent
* **Subdivisions**: Countries contain multiple subdivisions (states, provinces, regions)
* **Cities**: Countries contain multiple cities directly or through subdivisions
* **Proxies**: Proxies are physically located within countries
* **Products**: Products may be region-specific and tied to particular countries
* **Services**: Services may be region-specific and tied to particular countries
```mermaid theme={null}
graph TD
Continent --> Country
Country --> Subdivision
Subdivision --> City
Country -.-> Proxy
Country -.-> Product
Country -.-> Service
```
## Related Endpoints
| Endpoint | Description |
| ------------------------------------------------------------- | -------------------------------------- |
| `GET /public/user/country/retrieve/{country_id}` | Retrieve a specific country |
| `GET /public/user/country/search` | Search countries with various filters |
| `GET /public/user/subdivision/search?country_id={country_id}` | Get subdivisions in a specific country |
## Example Response
```json theme={null}
{
"data": {
"continent_id": "eu",
"country_alias": "fr",
"country_id": "fr",
"country_is_european_union": true,
"country_name": "France"
},
"message": "Country successfully retrieved."
}
```
## Usage Notes
* The `country_id` uses the ISO 3166-1 alpha-2 standard (e.g., "us" for United States, "gb" for United Kingdom)
* Country objects are most commonly used as filters when:
* Searching for proxies in specific geographic regions
* Generating residential proxy lists with geographic targeting
* Purchasing region-specific proxy services
* Analyzing usage patterns across different geographic regions
* The `country_is_european_union` flag is particularly useful for compliance with GDPR and other EU-specific regulations
* For more granular geographic targeting, combine country filters with subdivision and city filters
* When working with products and services, `country_id` is commonly used to identify region-specific offerings
## Geographic Hierarchy
Countries are part of a larger geographic hierarchy in the Byteful system:
1. **Continent**: The broadest geographic division
2. **Country**: Countries within continents
3. **Subdivision**: States, provinces, or regions within countries
4. **City**: Specific cities within subdivisions
This hierarchical structure allows for increasingly precise geographic targeting of proxies.
# Customer
Source: https://documentation.byteful.com/api-objects/customer
Understanding the Customer object and its role in the Byteful API
The Customer object represents an account holder in the Byteful system. It contains essential information about a user including their contact details, billing information, and account settings.
## Key Attributes
| Attribute | Type | Description |
| ------------------------------- | ------- | --------------------------------------------------- |
| `customer_id` | integer | Unique identifier for the customer |
| `customer_email_address` | string | Primary email address for the account |
| `customer_first_name` | string | Customer's first name |
| `customer_last_name` | string | Customer's last name |
| `credit_balance` | integer | Available credit balance in cents |
| `customer_proxy_user_limit` | integer | Maximum number of proxy users allowed |
| `proxy_count` | integer | Total number of proxies associated with the account |
| `residential_bytes_left` | integer | Remaining residential data in bytes |
| `active_residential_service_id` | string | ID of the active residential service |
| `mobile_bytes_left` | integer | Remaining mobile data in bytes |
| `active_mobile_service_id` | string | ID of the active mobile service |
## Object Relationships
The Customer object is a parent to several other objects in the Byteful API:
* **Proxy Users**: Authentication entities created by the customer
* **Services**: Subscriptions to proxy products
* **Proxies**: Individual proxies allocated to the customer's services
* **Residential Ledger**: Records of residential data usage
* **Mobile Ledger**: Records of mobile data usage
```mermaid theme={null}
graph TD
Customer --> ProxyUsers["Proxy Users"]
Customer --> Services
Services --> Proxies
Customer --> ResidentialLedger["Residential Ledger"]
Customer --> MobileLedger["Mobile Ledger"]
```
## Related Endpoints
| Endpoint | Description |
| ------------------------------------ | --------------------------------------------- |
| `GET /public/user/customer/retrieve` | Retrieve the authenticated customer's profile |
## Example Response
```json theme={null}
{
"data": {
"customer_id": 1955,
"customer_email_address": "steve.jobs@apple.com",
"customer_first_name": "Steve",
"customer_last_name": "Jobs",
"credit_balance": 1245,
"customer_proxy_user_limit": 5,
"proxy_count": 100,
"residential_bytes_left": 10737418240,
"active_residential_service_id": "1955-8012-871",
"mobile_bytes_left": 10737418240,
"active_mobile_service_id": "1935-1517-112"
},
"message": "Customer successfully retrieved."
}
```
## Usage Notes
* The `credit_balance` is displayed in cents (e.g., 1245 means \$12.45)
* When purchasing via API, services must be paid with account credit
* The `residential_bytes_left` shows remaining data for residential proxies
* The `mobile_bytes_left` shows remaining data for mobile proxies
* The `customer_proxy_user_limit` determines how many proxy users you can create
## Best Practices
* Regularly check your `credit_balance` before making API purchases
* Monitor your `residential_bytes_left` and `mobile_bytes_left` to avoid service interruptions
* Use the `customer_id` to reference your account in support requests
# Log
Source: https://documentation.byteful.com/api-objects/log
Understanding the Log object and its role in the Byteful API
The Log object represents an individual proxy request in the Byteful system. It contains detailed information about proxy usage, including client information, geographic data, request details, and timestamps. Logs provide granular visibility into how your proxies are being utilized and are crucial for troubleshooting, usage analysis, and security monitoring.
## Key Attributes
| Attribute | Type | Description |
| ------------------------- | -------- | --------------------------------------------------- |
| `log_id` | string | Unique identifier for the log entry |
| `proxy_user_id` | string | ID of the proxy user that made the request |
| `service_id` | string | ID of the service associated with the proxy |
| `log_network` | string | Network type (datacenter, isp, residential, mobile) |
| `log_protocol` | string | Protocol used (http, socks) |
| `log_hostname` | string | The target domain of the request |
| `log_client_ip_address` | string | IP address of the client that made the request |
| `log_total_bytes` | integer | Total data transferred in bytes |
| `log_request_datetime` | datetime | When the request was made |
| `log_authentication_type` | integer | Authentication method used |
| `log_session_id` | string | Session identifier for tracking related requests |
| `country_id` | string | Country code where the request was processed |
| `city_alias` | string | City identifier where the request was processed |
| `asn_id` | integer | ASN (Autonomous System Number) identifier |
## Data Retention
Raw logs are stored for a limited time period:
* Individual request logs are retained for **7 days**
* Logs are instantly aggregated into `log_summary` objects when created
* After the 7-day period, individual logs are removed and data is accessible only through the aggregated `log_summary` objects
## Object Relationships
The Log object is connected to several other objects in the Byteful system.
* **Proxy User**: Each log is associated with the proxy user that made the request
* **Service**: Logs are linked to the service that provided the proxy
* **Log Summary**: Logs are instantly aggregated into log summaries at creation time
* **Geographic Entities**: Logs contain references to country, city, and ASN information
## Related Endpoints
| Endpoint | Description |
| ---------------------------------------- | -------------------------------- |
| `GET /public/user/log/search` | Search logs with various filters |
| `GET /public/user/log/retrieve/{log_id}` | Retrieve a specific log entry |
| `GET /public/user/analytics/graph` | Graph data derived from logs |
## Example Log Object
```json theme={null}
{
"log_id": "123e4567-e89b-12d3-a456-426614174000",
"proxy_user_id": "stevejobs",
"log_network": "isp",
"log_protocol": "http",
"log_hostname": "apple.com",
"log_client_ip_address": "17.172.224.1",
"log_total_bytes": 5120,
"log_request_datetime": "2025-04-01 13:00:00",
"country_id": "us",
"city_alias": "cupertino",
"asn_id": 1299
}
```
## Usage Notes
* Logs provide the most detailed view of proxy activity but are only available for a short time period (7 days)
* For each request through a proxy, a corresponding log entry is created and simultaneously aggregated into a log summary
* Multiple filtering options are available to analyze logs by user, domain, location, and more
* For residential/mobile proxies, logs contribute to data usage calculations in the `residential_ledger` and `mobile_ledger`
* Log entries include information about the client making the request, which helps with troubleshooting and identifying potential abuse
* For long-term analysis, use `log_summary` objects which retain aggregated data for 90+ days
* While individual logs are removed after 7 days, the aggregated data in log summaries remains accessible
# Log Summary
Source: https://documentation.byteful.com/api-objects/log-summary
Understanding the Log Summary object and its role in the Byteful API
The Log Summary object represents aggregated usage data for proxies in the Byteful system. It provides a consolidated view of proxy usage patterns over time, offering insights into data consumption, request counts, and more, without the granularity of individual log entries.
## Key Attributes
| Attribute | Type | Description |
| ---------------------------------- | -------- | ------------------------------------------------------------- |
| `log_summary_id` | string | Unique identifier for the log summary |
| `proxy_user_id` | string | ID of the proxy user whose activity is summarized |
| `customer_id` | integer | ID of the customer account associated with the summary |
| `log_summary_network` | string | Network type (`datacenter`, `isp`, `residential` or `mobile`) |
| `log_summary_hostname` | string | Domain that was accessed through the proxy |
| `log_summary_requests` | integer | Total number of requests during the period |
| `log_summary_bytes` | integer | Total data usage in bytes |
| `log_summary_period` | datetime | Time period the summary represents |
| `log_summary_creation_datetime` | datetime | When the summary was created |
| `log_summary_last_update_datetime` | datetime | When the summary was last updated |
## Object Relationships
The Log Summary object connects several other entities in the Byteful system:
* **Customer**: Each log summary is associated with a specific customer account
* **Proxy User**: Log summaries track usage for specific proxy users
* **Logs**: Raw logs are aggregated into log summaries
* **Residential Ledger**: Both log summaries and residential ledger track data usage, but serve different purposes (analytics vs. billing)
* **Mobile Ledger**: Both log summaries and mobile ledger track data usage, but serve different purposes (analytics vs. billing)
## Related Endpoints
| Endpoint | Description |
| -------------------------------------------------------- | --------------------------------------------- |
| `GET /public/user/log_summary/retrieve/{log_summary_id}` | Retrieve a specific log summary |
| `GET /public/user/log_summary/search` | Search log summaries with filters |
| `GET /public/user/analytics/graph` | Generate visualizations from log summary data |
## Data Retention and Analytics
Log Summaries follow a tiered retention and aggregation policy:
* **First 90 days**: Organized by `proxy_user_id`, `network`, and `hostname`
* **After 90 days**: Further consolidated to just `proxy_user_id` and `network` level (hostname details are removed)
* **Long-term storage**: Maintained indefinitely but with reduced granularity
* **Analytics Integration**: The `/analytics/graph` endpoint processes data from both raw logs and log summaries, providing comprehensive analytics regardless of data age
This provides an efficient way to analyze historical usage patterns without storing every individual request.
## Usage Notes
* Log Summaries are automatically generated daily for active proxy users
* They provide a more efficient way to analyze usage trends compared to raw logs
* The `log_summary_hostname` field is only available for summaries less than 90 days old
* For residential/mobile proxies, the `log_summary_bytes` directly correlates with data consumption
* Use the `/analytics/graph` endpoint for visualizing log summary data over time with flexible time intervals (minute, hour, day, month)
* Log Summaries and Residential/Mobile Ledgers track related data but serve different purposes:
* Log Summaries focus on usage patterns and analytics across all proxy types
* Residential/Mobile Ledgers specifically tracks data changes for billing purposes
* While not directly linked, the data from both should reconcile in aggregate
# Mobile Ledger
Source: https://documentation.byteful.com/api-objects/mobile-ledger
Understanding the Mobile Ledger object and its role in the Byteful API
The Mobile Ledger object represents a record of mobile data usage or allocation in the Byteful system. It serves as a complete audit trail that tracks all changes to the mobile data pool associated with a customer account, including daily usage consumption, top-ups, service purchases, and administrative adjustments.
## Key Attributes
| Attribute | Type | Description |
| ------------------------------------ | -------- | --------------------------------------------------------------------------- |
| `mobile_ledger_id` | string | Unique identifier for the ledger entry |
| `mobile_ledger_bytes` | integer | Amount of data in bytes associated with this ledger entry |
| `mobile_ledger_requests` | integer | Number of requests associated with this ledger entry |
| `mobile_ledger_period_date` | string | The date this ledger entry is associated with |
| `mobile_ledger_reason` | string | Reason for the ledger entry (e.g., "usage", "top\_up", "service\_purchase") |
| `service_id` | string | ID of the related service if applicable |
| `service_adjustment_id` | integer | ID of the related service adjustment if applicable |
| `mobile_ledger_creation_datetime` | datetime | When the ledger entry was created |
| `mobile_ledger_last_update_datetime` | datetime | When the ledger entry was last updated |
## Object Relationships
The Mobile Ledger object is connected to several other objects in the Byteful API:
* **Customer**: Each mobile ledger entry belongs to a customer account
* **Service**: Entries may be associated with a mobile service (e.g., when purchasing additional data)
* **Service Adjustment**: Entries may be linked to service adjustments (e.g., refunds or manual adjustments)
* **Proxy User**: While not directly linked, proxy users consume data which creates ledger entries
```mermaid theme={null}
graph TD
Customer --> MobileLedger["mobile Ledger"]
Service --> MobileLedger
ServiceAdjustment --> MobileLedger
ProxyUser -.-> MobileLedger["Creates entries through usage"]
```
## Related Endpoints
| Endpoint | Description |
| ------------------------------------------------------------ | ----------------------------------------- |
| `GET /public/user/mobile_ledger/retrieve/{mobile_ledger_id}` | Retrieve a specific mobile ledger entry |
| `GET /public/user/mobile_ledger/search` | Search mobile ledger entries with filters |
| `GET /public/user/mobile/summary` | Get a summary of mobile data status |
## Example Response
```json theme={null}
{
"data": {
"customer_id": 1955,
"mobile_ledger_bytes": 128290101,
"mobile_ledger_creation_datetime": "2023-04-01 12:00:00",
"mobile_ledger_id": "123e4567-e89b-12d3-a456-426614174000",
"mobile_ledger_last_update_datetime": "2023-04-02 12:00:00",
"mobile_ledger_period_date": "2023-10-01",
"mobile_ledger_reason": "top_up",
"mobile_ledger_requests": 1244,
"service_adjustment_id": 10,
"service_id": "API-1234-5678"
},
"message": "Mobile Ledger successfully retrieved."
}
```
## Ledger Entry Types
Mobile ledger entries have various reason types that indicate different data changes:
| Reason | Description |
| ------------ | ---------------------------------------------------------------- |
| `usage` | Daily decrements to the data pool from proxy usage |
| `top_up` | Increments from purchasing additional data |
| `adjustment` | Manual adjustments (positive or negative) made by administrators |
## Usage Notes
* The mobile ledger is maintained at the account data pool level, not per proxy
* Usage entries are aggregated daily, providing a day-by-day audit trail of data consumption
* Entries with positive `mobile_ledger_bytes` values add to your data pool (top-ups, purchases)
* Entries with negative `mobile_ledger_bytes` values subtract from your data pool (usage)
* The `mobile_ledger_period_date` field indicates the specific day when usage occurred or changes were made
* Unlike datacenter and ISP proxies, mobile proxies operate on a data-based billing model
* There is no automatic expiration for mobile data - it remains in your account until consumed
* For real-time data status, use the `/mobile/summary` endpoint
# Product
Source: https://documentation.byteful.com/api-objects/product
Understanding the Product object and its role in the Byteful API
The Product object represents a proxy product or service available for purchase in the Byteful system. It contains essential information about the product including its type, characteristics, pricing options, and availability.
## Key Attributes
| Attribute | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `product_id` | string | Unique identifier for the product |
| `product_name` | string | Name of the product as displayed to customers |
| `product_type` | string | Type of product (datacenter, isp, residential, mobile, credit) |
| `product_protocol` | string | IP protocol supported by the product (ipv4, ipv6, dual) |
| `product_is_active` | boolean | Indicates if the product is currently active |
| `product_is_available` | boolean | Indicates if the product is available for purchase |
| `product_is_visible` | boolean | Indicates if the product is visible in product listings |
| `product_is_per_ip` | boolean | Indicates if the product is sold on a per-IP basis |
| `product_stock` | integer | Number of units available for purchase |
| `country_id` | string | Country code where the product is located (for region-specific products) |
| `product_prices` | array | List of pricing options with different billing cycles |
## Product Prices
Each product contains an array of price objects with the following structure:
| Attribute | Type | Description |
| ---------------------------- | ------- | ------------------------------------------- |
| `price_id` | string | Unique identifier for the price |
| `price_type` | string | Type of price (recurring, one\_time) |
| `price_amount` | integer | Cost in cents |
| `price_is_subscription` | boolean | Whether the price represents a subscription |
| `price_cycle_interval` | string | Billing interval (month, year) |
| `price_cycle_interval_count` | integer | Number of intervals for billing cycle |
| `price_tier_type` | string | Type of pricing tier (volume, graduated) |
| `price_tiers` | array | Array of pricing tiers for volume pricing |
## Object Relationships
The Product object is connected to several other objects in the Byteful API:
* **Checkout Catalog**: Products are summarized in the checkout catalog for purchase
* **Services**: When purchased, a product creates a service
* **Countries**: Products may be region-specific and tied to particular countries
## Related Endpoints
| Endpoint | Description |
| ----------------------------------- | ------------------------------------------- |
| `GET /public/user/product/search` | Search products with various filters |
| `GET /public/user/checkout/catalog` | Get simplified product listing for checkout |
## Example Response
```json theme={null}
{
"data": [
{
"product_id": "prod_RCLjwcUyqkfd2f",
"product_name": "Static Residential ISP Proxies [FR]",
"product_type": "isp",
"product_protocol": "ipv4",
"product_is_active": true,
"product_is_available": false,
"product_is_visible": true,
"product_is_per_ip": true,
"product_stock": 0,
"country_id": "fr",
"product_image": "https://files.stripe.com/links/MDB8YWNjdF8xSDdkOEFCMkJVbHFpbTVsfGZsX2xpdmVfNU9KWUZCTnp4djA0dmpuV3F0bjM2ck9i00dSLST0rl",
"product_description": null,
"product_instock": false,
"product_prices": [
{
"price_id": "price_1QJx2EB2BUlqim5ltggZJfyY",
"price_type": "recurring",
"price_is_subscription": true,
"price_cycle_interval": "month",
"price_cycle_interval_count": 1,
"price_tier_type": "volume",
"price_tiers": [
{
"price_tier_up_to": 1,
"price_tier_amount": 350
}
]
}
]
}
]
}
```
## Usage Notes
* The `product_stock` indicates real-time availability for purchase
* A value of `0` for `product_stock` means the product is out of stock
* A value of `-1` for `product_stock` means the product has infinite stock (typically for residential products)
* The `product_protocol` indicates which IP versions are supported (IPv4, IPv6, or both)
* The `product_prices` array shows all available pricing options and billing cycles
* For `residential` and `mobile` products, pricing is data-based rather than per-IP
* The `product_is_per_ip` flag distinguishes between per-IP pricing (datacenter/ISP) and data-based pricing (residential/mobile)
* Products with `country_id` are region-specific, while those without may be global
* The `price_amount` and `price_tier_amount` are in cents (e.g., 350 means \$3.50)
## Product Types
| Type | Description |
| ------------- | ---------------------------------------------------------- |
| `datacenter` | Commercial datacenter proxies with high speed |
| `isp` | Static residential ISP proxies with carrier legitimacy |
| `residential` | Dynamic residential proxies from real consumer connections |
| `mobile` | Dynamic mobile proxies from real mobile devices |
| `credit` | Account credit that can be applied to purchases |
# Proxy
Source: https://documentation.byteful.com/api-objects/proxy
Understanding the Proxy object and its role in the Byteful API
The Proxy object represents an individual proxy instance in the Byteful system. It contains essential information about a proxy including its network details, authentication settings, geographic location, and operational status.
## Key Attributes
| Attribute | Type | Description |
| ------------------- | ------- | ---------------------------------------------------------------- |
| `proxy_id` | string | Unique identifier for the proxy (UUID format) |
| `proxy_ip_address` | string | Main IPv4 address of the proxy |
| `proxy_protocol` | string | IP protocol of the proxy (ipv4, ipv6, dual) |
| `proxy_type` | string | Type of proxy (datacenter, isp, residential, mobile) |
| `proxy_http_port` | integer | HTTP port number for the proxy |
| `proxy_socks5_port` | integer | SOCKS5 port number for the proxy |
| `proxy_status` | string | Current status of the proxy (available, in\_use, reserved, etc.) |
| `service_id` | string | ID of the service this proxy is associated with |
| `country_id` | string | ISO country code where the proxy is located |
| `asn_id` | integer | Autonomous System Number (network provider) |
| `city_id` | integer | ID of the city where the proxy is located |
| `subdivision_id` | string | ID of the region/state where the proxy is located |
## Network Attributes
The Proxy object includes detailed network information:
| Attribute | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------ |
| `ip_address_id_v4` | string | IPv4 address identifier |
| `ip_address_id_v6` | string | IPv6 address identifier (for dual or ipv6 proxies) |
| `subnet_id` | string | IPv4 subnet the proxy belongs to |
| `subnet_id_v6` | string | IPv6 subnet the proxy belongs to (for dual or ipv6 proxies) |
| `asn_name` | string | Name of the Autonomous System (e.g., "AT\&T Services, Inc.") |
## Geographic Attributes
Proxies include detailed geographic information:
| Attribute | Type | Description |
| ------------------ | ------ | --------------------------------------------------- |
| `country_name` | string | Full name of the country (e.g., "United States") |
| `subdivision_name` | string | Full name of the region/state (e.g., "California") |
| `city_name` | string | Full name of the city (e.g., "Los Angeles") |
| `city_latitude` | number | Latitude coordinates of the city |
| `city_longitude` | number | Longitude coordinates of the city |
| `city_timezone` | string | Timezone of the city (e.g., "America/Los\_Angeles") |
## Object Relationships
The Proxy object connects to several other objects in the Byteful API:
* **Service**: Each proxy belongs to a service subscription
* **Customer**: Proxies are ultimately owned by a customer through services
* **Proxy User**: Proxy users can access proxies for authentication
* **ASN**: Provides network operator details for the proxy
* **Geographic Entities**: Country, subdivision, and city information
```mermaid theme={null}
graph TD
Service --> Proxy
ProxyUser -.-> Proxy
Proxy --> ASN
Proxy --> Country
Country --> Subdivision
Subdivision --> City
```
## Proxy Status Values
| Status | Description |
| ------------------ | ------------------------------------------------------------- |
| `available` | Proxy is ready but not actively assigned |
| `in_use` | Proxy is actively assigned to a service and available for use |
| `reserved` | Proxy is reserved for future use |
| `waiting` | Proxy is being provisioned or prepared |
| `pending_deletion` | Proxy is scheduled for removal |
## Related Endpoints
| Endpoint | Description |
| -------------------------------------------- | ------------------------------------ |
| `GET /public/user/proxy/retrieve/{proxy_id}` | Retrieve a specific proxy |
| `GET /public/user/proxy/search` | Search proxies with filters |
| `GET /public/user/proxy/list_by_search` | Retrieve formatted proxy lists |
| `POST /public/user/proxy/list_by_id` | Generate formatted proxy lists by ID |
## Usage Notes
* Proxies can be accessed using the default proxy user or proxy-specific authentication
* For IPv4 proxies, use `proxy_ip_address` or `ip_address_id_v4` (they contain the same value if you've purchased IPv4 proxies)
* For IPv6 or dual-stack proxies, the IPv6 address is stored in `ip_address_id_v6`
* The combination of IP address and port is unique to each proxy
* When listing proxies, the proxy object will include additional formatted fields:
* `http_formatted`: Formatted HTTP proxy string
* `socks5_formatted`: Formatted SOCKS5 proxy string
## Authentication Methods
Proxies can be accessed using three authentication methods:
1. **Proxy User Authentication**: Using a proxy user's credentials
2. **IP Authentication**: Allowing specific client IP addresses
3. **Proxy-Specific Authentication**: Using credentials specific to a single proxy
## Proxy Types and Differences
Each proxy type has unique characteristics:
* **Datacenter Proxies**: Static proxies hosted in data centers
* **ISP Proxies**: Static proxies with residential-type IP addresses from major ISPs
* **Residential Proxies**: Dynamic proxies from real residential connections
* **Mobile Proxies**: Dynamic proxies from real mobile phones
While datacenter and ISP proxies are represented as persistent proxy objects, residential and mobile proxies are generated dynamically and don't have persistent proxy objects.
# Proxy Testing
Source: https://documentation.byteful.com/api-objects/proxy-tester
Understanding the Proxy Tester and its role in the Byteful API
## Object Relationships
The Continent object sits at the top of the geographic hierarchy in the Byteful API:
* **Proxy Test Run**: The whole test that has run
* **Proxy Tester Proxy**: Each proxy that has been tested
* **Proxy Test Result**: The result of the test for a given proxy
* **Proxy Test Server**: The server being used for each proxy test
In the scenario below, **proxy A** and **proxy B** are being tested against `test_server_gb` and `test_server_us`.
The following objects are created:
```mermaid theme={null}
graph TD
A[Proxy Test Run] --> B["Proxy Tester Proxy (A)"]
A --> C["Proxy Tester Proxy (B)"]
B --> D["Proxy Test Result (1)
test_server_gb"]
B --> E["Proxy Test Result (2)
test_server_us"]
C --> F["Proxy Test Result (3)
test_server_gb"]
C --> G["Proxy Test Result (4)
test_server_us"]
classDef testRun fill:#A192EC,stroke:#553c9a,stroke-width:2px,color:#fff
classDef proxy fill:#48bb78,stroke:#1fb356,stroke-width:2px,color:#fff
classDef testResult fill:#4299e1,stroke:#2b6cb0,stroke-width:2px,color:#fff
class A testRun
class B,C proxy
class D,E,F,G testResult
```
## Key Components
### Proxy Test Run
The core testing workflow that orchestrates proxy validation across multiple test servers and target URLs.
| Attribute | Type | Description |
| ------------------------ | ------------------------ | -------------------------------------------------------------------- |
| `proxy_test_run_id` | string (uuid) (optional) | Unique identifier for the test run |
| `proxies` | array | List of proxy objects to test with their configurations (Maximum 20) |
| `urls` | array | Target URLs to test against |
| `proxy_tester_server_id` | array (optional) | Test servers to use for validation |
If no test server is provided, all test servers will be used.
No more than 20 proxies can be tested in the same request.
### Proxy Test Result
Individual test results for each proxy-URL-server combination.
| Attribute | Type | Description |
| --------------------------------- | ------------- | ---------------------------------------------------------- |
| `proxy_test_result_id` | string (uuid) | Unique identifier for this specific test result |
| `proxy_test_result_url` | string | The URL that was tested |
| `proxy_test_result_is_successful` | boolean | Whether the test was completed successfully |
| `proxy_test_result_error_code` | integer | The error code that was returned in the event of a failure |
| `proxy_test_result_error_source` | integer | Stage at which the error occurred (client/proxy/target) |
| `proxy_test_result_protocol` | string | Protocol used |
| `proxy_test_result_response_time` | integer | Response time in milliseconds |
| `proxy_test_server_id` | string | ID of the test server used |
| `proxy_test_server_city_name` | string | City where the test server is located |
| `proxy_test_server_country_id` | string | Country code of the test server |
| `proxy_username` | string | Username used for proxy authentication |
| `proxy_host` | string | Proxy server hostname/IP |
| `proxy_port` | integer | Proxy server port |
| `proxy_country_id` | string | Country where the proxy is located |
| `proxy_city_name` | string | City where the proxy is located |
| `proxy_asn_name` | string | ASN information for the proxy |
### Proxy Errors
If `proxy_test_result_is_successful` is not `true`, an error occurred during the testing process.
**Code** - The error code will describe the error that occurred. For example: `dns_error`.
**Source** - The source will describe the stage of the proxy testing process that the error occurred. For example: `client`.
* **Client** - The error occurred within the client, before a connection was made to the proxy server. For example, a **DNS lookup failure**.
* **Proxy** - The error occurred whilst connecting to the proxy server. For example, **invalid authentication**.
* **Target** - The error occurred whilst connecting to the target. For example, **not found**.
### Proxy Test Server
Geographic test servers that perform the actual proxy validation.
| Attribute | Type | Description |
| ------------------------------ | ------- | -------------------------------------- |
| `proxy_test_server_id` | string | Unique identifier for the test server |
| `city_name` | string | City where the test server is located |
| `country_id` | string | Country code of the test server |
| `proxy_test_server_active` | boolean | Whether the server is currently active |
| `proxy_test_server_ip_address` | string | IP address of the test server |
| `proxy_test_server_port` | integer | Port used by the test server |
## Related Endpoints
| Endpoint | Description |
| ------------------------------------------- | --------------------------- |
| `POST /public/user/proxy_test_run/create` | Create a new proxy test run |
| `GET /public/user/proxy_test_server/search` | Get available test servers |
# Proxy User
Source: https://documentation.byteful.com/api-objects/proxy-user
Understanding the Proxy User object and its role in the Byteful API
The Proxy User object represents an authentication entity used to access proxies. It functions as a layer between your customer account and your proxies, enabling flexible access control, usage tracking, and data management.
## Key Attributes
| Attribute | Type | Description |
| ------------------------------------ | ------- | -------------------------------------------------------------------------------------------- |
| `proxy_user_id` | string | Unique identifier for the proxy user (acts as username) |
| `proxy_user_password` | string | Password for proxy authentication |
| `proxy_user_access_type` | string | Access control type: `"all"` (unrestricted), `"service_restricted"`, or `"proxy_restricted"` |
| `proxy_user_is_strict_security` | boolean | Whether IP authentication is required |
| `proxy_user_residential_bytes_limit` | integer | Maximum residential data allocation in bytes |
| `proxy_user_residential_bytes_used` | integer | Used residential data in bytes |
| `proxy_user_mobile_bytes_limit` | integer | Maximum mobile data allocation in bytes |
| `proxy_user_mobile_bytes_used` | integer | Used mobile data in bytes |
| `proxy_user_metadata` | object | Custom metadata for tracking and organization |
| `ip_address_authentications` | array | List of IP addresses authorized to use this proxy user |
## Authentication Methods
Proxy Users support three authentication methods:
1. **Username/Password Authentication**: Standard method using `proxy_user_id` and `proxy_user_password`
2. **IP Authentication**: Access based on client IP address matching entries in `ip_address_authentications`
3. **Combined Authentication**: Requiring both username/password and IP authentication when `proxy_user_is_strict_security` is enabled
## Access Control
Proxy Users support three access control types via the `proxy_user_access_type` field:
* **`"all"`** (default): Unrestricted access to all proxies in your account
* **`"service_restricted"`**: Access limited to specific services via Proxy User ACL entries
* **`"proxy_restricted"`**: Access limited to specific individual proxies via Proxy User ACL entries
When using `"service_restricted"` or `"proxy_restricted"` access types, you must create Proxy User ACL entries to grant access to specific services or proxies. See the [Proxy User ACL object documentation](/api-objects/proxy-user-acl) for details.
## Object Relationships
The Proxy User acts as an intermediary between your customer account and your proxy services:
```mermaid theme={null}
graph TD
Customer --> ProxyUser1[Proxy User 1]
ProxyUser1 --> ACL[Proxy User ACL]
ACL --> Service1[Service]
Service1 --> Proxy1[Proxy]
ProxyUser1 --> LogSummary[Log Summary]
ProxyUser1 --> Log[Log]
```
* **Customer**: A single customer can have multiple proxy users
* **Proxy User ACL**: Controls which services or proxies a proxy user can access (when access\_type is restricted)
* **Services**: A proxy user can access multiple services based on their ACL entries
* **Proxies**: Proxies are accessed through proxy users, which control authentication and authorization
* **Logs**: Usage logs are associated with specific proxy users for tracking
* **Log Summaries**: Aggregated usage data is linked to proxy users
## Related Endpoints
| Endpoint | Method | Description |
| -------------------------------------------------- | ------ | ------------------------------- |
| `/public/user/proxy_user/create` | POST | Create a new proxy user |
| `/public/user/proxy_user/retrieve/{proxy_user_id}` | GET | Retrieve a specific proxy user |
| `/public/user/proxy_user/search` | GET | Search proxy users with filters |
| `/public/user/proxy_user/edit/{proxy_user_id}` | PATCH | Edit an existing proxy user |
| `/public/user/proxy_user/delete/{proxy_user_id}` | DELETE | Delete a proxy user |
## Example Response
```json theme={null}
{
"data": {
"proxy_user_id": "stevejobs",
"proxy_user_password": "apple1984",
"proxy_user_access_type": "all",
"proxy_user_ip_address_authentication_limit": 3,
"proxy_user_is_default": false,
"proxy_user_is_deleted": false,
"proxy_user_is_strict_security": false,
"proxy_user_metadata": {
"resell_order_id": "APPL-9876-5432"
},
"proxy_user_residential_bytes_limit": 134142432,
"proxy_user_residential_bytes_used": 31223,
"residential_bytes_left": 134111209,
"proxy_user_mobile_bytes_limit": 134142432,
"proxy_user_mobile_bytes_used": 31223,
"mobile_bytes_left": 134111209,
"ip_address_authentications": [
"193.222.13.1"
],
"restricted_service_ids": [],
"restricted_proxy_ids": []
},
"message": "Proxy User successfully retrieved."
}
```
## Usage Notes
* Each customer account can have multiple proxy users (limited by `customer_proxy_user_limit`)
* The default proxy user is automatically created with each account
* Proxy users can be used for traditional proxies, mobile and residential services
* Use proxy users to organize access to different proxy groups or for different teams
* Metadata allows for custom organization (e.g., by department, project, or client)
* For access control, use the `proxy_user_access_type` field in combination with [Proxy User ACL](/api-objects/proxy-user-acl) entries
# Proxy User ACL
Source: https://documentation.byteful.com/api-objects/proxy-user-acl
Understanding the Proxy User ACL object and its role in access control
The Proxy User ACL (Access Control List) object defines granular access permissions for proxy users. It allows you to control whether a proxy user can access specific services or individual proxies, enabling flexible access management for different use cases such as team segregation, reselling, or fine-grained security controls.
Default Proxy Users cannot have ACL rules applied and have access to all proxies on your account.
## Key Attributes
| Attribute | Type | Description |
| ---------------------------------- | -------- | ------------------------------------------------------------------ |
| `proxy_user_acl_id` | string | Unique identifier for the ACL entry (UUID format) |
| `proxy_user_id` | string | ID of the proxy user this ACL entry applies to |
| `service_id` | string | Service ID to grant access to (mutually exclusive with `proxy_id`) |
| `proxy_id` | string | Proxy ID to grant access to (mutually exclusive with `service_id`) |
| `proxy_user_acl_creation_datetime` | datetime | Timestamp when the ACL entry was created |
## Access Control Model
Proxy User ACL entries work in conjunction with the `proxy_user_access_type` field on the Proxy User object:
* **`access_type: "all"`**: No ACL entries needed. Proxy user has unrestricted access to all proxies.
* **`access_type: "service_restricted"`**: ACL entries with `service_id` define which services the proxy user can access. The user can use any proxy within those services.
* **`access_type: "proxy_restricted"`**: ACL entries with `proxy_id` define which specific individual proxies the proxy user can access.
Each ACL entry must contain **either** a `service_id` **or** a `proxy_id`, but never both. The type of ID must match the proxy user's `access_type`.
## Use Cases
### Service-Restricted Access
Perfect for organizing proxy access by teams, departments, or customers:
```json theme={null}
{
"proxy_user_id": "seo_team",
"service_id": "API-SEO-POOL-001"
}
```
The `seo_team` proxy user can access all proxies in the `API-SEO-POOL-001` service.
### Proxy-Restricted Access
Ideal for reselling individual proxies or highly granular access control:
```json theme={null}
{
"proxy_user_id": "customer_123",
"proxy_id": "550e8400-e29b-41d4-a716-446655440001"
}
```
The `customer_123` proxy user can only access this specific proxy.
## Object Relationships
The Proxy User ACL creates a many-to-many relationship between proxy users and their accessible resources:
```mermaid theme={null}
graph TD
ProxyUser[Proxy User] --> ACL1[Proxy User ACL]
ProxyUser --> ACL2[Proxy User ACL]
ACL1 --> Service[Service]
ACL2 --> Proxy[Individual Proxy]
Service --> Proxy1[Proxy 1]
Service --> Proxy2[Proxy 2]
Service --> Proxy3[Proxy 3]
```
* **Proxy User**: A single proxy user can have multiple ACL entries
* **Service**: When an ACL grants service access, the user can access all proxies in that service
* **Proxy**: When an ACL grants proxy access, the user can only access that specific proxy
* **Multiple ACLs**: You can create multiple ACL entries to grant access to multiple services or proxies
## Related Endpoints
| Endpoint | Method | Description |
| ---------------------------------------------------------- | ------ | ------------------------------- |
| `/public/user/proxy_user_acl/create` | POST | Create a new ACL entry |
| `/public/user/proxy_user_acl/retrieve/{proxy_user_acl_id}` | GET | Retrieve a specific ACL entry |
| `/public/user/proxy_user_acl/search` | GET | Search ACL entries with filters |
| `/public/user/proxy_user_acl/delete/{proxy_user_acl_id}` | DELETE | Delete an ACL entry |
## Example Response
```json theme={null}
{
"data": {
"proxy_user_acl_id": "550e8400-e29b-41d4-a716-446655440000",
"proxy_user_id": "stevejobs",
"service_id": "API-1234-5678",
"proxy_user_acl_creation_datetime": "2023-09-28 12:34:56"
},
"message": "Proxy User Acl successfully retrieved."
}
```
## Usage Notes
* ACL entries can only be created for proxy users with `access_type` set to `"service_restricted"` or `"proxy_restricted"`
* The service or proxy specified in the ACL must belong to the same customer account as the proxy user
* When changing a proxy user's `access_type` to `"all"`, you must clear all existing ACL entries using the `clear_proxy_user_acl` parameter
* Deleting a proxy user automatically deletes all associated ACL entries
* You can have multiple ACL entries for the same proxy user to grant access to multiple services or proxies
# Residential Ledger
Source: https://documentation.byteful.com/api-objects/residential-ledger
Understanding the Residential Ledger object and its role in the Byteful API
The Residential Ledger object represents a record of residential data usage or allocation in the Byteful system. It serves as a complete audit trail that tracks all changes to the residential data pool associated with a customer account, including daily usage consumption, top-ups, service purchases, and administrative adjustments.
## Key Attributes
| Attribute | Type | Description |
| ----------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `residential_ledger_id` | string | Unique identifier for the ledger entry |
| `residential_ledger_bytes` | integer | Amount of data in bytes associated with this ledger entry |
| `residential_ledger_requests` | integer | Number of requests associated with this ledger entry |
| `residential_ledger_period_date` | string | The date this ledger entry is associated with |
| `residential_ledger_reason` | string | Reason for the ledger entry (e.g., "usage", "top\_up", "service\_purchase") |
| `service_id` | string | ID of the related service if applicable |
| `service_adjustment_id` | integer | ID of the related service adjustment if applicable |
| `residential_ledger_creation_datetime` | datetime | When the ledger entry was created |
| `residential_ledger_last_update_datetime` | datetime | When the ledger entry was last updated |
## Object Relationships
The Residential Ledger object is connected to several other objects in the Byteful API:
* **Customer**: Each residential ledger entry belongs to a customer account
* **Service**: Entries may be associated with a residential service (e.g., when purchasing additional data)
* **Service Adjustment**: Entries may be linked to service adjustments (e.g., refunds or manual adjustments)
* **Proxy User**: While not directly linked, proxy users consume data which creates ledger entries
```mermaid theme={null}
graph TD
Customer --> ResidentialLedger["Residential Ledger"]
Service --> ResidentialLedger
ServiceAdjustment --> ResidentialLedger
ProxyUser -.-> ResidentialLedger["Creates entries through usage"]
```
## Related Endpoints
| Endpoint | Description |
| ---------------------------------------------------------------------- | ---------------------------------------------- |
| `GET /public/user/residential_ledger/retrieve/{residential_ledger_id}` | Retrieve a specific residential ledger entry |
| `GET /public/user/residential_ledger/search` | Search residential ledger entries with filters |
| `GET /public/user/residential/summary` | Get a summary of residential data status |
## Example Response
```json theme={null}
{
"data": {
"customer_id": 1955,
"residential_ledger_bytes": 128290101,
"residential_ledger_creation_datetime": "2023-04-01 12:00:00",
"residential_ledger_id": "123e4567-e89b-12d3-a456-426614174000",
"residential_ledger_last_update_datetime": "2023-04-02 12:00:00",
"residential_ledger_period_date": "2023-10-01",
"residential_ledger_reason": "top_up",
"residential_ledger_requests": 1244,
"service_adjustment_id": 10,
"service_id": "API-1234-5678"
},
"message": "Residential Ledger successfully retrieved."
}
```
## Ledger Entry Types
Residential ledger entries have various reason types that indicate different data changes:
| Reason | Description |
| ------------ | ---------------------------------------------------------------- |
| `usage` | Daily decrements to the data pool from proxy usage |
| `top_up` | Increments from purchasing additional data |
| `adjustment` | Manual adjustments (positive or negative) made by administrators |
## Usage Notes
* The residential ledger is maintained at the account data pool level, not per proxy
* Usage entries are aggregated daily, providing a day-by-day audit trail of data consumption
* Entries with positive `residential_ledger_bytes` values add to your data pool (top-ups, purchases)
* Entries with negative `residential_ledger_bytes` values subtract from your data pool (usage)
* The `residential_ledger_period_date` field indicates the specific day when usage occurred or changes were made
* Unlike datacenter and ISP proxies, residential proxies operate on a data-based billing model
* There is no automatic expiration for residential data - it remains in your account until consumed
* For real-time data status, use the `/residential/summary` endpoint
# Service
Source: https://documentation.byteful.com/api-objects/service
Understanding the Service object and its role in the Byteful API
The Service object represents a subscription to a proxy product in the Byteful system. It contains essential information about a purchased proxy service including its type, status, billing details, and associated resources.
## Key Attributes
| Attribute | Type | Description |
| --------------------------------- | -------- | ------------------------------------------------------------ |
| `service_id` | string | Unique identifier for the service |
| `service_name` | string | Name of the purchased service |
| `service_type` | string | Type of service (datacenter, isp, residential, off\_catalog) |
| `service_protocol` | string | IP protocol of the service (ipv4, ipv6, dual) |
| `service_quantity` | integer | Number of proxies in the service |
| `service_status` | string | Current status of the service |
| `service_cycle` | string | Billing cycle of the service (e.g., "1:month") |
| `service_expiry_datetime` | datetime | When the current billing period ends |
| `service_total` | integer | Cost of the service in cents |
| `service_is_automatic_collection` | boolean | Whether billing occurs automatically |
| `service_is_pending_cancellation` | boolean | Whether the service is scheduled to be canceled |
| `service_metadata` | object | Custom metadata for tracking and organization |
| `country_id` | string | Country code where the service is based |
| `service_fulfillment_filter` | object | Criteria used when provisioning the service |
## Service Status Values
| Status | Description |
| --------------------------------- | ----------------------------------------------------------- |
| `awaiting_fulfillment` | Service has been paid for but proxies not yet provisioned |
| `awaiting_manual_fulfillment` | Service needs manual intervention by staff |
| `awaiting_additional_fulfillment` | Service needs more proxies to be provisioned |
| `active` | Service is active and available for use |
| `paused` | Service is temporarily paused |
| `overdue` | Payment is overdue for the service |
| `canceled` | Service has been terminated |
| `complete` | Service has completed its term (for non-recurring services) |
## Object Relationships
The Service object is connected to several other objects in the Byteful API:
* **Customer**: Each service belongs to a customer account
* **Proxies**: Services contain individual proxy objects
* **Service Adjustments**: Track changes or modifications to the service
* **Invoices**: Financial records associated with the service
* **Product**: The product template the service was created from
* **Proxy Users**: Authentication entities that can access the service
```mermaid theme={null}
graph TD
Customer --> Service
Service --> Proxies
Service --> ServiceAdjustments
Service --> Invoices
Service --> ResidentialLedger[Residential Ledger]
Service --> MobileLedger[Mobile Ledger]
Product --> Service
```
## Related Endpoints
| Endpoint | Description |
| ------------------------------------------------- | ---------------------------- |
| `GET /public/user/service/retrieve/{service_id}` | Retrieve a specific service |
| `GET /public/user/service/search` | Search services with filters |
| `PATCH /public/user/service/edit/{service_id}` | Edit a service |
| `DELETE /public/user/service/cancel/{service_id}` | Cancel a service |
## Example Response
```json theme={null}
{
"data": {
"service_id": "API-1234-5678",
"service_name": "AT&T ISP Proxies [US]",
"service_type": "isp",
"service_protocol": "ipv4",
"service_quantity": 5,
"service_status": "active",
"service_cycle": "1:month",
"service_creation_datetime": "2025-03-25 14:25:36",
"service_expiry_datetime": "2025-04-25 14:25:36",
"service_total": 1575,
"service_is_automatic_collection": true,
"service_is_pending_cancellation": false,
"service_metadata": {
"project": "Client XYZ",
"department": "Marketing"
},
"country_id": "us",
"service_fulfillment_filter": {
"asn_id": 7018
}
},
"message": "Service successfully retrieved."
}
```
## Usage Notes
* A service can contain multiple proxies, up to the `service_quantity` value
* The `service_fulfillment_filter` allows you to target specific ASNs or regions
* Services automatically renew based on the `service_cycle` unless `service_is_pending_cancellation` is true
* The `service_metadata` field can be used to organize services by project, client, or department
* When a service is canceled, all associated proxies are deprovisioned
* To view proxies associated with a service, use the `proxies=true` parameter when retrieving the service
## Residential and Mobile Services
Residential and Mobile services have several unique characteristics:
* They do not have static proxies attached to them, unlike datacenter and ISP services
* Instead, they add data to your account's residential or mobile data pool
* Data added through residential/mobile services never expires, even if the subscription is canceled
* Each purchase creates a `residential_ledger` or `mobile_ledger` entry recording the data addition
* Residential and Mobile services can be paused and unpaused, a feature not available for other service types
* When paused, billing stops but you retain access to any previously purchased data
* You can access this data through dynamic residential proxies and mobile proxies using the corresponding endpoints
# Service Adjustment
Source: https://documentation.byteful.com/api-objects/service-adjustment
Understanding the Service Adjustment object and its role in the Byteful API
The Service Adjustment object represents a record of changes made to services in the Byteful system. It provides a detailed audit trail of any modifications to a service, including who made the change, when it was made, and what was modified.
## Key Attributes
| Attribute | Type | Description |
| ----------------------------------------- | -------- | -------------------------------------------------------------------------- |
| `service_adjustment_id` | integer | Unique identifier for the service adjustment |
| `service_id` | string | ID of the service that was modified |
| `service_adjustment_type` | string | Type of adjustment (e.g., `extension`, `fulfillment`, `proxy_replacement`) |
| `service_adjustment_status` | string | Status of the adjustment (`pending`, `complete`, `failed`) |
| `service_adjustment_pre` | object | JSON representation of the service state before the adjustment |
| `service_adjustment_post` | object | JSON representation of the service state after the adjustment |
| `service_adjustment_eval` | object | Evaluation of changes between pre and post states |
| `service_adjustment_is_administrator` | boolean | Whether the adjustment was made by a Byteful administrator |
| `service_adjustment_is_automatic` | boolean | Whether the adjustment was made automatically by the system |
| `service_adjustment_is_customer` | boolean | Whether the adjustment was made by the customer |
| `service_adjustment_creation_datetime` | datetime | When the adjustment was created |
| `service_adjustment_last_update_datetime` | datetime | When the adjustment was last updated |
| `invoice_id` | string | ID of any invoice associated with the adjustment |
## Service Adjustment Types
Service adjustments can be of various types, each representing a different kind of change:
| Type | Description |
| ------------------------ | --------------------------------------------------------- |
| `ingestion` | Initial creation and ingestion of a service |
| `fulfillment` | Allocation of proxies to a service |
| `remove_proxy` | Removal of proxies from a service |
| `additional_fulfillment` | Adding more proxies to an existing service |
| `update` | General update to service attributes |
| `proxy_replacement` | Replacing proxies with new ones |
| `extension` | Extending the service period |
| `top_up` | Adding additional data to a residential or mobile service |
| `top_up_and_extension` | Both extending service and adding data |
| `cancel` | Cancellation of a service |
## Object Relationships
The Service Adjustment object is connected to several other objects in the Byteful API:
* **Service**: Each adjustment is associated with a specific service
* **Invoice**: Adjustments that involve billing will reference an invoice
* **Proxy Replacements**: When proxies are replaced, the adjustment may contain details of the replacement
* **Customer**: Adjustments track which customer made the change, if applicable
```mermaid theme={null}
graph TD
Service --> ServiceAdjustment
ServiceAdjustment --> Invoice
ServiceAdjustment --> ProxyReplacement
Customer -.-> ServiceAdjustment
```
## Related Endpoints
| Endpoint | Description |
| ---------------------------------------------------------------------- | --------------------------------------- |
| `GET /public/user/service_adjustment/retrieve/{service_adjustment_id}` | Retrieve a specific service adjustment |
| `GET /public/user/service_adjustment/search` | Search service adjustments with filters |
## Example Response Structure
```json theme={null}
{
"data": {
"service_adjustment_id": 213,
"service_id": "API-1234-5678",
"service_adjustment_type": "extension",
"service_adjustment_status": "complete",
"service_adjustment_pre": {
"service_expiry_datetime": "2023-09-14 18:30:00"
},
"service_adjustment_post": {
"service_expiry_datetime": "2024-09-14 18:30:00"
},
"service_adjustment_eval": {
"service_expiry_datetime": [
"2023-09-14 18:30:00",
"2024-09-14 18:30:00"
]
},
"service_adjustment_is_administrator": false,
"service_adjustment_is_automatic": true,
"service_adjustment_is_customer": true,
"service_adjustment_creation_datetime": "2023-09-14 18:30:00",
"service_adjustment_last_update_datetime": "2023-09-15 18:30:00",
"invoice_id": "in_1NpRIvB2BUlqim5lN4v3URka"
},
"message": "Service Adjustment successfully retrieved."
}
```
## Usage Notes
* Service adjustments provide a comprehensive audit trail of all changes to services
* The `service_adjustment_pre` and `service_adjustment_post` fields store JSON snapshots of the service state before and after the change
* The `service_adjustment_eval` field provides a side-by-side comparison of changed values
* When an adjustment involves proxy replacements, the `proxy_replacements` array will be included with details of each replaced proxy
* Service adjustments are read-only records and cannot be modified once created
* The `service_adjustment_is_administrator`, `service_adjustment_is_automatic`, and `service_adjustment_is_customer` flags help identify the origin of the change
* For complex adjustments like `proxy_replacement`, the adjustment may contain additional nested objects with details specific to that adjustment type
# Subdivision
Source: https://documentation.byteful.com/api-objects/subdivision
Understanding the Subdivision object and its role in the Byteful API
The Subdivision object represents a geographical administrative division within a country in the Byteful system. These are typically states, provinces, regions, or other similar administrative areas. Subdivisions provide a more granular level of geographic targeting than countries alone, allowing you to select proxies from specific regions within countries.
## Key Attributes
| Attribute | Type | Description |
| ------------------- | ------ | -------------------------------------------------------------------- |
| `subdivision_id` | string | Unique identifier for the subdivision (e.g., `us-tx` for Texas, USA) |
| `subdivision_name` | string | Full name of the subdivision (e.g., `Texas`) |
| `subdivision_alias` | string | Alternative identifier or shorthand (e.g., `us_tx`) |
| `country_id` | string | ISO country code of the parent country (e.g., `us`) |
## Object Relationships
The Subdivision object connects several other entities in the Byteful system:
* **Country**: Each subdivision belongs to a specific country
* **City**: Subdivisions contain multiple cities
* **Proxies**: Proxies can be located within specific subdivisions
* **Service Fulfillment Filters**: Proxy services can be filtered to target specific subdivisions
```mermaid theme={null}
graph TD
Country --> Subdivision
Subdivision --> City
Proxy -.-> Subdivision
ServiceFulfillmentFilter -.-> Subdivision
```
## Related Endpoints
| Endpoint | Description |
| --------------------------------------------------------------- | ----------------------------------------- |
| `GET /public/user/subdivision/retrieve/{subdivision_id}` | Retrieve a specific subdivision |
| `GET /public/user/subdivision/search` | Search subdivisions with filters |
| `GET /public/user/city/search?subdivision_id={subdivision_id}` | Find cities within a specific subdivision |
| `GET /public/user/proxy/search?subdivision_id={subdivision_id}` | Find proxies in a specific subdivision |
## Example Subdivision Object
```json theme={null}
{
"subdivision_id": "fr-idf",
"subdivision_name": "Île-de-France",
"subdivision_alias": "fr_idf",
"country_id": "fr"
}
```
## Usage Notes
* When targeting proxies with high geographic precision, subdivisions provide an intermediate level between countries and cities
* The `subdivision_id` follows the ISO 3166-2 format: a country code, followed by a hyphen and the subdivision code
* For service fulfillment filters, using subdivision targeting often provides better proxy availability than city-level targeting while still maintaining geographic specificity
* Not all proxies have subdivision data, particularly in smaller countries
* For residential/mobile proxy generation, subdivision targeting is implemented through the `subdivision_id` parameter in the residential list or mobile list endpoint
## Subdivision ID Formats
Byteful follows the ISO 3166-2 standard for subdivision identification:
* US states: `us-tx`, `us-ca`, `us-ny`, etc.
* Canadian provinces: `ca-on`, `ca-qc`, `ca-bc`, etc.
* UK regions: `gb-eng`, `gb-sct`, `gb-wls`, etc.
* French regions: `fr-idf`, `fr-ara`, `fr-pac`, etc.
This standardized approach ensures consistent identification of subdivisions across the platform.
# Retrieve ASN
Source: https://documentation.byteful.com/api-reference/asn/retrieve-asn
get /public/user/asn/retrieve/{asn_id}
Retrieves a specific ASN.
# Search ASN
Source: https://documentation.byteful.com/api-reference/asn/search-asn
get /public/user/asn/search
Search Autonomous System Number (ASN) entries using various filters.
# Create Checkout
Source: https://documentation.byteful.com/api-reference/checkout/create-checkout
post /public/user/checkout/create
This endpoint creates a checkout for the authenticated user based on the provided data. It supports
promotional codes and can handle both one-time and recurring payments. The product can be configured
in one of two mutually exclusive forms:
- Legacy flat form: a `product_code` directly, or the traditional combination of `product_type`,
`country_id`, and `product_protocol`, with a top-level `quantity`.
- Multi-location form: a single `line_items` entry carrying its own product type, billing cycle,
quantity, and per-location `service_fulfillment_filter`.
**Important considerations**
- If `product_code` is provided alongside `product_type`/`country_id`/`product_protocol`, their values must match the actual product attributes.
- API checkouts are settled with your existing credit balance; a cart your credit cannot fully cover is rejected with 422. The returned invoice is already paid and `invoice_url` points at its hosted page.
**Example: multi-location checkout (line_items form)**
```json
{
"line_items": [
{
"product_type": "isp",
"item_quantity": 5,
"cycle_interval": "month",
"cycle_interval_count": 1,
"service_fulfillment_filter": [
{"country_id": "us", "quantity": 2},
{"country_id": "gb", "quantity": 2}
]
}
],
"promotional_code": "PROMOCODEHERE"
}
```
# Generate Checkout Quote
Source: https://documentation.byteful.com/api-reference/checkout/generate-checkout-quote
post /public/user/checkout/quote
This endpoint allows a user to generate a quote for a service via the API. The product can be
configured in one of two mutually exclusive forms:
- Legacy flat form: a `product_code` directly, or the traditional combination of `product_type`,
`country_id`, and `product_protocol`, with a top-level `quantity`.
- Multi-location form: a single `line_items` entry carrying its own product type, billing cycle,
quantity, and per-location `service_fulfillment_filter`.
**Example: multi-location quote (line_items form)**
```json
{
"line_items": [
{
"product_type": "isp",
"item_quantity": 5,
"cycle_interval": "month",
"cycle_interval_count": 1,
"service_fulfillment_filter": [
{"country_id": "us", "quantity": 2},
{"country_id": "gb", "quantity": 2}
]
}
],
"promotional_code": "PROMOCODEHERE"
}
```
# Retrieve Simplified Product Checkout Catalog
Source: https://documentation.byteful.com/api-reference/checkout/retrieve-simplified-product-checkout-catalog
get /public/user/checkout/catalog
This endpoint returns a simplified product list that is both visible
and enabled for API checkouts. It helps clients to quickly identify and
purchase available products without any search or pagination parameters.
Ideal for basic API-based purchasing.
# Retrieve City
Source: https://documentation.byteful.com/api-reference/city/retrieve-city
get /public/user/city/retrieve/{city_id}
Retrieves a specific City.
# Search City
Source: https://documentation.byteful.com/api-reference/city/search-city
get /public/user/city/search
Search City entries using various filters.
# Retrieve Continent
Source: https://documentation.byteful.com/api-reference/continent/retrieve-continent
get /public/user/continent/retrieve/{continent_id}
Retrieves a specific Continent.
# Search Continent
Source: https://documentation.byteful.com/api-reference/continent/search-continent
get /public/user/continent/search
Search Continent entries using various filters.
# Retrieve Country
Source: https://documentation.byteful.com/api-reference/country/retrieve-country
get /public/user/country/retrieve/{country_id}
Retrieves a specific Country.
# Search Country
Source: https://documentation.byteful.com/api-reference/country/search-country
get /public/user/country/search
Search Country entries using various filters.
# Retrieve Current Customer
Source: https://documentation.byteful.com/api-reference/customer/retrieve-current-customer
get /public/user/customer/retrieve
Retrieves the profile of the currently authenticated customer, along with their credit balance.
# Get Mobile Availability Count
Source: https://documentation.byteful.com/api-reference/mobile-availability/count-mobile-availability
get /public/user/mobile_availability/count
Get the total count of mobile availability nodes with optional filtering capabilities.
Filters are applied when parameters are present and not null.
# Search Mobile Availability
Source: https://documentation.byteful.com/api-reference/mobile-availability/search-mobile-availability
get /public/user/mobile_availability/search
Search mobile availability records with optional grouping capabilities.
Use `group_by` parameter to aggregate results by specified field(s).
# Retrieve Mobile Ledger
Source: https://documentation.byteful.com/api-reference/mobile-ledger/retrieve-mobile-ledger
get /public/user/mobile_ledger/retrieve/{mobile_ledger_id}
Retrieves a specific Mobile Ledger based on the provided ID for the current user's account.
# Search Mobile Ledger
Source: https://documentation.byteful.com/api-reference/mobile-ledger/search-mobile-ledger
get /public/user/mobile_ledger/search
Search for entries in the Mobile Ledger using various filters.
# Generated Mobile List
Source: https://documentation.byteful.com/api-reference/mobile/create-mobile-list
get /public/user/mobile/list
This endpoint creates a list of mobile proxies based on filter parameters.
The search parameters allow the user to filter the proxies by location, session type, and format (e.g., http, socks5, socks5h).
# Retrieve Mobile Service Summary
Source: https://documentation.byteful.com/api-reference/mobile/retrieve-mobile-service-summary
get /public/user/mobile/summary
This endpoint provides a detailed summary of a mobile service.
It returns information such as service details, usage statistics, and associated proxy users.
# Search Product
Source: https://documentation.byteful.com/api-reference/product/search-product
get /public/user/product/search
Search Products entries using various filters.
# Analytics Breakdown
Source: https://documentation.byteful.com/api-reference/proxy-analytics/breakdown-proxy-analytics
get /public/user/analytics/breakdown
This endpoint analyzes proxy usage for a given customer within a specified time range
and provides breakdowns by proxy users, hostnames, and network types.
You can either:
1. Provide a "preset" parameter, which automatically sets the time period
(e.g. "last_day", "last_hour", etc.).
2. OR, manually specify your own time range using period_start and period_end.
You can also filter by hostname, network, and proxy_user_id.
Hostname filters are disallowed if searching older than 90 days.
# Graph Proxy Analytics
Source: https://documentation.byteful.com/api-reference/proxy-analytics/graph-proxy-analytics
get /public/user/analytics/graph
This endpoint analyzes proxy usage for a given customer within a specified time range
and groups them by one of four discrete intervals: `minute`, `hour`, `day`, or `month`.
You can either
1. Provide a `preset` parameter, which automatically sets period and interval
(e.g. `last_day`, `last_hour`, etc.)
2. OR, manually specify your own time range (`period_start`, `period_end`) plus `interval`
You can also filter by `hostname`, `network`, `proxy_user_id`, and `service_id`.
Service ID can only be filtered if period is within 7 days and interval is hour or less.
Hostname filters are disallowed if searching older than 90 days.
# Create Proxy Test Run
Source: https://documentation.byteful.com/api-reference/proxy-tester/create-proxy-test
POST /public/user/proxy_test_run/create
Test all provided proxies against urls
# Search Proxy Test Servers
Source: https://documentation.byteful.com/api-reference/proxy-tester/search-proxy-test-servers
GET /public/user/proxy_test_server/search
Search Proxy Test Servers using various filters.
# Create Proxy User ACL
Source: https://documentation.byteful.com/api-reference/proxy-user-acl/create-proxy-user-acl
post /public/user/proxy_user_acl/create
This endpoint allows you to create a new Proxy User ACL entry to grant access to specific services or proxies.
- The target Proxy User must not be deleted.
- The target Proxy User must not be a default proxy user (default proxy users have access to all proxies).
- For service access: proxy_user_access_type must be `service_restricted`.
- For proxy access: proxy_user_access_type must be `proxy_restricted`.
# Delete Proxy User ACL Record
Source: https://documentation.byteful.com/api-reference/proxy-user-acl/delete-proxy-user-acl
delete /public/user/proxy_user_acl/delete/{proxy_user_acl_id}
Allows a user to delete an existing Proxy User ACL associated with their account.
This permanently removes the ACL record from the database.
# Retrieve Proxy User ACL
Source: https://documentation.byteful.com/api-reference/proxy-user-acl/retrieve-proxy-user-acl
get /public/user/proxy_user_acl/retrieve/{proxy_user_acl_id}
Retrieves a specific Proxy User ACL based on the provided ID for the current user's account.
# Search Proxy User ACLs
Source: https://documentation.byteful.com/api-reference/proxy-user-acl/search-proxy-user-acls
get /public/user/proxy_user_acl/search
Search Proxy User ACL entries on the customer account using various filters.
Only returns ACL entries for proxy users that belong to the current customer.
# Create Proxy User
Source: https://documentation.byteful.com/api-reference/proxy-user/create-proxy-user
post /public/user/proxy_user/create
This endpoint allows you to create a new proxy user.
The `proxy_user_id` and `proxy_user_password` can be provided or, if omitted, will be randomly generated.
Additional considerations when creating a Proxy User:
- `proxy_user_access_type`: Controls access restrictions ("all", "service_restricted", "proxy_restricted")
- `proxy_user_is_strict_security`: If true, the Proxy User requires an IP address authentication list.
- `proxy_user_enforce_https`: If true, this Proxy User can only access targets on port 443 (HTTPS).
- `ip_address_authentications` must be a list of valid IP addresses. Each IP address can only be used by one Proxy User.
- `proxy_user_residential_bytes_limit`: An integer limiting residential traffic (must not be negative).
- `proxy_user_mobile_bytes_limit`: An integer limiting mobile traffic (must not be negative).
For access control, use the ProxyUserAcl endpoints to grant specific service or proxy access when using "service_restricted" or "proxy_restricted" access types.
# Delete Proxy User Record
Source: https://documentation.byteful.com/api-reference/proxy-user/delete-proxy-user-record
delete /public/user/proxy_user/delete/{proxy_user_id}
Allows a user to delete an existing proxy user associated with their account.
Proxy users that are set as account default can not be deleted,
and already deleted proxy users can not be deleted again.
# Edit Proxy User
Source: https://documentation.byteful.com/api-reference/proxy-user/edit-proxy-user
patch /public/user/proxy_user/edit/{proxy_user_id}
This endpoint allows a user to edit an existing Proxy User entry by providing the necessary `proxy_user_id`.
For access control, use the ProxyUserAcl endpoints to manage specific service or proxy access when using "service_restricted" or "proxy_restricted" access types.
# Retrieve Proxy User
Source: https://documentation.byteful.com/api-reference/proxy-user/retrieve-proxy-user
get /public/user/proxy_user/retrieve/{proxy_user_id}
Retrieves a specific Proxy User based on the provided ID for the current user's account.
# Search Proxy Users
Source: https://documentation.byteful.com/api-reference/proxy-user/search-proxy-users
get /public/user/proxy_user/search
Search Proxy Users on the customer account using various filters.
# Retrieve Proxy
Source: https://documentation.byteful.com/api-reference/proxy/retrieve-proxy
get /public/user/proxy/retrieve/{proxy_id}
Retrieves a specific Proxy based on the provided ID for the current user's account, ensuring
that only proxies associated with the customer services and in use are returned.
# Generate Proxy List By ID
Source: https://documentation.byteful.com/api-reference/proxy/retrieve-proxy-list-by-id
post /public/user/proxy/list_by_id
This endpoint retrieves a list of proxies assigned to the current user (or a specified
customer) based on the proxy IDs.
This endpoint is intentionally a POST even though it only retrieves data since it needs to larger lists of UUIDs.
# Generate Proxy List By Search
Source: https://documentation.byteful.com/api-reference/proxy/retrieve-proxy-list-by-search
get /public/user/proxy/list_by_search
This endpoint retrieves a list of available proxies for a user based on provided search parameters.
The search parameters allow the user to filter the proxies based on protocol, version, format, and associated service ID.
The function returns proxies in various formats suitable for different purposes.
# Get Proxy User List Options
Source: https://documentation.byteful.com/api-reference/proxy/retrieve-proxy-list-options
post /public/user/proxy/list/options
This endpoint returns a list of all active proxy users on the customer's account,
along with a boolean flag indicating whether each proxy user has access to export/use
the specified proxies based on their access type and ACL rules.
**Access Logic:**
- **Unrestricted (all)**: Proxy user has access to all proxies on the account
- **Service Restricted**: Proxy user has access only if they have ACL entries for all services
containing the specified proxies
- **Proxy Restricted**: Proxy user has access only if they have ACL entries for all
specified proxies
**Note:** This endpoint is intentionally a POST request (rather than GET) to support
large lists of proxy IDs in the request body.
# Search Proxies
Source: https://documentation.byteful.com/api-reference/proxy/search-proxies
get /public/user/proxy/search
Search Proxies on the customer account using various filters.
# Get Residential Availability Count
Source: https://documentation.byteful.com/api-reference/residential-availability/count-residential-availability
get /public/user/residential_availability/count
Get the total count of residential availability nodes with optional filtering capabilities.
Filters are applied when parameters are present and not null.
# Search Residential Availability
Source: https://documentation.byteful.com/api-reference/residential-availability/search-residential-availability
get /public/user/residential_availability/search
Search residential avairecords with optional grouping capabilities.
Use `group_by` parameter to aggregate results by specified field(s).
# Retrieve Residential Ledger
Source: https://documentation.byteful.com/api-reference/residential-ledger/retrieve-residential-ledger
get /public/user/residential_ledger/retrieve/{residential_ledger_id}
Retrieves a specific Residential Ledger based on the provided ID for the current user's account.
# Search Residential Ledger
Source: https://documentation.byteful.com/api-reference/residential-ledger/search-residential-ledger
get /public/user/residential_ledger/search
Search for entries in the Residential Ledger using various filters.
# Generated Residential List
Source: https://documentation.byteful.com/api-reference/residential/create-residential-list
get /public/user/residential/list
This endpoint creates a list of residential proxies based on filter parameters.
The search parameters allow the user to filter the proxies by location, session type, and format (e.g., http, socks5, socks5h).
# Retrieve Residential Service Summary
Source: https://documentation.byteful.com/api-reference/residential/retrieve-residential-service-summary
get /public/user/residential/summary
This endpoint provides a detailed summary of a residential service.
It returns information such as service details, usage statistics, and associated proxy users.
# Retrieve Service Adjustment
Source: https://documentation.byteful.com/api-reference/service-adjustment/retrieve-service-adjustment
get /public/user/service_adjustment/retrieve/{service_adjustment_id}
Retrieves a specific Service Adjustment based on the provided ID for the current user's account.
The returned adjustment provides details about any modifications or updates made to the user's service.
# Search Service Adjustments
Source: https://documentation.byteful.com/api-reference/service-adjustment/search-service-adjustments
get /public/user/service_adjustment/search
Search Service Adjustments on the customer account using various filters.
# Cancel Service
Source: https://documentation.byteful.com/api-reference/service/cancel-service
delete /public/user/service/cancel/{service_id}
Allows the authenticated user to cancel a specific service associated with their account.
The user provides a service_id and optionally a cancel feedback and comment.
# Edit Service
Source: https://documentation.byteful.com/api-reference/service/edit-service
patch /public/user/service/edit/{service_id}
Allows a user to edit the details of an existing service.
This can include changes in payment method, adjusting automatic collection,
and marking for cancellation at the end of a period.
# Retrieve Service
Source: https://documentation.byteful.com/api-reference/service/retrieve-service
get /public/user/service/retrieve/{service_id}
Retrieves a specific Service based on the provided ID for the current user's account. The
service's live per-location line items are always included. If the 'proxies' parameter is
set to 'True', the proxies associated with the service are also added to the result.
# Search Services
Source: https://documentation.byteful.com/api-reference/service/search-services
get /public/user/service/search
Search Services on the customer account using various filters.
# Retrieve Subdivision
Source: https://documentation.byteful.com/api-reference/subdivision/retrieve-subdivision
get /public/user/subdivision/retrieve/{subdivision_id}
Retrieves a specific Subdivision.
# Search Subdivision
Source: https://documentation.byteful.com/api-reference/subdivision/search-subdivision
get /public/user/subdivision/search
Search Subdivision entries using various filters.
This endpoint allows users to query subdivisions based on specific attributes.
# Retrieve Zip Code
Source: https://documentation.byteful.com/api-reference/zip-code/retrieve-zip-code
get /public/user/zip_code/retrieve/{zip_code_id}
Retrieves a specific Zip Codeq.
# Search Zip Code
Source: https://documentation.byteful.com/api-reference/zip-code/search-zip-code
get /public/user/zip_code/search
Search Zip Code entries using various filters.
# Scenarios
Source: https://documentation.byteful.com/examples-index
Collection of practical examples for the Byteful API
## Practical Examples
Explore these practical examples to learn how to effectively use the Byteful API for common tasks and workflows.
Learn how to retrieve and paginate through all your proxies and add them to a list.
Export your datacenter and ISP proxies to a list using the list\_by\_search endpoint.
Learn how to retrieve all proxies associated with a specific service ID.
Export a formatted list of proxies from a specific service.
Generate a list of sticky residential proxies in the US for a specific proxy user.
Generate a list of sticky mobile proxies in the US for a specific proxy user.
Create a proxy user with metadata and data limits.
Create a proxy user with restricted access to specific services using ACLs.
Create a proxy user with access to specific individual proxies using ACLs.
Search, add, and remove Proxy User ACL entries to control access.
Learn how to retrieve all proxies a proxy user can access based on their ACL settings.
Search for proxy users using metadata criteria.
Search for proxy users using metadata criteria.
Learn how to automate proxy purchasing through our API.
Learn how to access and analyze usage statistics for a specific proxy user.
Update authentication credentials and settings for an existing proxy user.
Test a list of proxies from a file and output the results to a csv.
## Implement Your Own Integrations
These examples are written in multiple programming languages to help you implement your own integrations with the Byteful API. Each example includes:
* Detailed explanation of the API functionality
* Code samples in Python, JavaScript, PHP, Go, and Java
* Sample API responses
* Best practices and tips
## Need Custom Examples?
If you need help with specific use cases not covered in these examples, please contact our support team or join our Discord community for assistance.
Reach out to our support team for technical assistance.
# Abuse Reporting Policy
Source: https://documentation.byteful.com/general/abuse-reporting-policy
Official Abuse Reporting Policy and Instructions for Byteful services
If you believe abusive activity is originating from our services, please report it immediately to our dedicated abuse desk at [abuse@byteful.com](mailto:abuse@byteful.com)
Our abuse desk operates 24/7 with continuous email monitoring. We aim to respond to all abuse reports within 24 hours and investigate/remediate cases within 48 hours. We prioritize cases involving active attacks, CSAM, and law enforcement requests.
## What to Include in Your Report
| Information | Status | Description |
| --------------------------------------------------------- | ------------ | ----------------------------------------------- |
| Date, time, and timezone of the incident | **REQUIRED** | Specify when the abusive activity occurred |
| Source IP address(es) involved in the abusive activity | **REQUIRED** | The IP addresses that originated the abuse |
| Type of abuse (see categories below) | **REQUIRED** | Category of abuse from our list below |
| Your contact information for follow-up | **REQUIRED** | Email or phone for case updates |
| Full email headers (for spam/phishing) | OPTIONAL | Complete headers for email-based abuse |
| Server or firewall logs showing the abusive activity | OPTIONAL | Log files demonstrating the abuse |
| Relevant URLs or domains involved | OPTIONAL | Any websites or domains related to the incident |
| Screenshots, packet captures, or other technical evidence | OPTIONAL | Visual or technical proof of the abuse |
The more detailed information you provide, the faster we can investigate and take action.
## Abuse Categories We Handle
We investigate and respond to all types of network abuse including:
* Spam
* Phishing/Fraud
* Hacking
* Brute Force/Login Attacks
* DDoS Attacks
* Malware
* Port Scanning
* Web Scraping of non-publicly available information
* Copyright Infringement/DMCA Violations
* Hosting Violence/CSAM/Illegal Content
Other abuse report types may be accepted at our discretion.
## Our Investigation Process
When we receive an abuse report, we log it with a ticket number and acknowledge it within 24 hours. We then identify which service or infrastructure is involved and investigate to verify the activity. If confirmed, we take corrective action directly or require our downstream customers to address it with their end-users. We keep the reporting party updated throughout and confirm when the issue is resolved.
Enforcement depends on severity. Minor issues get warnings. Serious abuse leads to suspension, null-routing, or service termination. Repeat offenders face permanent bans and IP revocation. For illegal content like CSAM, terrorism material, or violent extremism, we restrict services, permanently ban the customer and their fingerprint to prevent re-registration, and reserve the right to contact local law enforcement.
## Law Enforcement & Regulatory Cooperation
We cooperate fully with properly authorized law enforcement requests from agencies in any jurisdiction, wherever they are based. All requests must meet appropriate legal standards with proper authorization, such as a court order, warrant, or other valid legal process recognised in the requesting jurisdiction. Where a request originates outside the United Kingdom, we may process it through the relevant mutual legal assistance or international cooperation channels, and we will always act in accordance with applicable law.
# Acceptable Usage Policy
Source: https://documentation.byteful.com/general/acceptable-usage-policy
Official Acceptable Usage Policy (AUP) for Byteful services
Our Acceptable Usage Policy (AUP) strictly prohibits the use of our services for activities mentioned in our restricted activity list.
## Prohibited Activities
The following activities are prohibited when using Byteful services:
* **Google Search Scraping:** Automated, large-scale scraping of google.com or other Google Search domains using Datacenter or Static Residential ISP Proxy services without prior approval. To request approval, please contact [support@byteful.com](mailto:support@byteful.com).
* **Any illegal activity**
* **Service interference**: Interfering with or denying service to any user other than the Customer's host (e.g., denial of service attack)
* **Prohibited content**: Posting, transmission, re-transmission, accessing or storing ("Access") material on or through the Services, if in the sole judgment of Ping Technology Labs LTD such Access is:
* In violation of any local, state, federal, or non-United States law or regulation (including rights protected by copyright, trade secret, patent or other intellectual property or similar laws or regulations)
* Threatening or abusive
* Obscene
* Indecent
* Defamatory
* **Security violations**: Causing or attempting to cause security breaches or disruptions of Internet communications
* **Fraudulent activities**: Using the Services to engage or support fraud, including ad-fraud
* **Unauthorized data collection**: Using the Services to collect or access non-public data. Unless the Customer has permission from the site, only publicly available data may be scraped
* **Sensitive data collection**: Using the Services to collect or access sensitive data such as health data
You must further comply with our full Terms and Conditions, including but not limited to, Terms and Conditions Article 4.2 Prohibition on Reverse Engineering, Scanning, and Proxy Indexing Activities.
## Customer Responsibility
Each Customer shall be responsible for determining what laws or regulations are applicable to their use of the products and services.
***
If you believe abusive activity is originating from our services, please report it immediately to our dedicated abuse desk.
# Account Registration
Source: https://documentation.byteful.com/general/account-registration
How to create and verify your Byteful account
Before you can purchase proxies or use the Byteful API, you'll need to create and verify an account.
## Registration Options
Byteful offers two convenient ways to register for an account:
![Byteful Registration]()
### Standard Email Registration
1. Visit our [sign-up page](https://dashboard.byteful.com/sign-up)
2. Enter your email address and create a password
3. Check your inbox for a verification email from `security.noreply@byteful.com`
4. Enter the two-factor authentication code from the email to verify your account
Each account must have a unique email address. Be sure to check your spam folder if you don't see the verification email in your inbox.
### Google Sign-Up (OAuth)
For a faster registration process, you can use your Google account:
1. Click [Sign Up With Google](https://api.byteful.com/1.0/private/user/customer/oauth?automatic_redirect=true\&external_service=google\&authorization_type=signup\&redirect_url=https%3A%2F%2Fdashboard.byteful.com)
2. Follow the Google authentication prompts
3. Grant permission for Byteful to access your Google account information
When using Google sign-up, authentication is handled through OAuth, and we rely on Google to verify your identity. This method bypasses the need for email verification.
## Account Security
We take security seriously and implement several measures to protect your account:
* **Email Verification**: Confirms ownership of your email address
* **Two-Factor Authentication**: Available for additional account security
* **Secure OAuth Integration**: When using Google sign-up
After successfully registering your account, you'll have immediate access to the Byteful dashboard where you can:
* Browse available proxy products
* Make purchases
* Generate API keys
* Manage your proxy infrastructure
## Next Steps
Once your account is created, you're ready to [make your first purchase](/general/making-your-first-purchase) or explore the dashboard to learn more about our proxy offerings.
# Fair Usage Policy
Source: https://documentation.byteful.com/general/anti-abuse-policy
Understanding our flexible approach to data and connection management
Our Fair Usage Policy is designed to protect our network and ensure excellent performance for all customers. **These guidelines are rarely enforced** and exist primarily to help us identify and address extreme abuse cases that could impact service quality for other users.
## Our Philosophy
We believe in providing generous, flexible proxy services. These policies are safety nets that allow us to take action only when customers engage in obviously abusive behavior at levels similar to DDoS or DoS attacks that negatively affect our network and other customers' experience.
## Data Guidelines
Our static proxy services come with generous data allowances designed to accommodate most legitimate use cases:
* **Generous Standard Allowance**: Up to 100TB per 500 proxies per monthly billing cycle
* **Proportional Scaling**: Limits scale with your subscription size and billing frequency
* **Flexible Implementation**: We adjust these thresholds based on network capacity and overall health
The vast majority of our customers never approach these limits. They're primarily in place to identify extreme usage patterns that could indicate network abuse.
## Connection Management
We maintain reasonable connection limits to ensure network stability:
* **Comfortable Concurrent Limits**: Up to several hundred simultaneous connections per proxy
* **Intelligent Monitoring**: We may apply additional safeguards during:
* High network load periods
* Suspicious traffic patterns
* Activities that resemble automated attacks
* Unusual target access patterns
## When We Take Action
**These policies are almost never enforced** for typical usage. We only intervene in clear cases of abuse such as:
* Traffic volumes approaching DDoS/DoS attack levels
* Patterns that significantly degrade service for other customers
* Activities that threaten network infrastructure stability
* Clear violations of our Terms of Service
Our approach is always to contact customers first to understand their use case before taking any restrictive action.
## Need Higher Limits?
If your legitimate business needs exceed our standard guidelines, we're happy to work with you:
1. **Reach out early**: Contact [support@byteful.com](mailto:support@byteful.com)
2. **Explain your use case**: Help us understand your requirements
3. **Custom solutions**: We often accommodate higher limits for genuine business needs
## Our Promise
We're committed to providing robust, reliable proxy services without unnecessary restrictions. These policies exist to protect our network infrastructure and ensure consistent performance for all customers, not to limit legitimate business activities.
While we rarely enforce these limits, attempting to deliberately circumvent our network protections or engage in obviously abusive behavior may result in service restrictions.
**Bottom line**: Use our services for legitimate purposes, and you'll likely never encounter these limitations. We're here to support your success, not create barriers.
# Billing Address
Source: https://documentation.byteful.com/general/billing-address
Learn how to set up and manage your billing address for invoices in Byteful
Invoices are automatically generated by our billing systems for each subscription payment event and top-up. These invoices use the Billing Address in your Billing address section.
![Byteful Billing Address Button]()
In this section, you can set your full billing address including your country, address line, billing name and ZIP code.
Once you have made changes, click Save Changes and then all invoices will be generated with these new details.
Only new invoices will be generated with your new Billing Address. Invoices are legal documents and we are unable to edit the billing information of past invoices that have already been generated.
# Changing your payment cycle
Source: https://documentation.byteful.com/general/changing-payment-cycle
Learn how to modify your subscription payment cycle
Datacenter, Static Residential, Mobile Data and Residential Data services can be reconfigured and resized through your Byteful dashboard by going to your Summary Page and clicking the three dots next to the specific service.
![Service options menu]()
## Reconfiguration Options
Once clicked, a pop-up will appear and it will allow you to change your subscription payment cycle.
![Service reconfiguration options]()
## Reconfiguration Review
After making your reconfiguration options, you can click calculate to get a preview of the change. This will show you the new billing date of the subscription along with amount due immediately.
Changes in payment cycle will usually occur after at your next billing cycle.
## Can't reconfigure your service?
Some services may not be reconfigurable and when you attempt to reconfigure them you'll see an error. This is usually the case if you've received a bespoke service or have a discount code applied to the service which is no longer supported.
# Changing your email address
Source: https://documentation.byteful.com/general/changing-your-email-address
Learn how to update the email address associated with your Byteful account
You manage your account information in your Account Settings section of the dashboard.
To change your account password:
1. Enter a new email address and click **Save Changes**. It can not be linked to any other Byteful accounts.
2. A pop-up will appear and an email will be sent to you with a code confirming you have access to the new account email address.
3. Enter the code and click **Confirm**
Your account is now associated with the new email address.
# Changing your password
Source: https://documentation.byteful.com/general/changing-your-password
Learn how to change your account password in the dashboard
You manage your account information in your Account Settings section of the dashboard.
To change your account password:
1. Go to the security tab
2. Enter a new password, first in the New Password box and then in the Repeat new password box and click Save Changes.
3. A pop-up will appear and an email will be sent to you with a code confirming you have are the account owner and have permissions to change the password.
4. Enter the code and click Confirm
Your account is now associated with the new password and you can use when you login.
# Creating a Proxy User
Source: https://documentation.byteful.com/general/creating-a-proxy-user
Learn how to create and configure proxy users for better organization and access control
All accounts have a default Proxy User created and assigned to them at the point of registration. This Proxy User cannot be deleted and will stay on your account forever.
## Adding a New Proxy User
If you'd like to create a new Proxy User, follow these steps:
1. Navigate to the Proxy User management section in your dashboard
2. Click the **+Add User** button in the top right corner
![Byteful Create Proxy User]()
## Limitations & Rules
| Limit | Editable | Restriction |
| ---------------------------- | --------------- | ----------------------------- |
| Proxy User ID | No | 10-32 Alphanumeric characters |
| Proxy User Password | Yes | 10-32 Alphanumeric characters |
| Number of Proxy Users | Contact Support | Contact Support |
| Number of IP Authentications | No | 3 per Proxy User |
# Credit and Payment Transactions
Source: https://documentation.byteful.com/general/credit-and-payment-transactions
Learn how to view and understand payment and credit transactions in your Byteful dashboard.
You can view all payment transaction and credit transactions in your dashboard at the Billing Transaction section of your dashboard. Here you can see all payment events and credit events that have occurred on your account.
![Byteful Transaction List]()
## Payment Transactions
The default view of the dashboard will show your Payment Transactions such as payments from cards or cryptocurrency. If you'd like to see store credit payments and top ups, you can click the drop down and select Credit Transactions.
## Transaction Details
On both pages, you'll see invoice including:
* Transaction date and time (UTC)
* Transaction amount
* Payment Card
* Transaction Status
* Credit Transaction reason
* The invoice that is related to your Payment Transaction or Credit Transaction
If you don't recognise a transaction then feel free to reach out to [support@byteful.com](mailto:support@byteful.com) or open a ticket in your dashboard.
# Debugging Proxy Errors
Source: https://documentation.byteful.com/general/debugging-and-error-codes
Learn how to identify and resolve proxy request failures using the Live Log Viewer and `x-byteful-request-id` header.
Understanding and resolving failed proxy requests is crucial to maintaining reliable infrastructure. We provide a powerful [**Live Log Viewer**](https://dashboard.byteful.com/observability/live) combined with traceable request identifiers to help you debug issues efficiently and in real time.
## Identifying Failed Requests
Every authenticated request that passes through our network includes a special response header:
```http theme={null}
x-byteful-request-id: 90c1d76f-4551-4d15-9087-b37421d6b7c7
```
This `x-byteful-request-id` is a unique identifier tied to that request's **Log ID** in the [Live Network Activity Viewer](/general/live-network-activity#live-network-activity). You can use this ID to locate and inspect the exact request, its metadata, and its outcome.
## Debugging with cURL
You can inspect your proxy request headers and outcomes using the `curl` CLI. Below is an example of a successful proxy tunnel request, which returns an `x-byteful-request-id` header:
```bash theme={null}
curl --proxy 124.103.51.11:8000 --proxy-user example_user:example_pass --verbose https://ipinfo.io
```
Example output (truncated for readability):
```
> CONNECT ipinfo.io:443 HTTP/1.1
> Proxy-Authorization: Basic ZXhhbXBsZV91c2VyOmV4YW1wbGVfcGFzcw==
< HTTP/1.1 200 OK
< x-byteful-request-id: 90c1d76f-4551-4d15-9087-b37421d6b7c7
< x-byteful-status-code: 200
< x-byteful-warp-enabled: true
...
```
You can now go to the **Live Activity** section in your dashboard, locate the Log ID `90c1d76f-4551-4d15-9087-b37421d6b7c7`, and inspect:
* Network used
* Proxy IP address
* Target domain
* Duration and bytes
* Internal error code (if failed)
### Headers
All responses from Byteful will contain the following headers:
| Header | Type | Meaning |
| ------------------------ | -------- | ------------------------------------------------------------------------- |
| `x-byteful-request-id` | `UUIDv4` | The unique ID of the request for cross-referencing in the dashboard. |
| `x-byteful-status-code` | `u16` | The Byteful code (error or success) associated with this request. |
| `x-byteful-warp-enabled` | `bool` | Wether or not your request was sped up using our WARP pathing technology. |
## Common Codes and Troubleshooting
We do not expose HTTP status codes due to TLS encryption. Instead, errors are represented by 4 digit internal codes shown in the [**Live Network Activity Viewer**](https://dashboard.byteful.com/observability/live).
The last digit of this internal code code is used to aid debugging by our support team and is not necessary for the customer to understand. As such, we display the last digit as `x` in this table.
# Byteful Customer Error Reference
| Dashboard Code | HTTP Code | Message |
| -------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 | `200 ` | Success |
| 301 | `301 ` | Redirecting to different target |
| 100x to 200x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 201x to 203x | `407` | Invalid proxy credentials. Please check your username and password and try again. |
| 206x | `400` | Invalid username parameters provided. Please check your proxy username format and try again. |
| 207x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 208x | `407` | Invalid proxy credentials. Please check your username and password and try again. |
| 301 | `500` | Redirecting to different target. |
| 310x to 312x | `502` | Failed to reach target. Please try again or contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 314x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 315x | `400` | The target hostname provided is invalid. Please check the target URL and try again. |
| 316x to 317x | `403` | You are accessing a restricted target. Please contact [support@byteful.com](mailto:support@byteful.com) if you believe this is incorrect. |
| 410x | `500` | Connection terminated by Byteful. |
| 411x to 412x | `403` | Exceeded maximum allowed connection duration. Please try again or contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 420x | `429` | Exceeded maximum allowed rate of requests. Please reduce your request rate and try again. |
| 421x | `429` | Concurrency limit exceeded. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 422x | `429` | Bandwidth limit exceeded. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 423x | `403` | Target website is blacklisted. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 450x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 451x | `503` | No node found for given parameters. Please check your proxy username format and try again. |
| 452x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 500x | `500` | Server failed to process request. Please try again or contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 501x to 502x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 800x to 810x | `500` | Network communication error. Please try again or contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 820x | `502` | Failed to reach target. Please try again or contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 821x | `503` | No node found for given parameters. Please check your proxy username format and try again. |
| 822x | `502` | The target refused the connection. Please verify the target host and port are correct and accepting connections. |
| 823x | `502` | The target's network is unreachable. Please check the target address and try again. |
| 824x | `502` | The target host is unreachable. Please check the target address and try again. |
| 900x to 901x | `500` | Server encountered an error while proxying your request. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 902x | `405` | Unsupported protocol method. Please contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
| 910x | `400` | Error processing your request. Please check your request and try again. |
| 999x | `500` | Server failed to process request. Please try again or contact [support@byteful.com](mailto:support@byteful.com) if this error persists. |
### Suggested Fixes
* **Authentication Errors (`201x` to `203x`)**: Verify your proxy username and password. Double-check authentication format.
* **Data or Connection Limits (`421x` or `423x`)**: Upgrade your plan or reduce simultaneous requests.
* **Target Restricted (`423x`)**: The target website or port may be blocked by your plan or region. Try a different network or contact support.
## Still Need Help?
If you cannot resolve the issue using the Log ID and error code, please reach out to our support team with:
* The full `x-byteful-request-id` (If within 7 days of the issue and request)
* Target domain
* Approximate timestamp
* Proxy credentials used (if applicable)
📩 **[support@byteful.com](mailto:support@byteful.com)**
# Edit Payment Method
Source: https://documentation.byteful.com/general/edit-payment-method
Learn how to update your subscription payment method and automatic renewal settings in your Byteful dashboard
Subscription billing information can be edited through your Byteful dashboard by going to your Subscriptions Page and clicking the three dots next to the specific service.
![Byteful Edit Billing Button]()
## Edit Options
There are two main options when editing your subscription billing information.
### Automatic Renewal
This controls whether your payment card will be automatically charged and the subscription extended. If you pay via cryptocurrency or other methods such as store credit, then this will be set to No.
### Payment Card
This controls the payment card that an subscription will create an automatic charge from. Payment card can only be selected when Automatic Renewal is set to Yes.
![Byteful Edit Card Options]()
# Editing a Proxy User
Source: https://documentation.byteful.com/general/editing-a-proxy-user
Learn how to edit your proxy users through the Byteful dashboard
You can edit your Proxy Users via our dashboard and Proxy User management section. Simply click edit next to a Proxy User and then you'll be able to edit their details.
![Byteful Edit Proxy User]()
## Editable Attributes
| Attribute | Limitation |
| --------------------------- | ------------------------------------- |
| Proxy User Password | 10-32 Alphanumeric |
| Proxy User Residential Data | Integer greater than current GB usage |
| Proxy User Mobile Data | Integer greater than current GB usage |
| IP Authentications | Maximum of 3 per Proxy User |
| Access Control | Managed via Proxy User ACL objects |
## Editing Process
1. Navigate to the Proxy User management section in your dashboard
2. Find the proxy user you want to edit
3. Click the "Edit Authentication" button next to their name to alter the password or IP authentication, or "Edit Limits" to adjust the residential or mobile pool allowances and other service access.
4. Make your desired changes to any of the editable attributes
5. Click "Save" to apply your changes
## IP Authentication
IP authentication allows proxy access based on client IP address without sending credentials in each request. You can add up to 3 IP addresses per proxy user for authentication purposes. Each IP address can only belong to a single proxy user at any given time.
## Limits
![Byteful Proxy User Limits]()
### Residential and Mobile Data Allocation
You can edit the proxy user's residential or mobile pool allowance clicking Edit Limits next to the proxy user on the dashboard.
### Other Services
You can control which proxies a proxy user can access using the `proxy_user_access_type` field and Proxy User ACL entries:
* **Unrestricted Access (`"all"`)**: The proxy user can access all proxies in your account
* **Service Restricted (`"service_restricted"`)**: The proxy user can only access proxies within specific services. Create Proxy User ACL entries to grant access to services.
* **Proxy Restricted (`"proxy_restricted"`)**: The proxy user can only access specific individual proxies. Create Proxy User ACL entries to grant access to proxies.
Use the Proxy User ACL endpoints to manage which services or proxies a restricted proxy user can access. See the [Proxy User Access Control guide](/api-explainers/proxy-user-access-control) for more details.
# Ethical Sourcing Guidelines
Source: https://documentation.byteful.com/general/ethical-sourcing
Our commitment to ethical proxy sourcing and maintaining the highest standards of compliance and transparency.
## Our Commitment to Ethical Proxy Sourcing
We believe that ethical sourcing isn't just a best practice; it is fundamental to building trust, ensuring compliance, and maintaining the integrity of our network. We are committed to responsible and legal proxy sourcing across all our services, ensuring that every IP address in our network is obtained through ethical means with consent.
In an industry that unfortunately has a darker side with unethical practices, maintaining high standards is crucial. The proxy industry has faced challenges with questionable sourcing methods, making it essential for legitimate providers to demonstrate their commitment to ethical practices.
We explore the importance of ethical proxy sourcing in detail in our blog post: [Why Ethical Proxy Sourcing Matters](https://byteful.com/blog/ethical-proxy-sourcing)
## Our Sourcing Methods
### Residential and Mobile Proxies: Verified SDK Partners and Earn Apps
For our residential and mobile proxy networks, we exclusively work with:
**Verified SDK Providers**
* Partnership with established, compliant SDK providers who maintain high ethical standards
* All SDK integrations require explicit user opt-in consent
* Users are fully informed about data sharing and any available compensation or reward if available
**Well-Known Earn Apps**
* Collaboration with reputable earn applications that offer financial rewards for data sharing
* Users voluntarily participate in exchange for fair monetary compensation
* Clear terms of service and privacy policies for all participants
* Transparent communication about how shared data is utilized
### Static ISP and Datacenter Proxies: Direct Carrier Partnerships
For our Static ISP and Datacenter proxy services, we maintain:
**Direct Carrier Relationships**
* Work exclusively with legitimate internet service providers and data centers
* Direct compensation to IP address owners and carriers
* Formal agreements ensuring all parties benefit from the arrangement
* No ethical concerns as all transactions are business-to-business with mutual benefit
**Transparent Ownership**
* Clear chain of custody for all IP addresses
* Direct relationships eliminate middlemen and potential ethical issues
* All parties are willing participants receiving fair compensation
* Full compliance with carrier policies and industry standards
## Questions?
Our sourcing methods ensure that every IP address in our network comes from legitimate, consenting sources with proper compensation and transparency but if you have any questions at all, please contact our compliance team at [compliance@byteful.com](mailto:compliance@byteful.com).
# Understanding Mobile Proxies
Source: https://documentation.byteful.com/general/explaining-mobile-proxies
Learn about mobile proxies, their benefits, and how they work at Byteful
![Byteful Mobile Proxies]()
Mobile proxies are proxy servers that use real mobile IP addresses. Unlike other proxy types that rely on datacenters or servers, mobile proxies route traffic through devices of users on mobile networks. This changes your own IP address to a mobile IP address in a different location.
## Why Use Mobile Proxies?
With mobile proxies, websites can't easily detect that your traffic is coming from a proxy. Since many websites and services tend to ban IPs that are identifiable as proxies, using a mobile proxy is the most effective way to avoid such restrictions.
* Higher success rates on restrictive websites
* More natural browsing patterns
* Access to geo-restricted content
* Lower detection rates
* Wide range of locations
## When to Use Mobile Proxies
Mobile proxies sit in a different part of the trade-off space to residential proxies. Here's how to think about it as a developer.
### Pros
* **Hardest IPs to ban or rate limit.** Mobile carriers run their networks behind CGNAT (Carrier-Grade NAT), so thousands of real users share each public IP. Banning a single mobile IP means cutting off a lot of legitimate traffic, so target sites are very cautious about doing it.
* **Dynamic behaviour is assumed.** Mobile devices are expected to roam, drop connections and rotate addresses. Patterns that would look suspicious on a fixed line look completely normal coming from a mobile IP.
### Cons
* **Smaller pool size.** Because every mobile IP sits behind thousands of users, the total node count is lower than a large residential network. This is largely offset by how hard each IP is to ban, but it's worth knowing if you're running very high concurrency.
* **Slightly worse network performance.** Mobile proxies have higher latency, lower throughput and less stable connections than residential proxies. Not bad, just worse in comparison. This is a characteristic of 4G/5G networks versus fixed-line residential connections, plus the fact that the underlying device may be moving or hitting signal changes.
### Which one should you pick?
Reach for mobile proxies when the target is aggressive about banning residential IPs, or when you need the highest possible trust score on a request. Common cases include social networks, sneaker and ticketing sites, ad verification, and anything mobile-first.
If the target is less hostile and you care more about raw throughput, concurrency or steady connections, residential proxies are usually the better fit.
## How Mobile Proxies Are Charged
Mobile proxies at Byteful use a **Pay per GB model**. Charges are based on the amount of data (data) transferred through the proxy service.
This is similar to how mobile phone plans charge for data usage - you pay for what you consume. For instance, just as you might pay for 5GB of mobile phone data per month, you could pay for 5GB of proxy data.
This model is particularly beneficial for users who need access to a wide range of IP addresses across various regions but may not have consistent or high-volume usage.
## Unlimited Proxy Generation
Yes! We have no limitations on proxies or concurrency with our mobile data packages since they're charged per GB.
This means you can generate millions of different proxies and use them concurrently without worrying about rate-limiting. Your only constraint is the amount of data in your account.
## Geographic Coverage
Our mobile network spans over 6 million monthly IPs across 1,500+ cities in 190+ countries. After purchase, you can select the country or city you'd like to geolocate your proxies to.
Increasing the precision of proxy geolocation reduces the number of available proxies. We generally recommend using country-level geolocation, unless you specifically need city-based proxies. This approach provides a good balance between location accuracy and proxy pool size.
## Carrier and ASN Targeting
Yes! All plans come with carrier and ASN targeting as standard, with IPs sourced from 650+ mobile carriers worldwide.
We offer proxies from all major carriers including:
* China Mobile
* Reliance Jio
* Vodafone Group
* Bharti Airtel
* Verizon
* AT\&T
* Deutsche Telekom
* T-Mobile US
* And hundreds more
Limiting the ASN of your proxies reduces the number of available proxies. Unless you specifically need proxies from a specific carrier, we generally recommend leaving this feature off.
## Ethical Sourcing
Yes! Byteful partners with SDK providers and peer payment applications which compensate developers and end-users for their participation in our network.
These programs pay regular internet users and/or developers who participate in the network. SDK providers and partner applications must get opt-in consent from end-users. This way, users and developers are fairly compensated and are always well-informed about how their IP addresses might be used.
On top of that, Byteful has a strict [Acceptable Usage Policy](/general/acceptable-usage-policy) which helps ensure that users don't misuse the proxy. This protects everyone within the proxy network and minimizes the amount of shady or illegal activities.
## Next Steps
Now that you understand the basics of mobile proxies, you might want to explore:
Learn how to create and manage mobile proxies for your needs
Understand the difference between sticky and rotating mobile proxies
Learn how to target specific countries and cities with your proxies
Discover how to target specific carriers and networks
# Understanding Residential Proxies
Source: https://documentation.byteful.com/general/explaining-residential-proxies
Learn about residential proxies, their benefits, and how they work at Byteful
![Byteful Residential Proxies]()
Residential proxies are proxy servers that use real residential IP addresses. Unlike other proxy types that rely on datacenters or servers, residential proxies route traffic through devices of users in residential areas. This changes your own IP address to a residential IP address in a different location.
## Why Use Residential Proxies?
With residential proxies, websites can't easily detect that your traffic is coming from a proxy. Since many websites and services tend to ban IPs that are identifiable as proxies, using a residential proxy is the most effective way to avoid such restrictions.
* Higher success rates on restrictive websites
* More natural browsing patterns
* Access to geo-restricted content
* Lower detection rates
* Wide range of locations
## How Residential Proxies Are Charged
Residential proxies at Byteful use a **Pay per GB model**. Charges are based on the amount of data (data) transferred through the proxy service.
This is similar to how mobile phone plans charge for data usage - you pay for what you consume. For instance, just as you might pay for 5GB of mobile phone data per month, you could pay for 5GB of proxy data.
This model is particularly beneficial for users who need access to a wide range of IP addresses across various regions but may not have consistent or high-volume usage.
## Unlimited Proxy Generation
Yes! We have no limitations on proxies or concurrency with our residential data packages since they're charged per GB.
This means you can generate millions of different proxies and use them concurrently without worrying about rate-limiting. Your only constraint is the amount of data in your account.
## Geographic Coverage
We support over 195 countries and every major city in the world on all residential data plans. After purchase, you can select the country or city you'd like to geolocate your proxies to.
Increasing the precision of proxy geolocation reduces the number of available proxies. We generally recommend using country-level geolocation, unless you specifically need city-based proxies. This approach provides a good balance between location accuracy and proxy pool size.
## Carrier and ASN Targeting
Yes! All plans come with carrier and ASN targeting as standard and you can select from over 10,000 networks and ASNs.
We offer proxies from all major carriers including:
* China Mobile
* Reliance Jio
* Vodafone Group
* Bharti Airtel
* Verizon
* AT\&T
* Deutsche Telekom
* T-Mobile US
* And hundreds more
Limiting the ASN of your proxies reduces the number of available proxies. Unless you specifically need proxies from a specific carrier, we generally recommend leaving this feature off.
## Ethical Sourcing
Yes! Byteful partners with SDK providers and peer payment applications which compensate developers and end-users for their participation in our network.
These programs pay regular internet users and/or developers who participate in the network. SDK providers and partner applications must get opt-in consent from end-users. This way, users and developers are fairly compensated and are always well-informed about how their IP addresses might be used.
On top of that, Byteful has a strict [Acceptable Usage Policy](/general/acceptable-usage-policy) which helps ensure that users don't misuse the proxy. This protects everyone within the proxy network and minimizes the amount of shady or illegal activities.
## Next Steps
Now that you understand the basics of residential proxies, you might want to explore:
Learn how to create and manage residential proxies for your needs
Understand the difference between sticky and rotating residential proxies
Learn how to target specific countries and cities with your proxies
Discover how to target specific carriers and networks
# Forgotten Password
Source: https://documentation.byteful.com/general/forgot-password
How to reset your password if you've forgotten it for your Byteful account
If you've forgotten your password and can't login to your Byteful account then you can head to our Password Reset page to set a new password.
To change reset your password:
1. Go to the Password Reset page
2. Enter a new new password, first in the New Password box and then in the Repeat new password box.
3. Click Submit
4. A page will appear and an email will be sent to you with a code confirming you have are the account owner and have permissions to change the password.
5. Enter the code and click Confirm
Your account is now associated with your new password and you can login with these new details.
![Byteful Forgotten Password]()
# Generating Mobile Proxies
Source: https://documentation.byteful.com/general/generating-mobile-proxies
Learn how to generate and use mobile proxies on our platform
If you have available mobile data on your account you can generate mobile proxies on the Mobile Generator dashboard section.
You can generate 1,000 proxies at a time through the dashboard and you can do this an unlimited number of times.
The generator will allow you to select your geolocation and carrier settings as well as the session type.
![Byteful Mobile Proxies Generator]()
## Syntax Generation
You can also generate mobile proxies via syntax generation. Our proxies have a standardized format and as long as you generate proxy information in this format then your proxies will be accepted by our network.
### Basic Random Mobile Proxy
**Format**
```
mobile.byteful.com:8000:{username}:{password}
```
**Example**
```
mobile.byteful.com:8000:stevejobs:apple123
```
### Sticky Mobile Proxy
You can make a proxy have a sticky IP address by adding a session ID in this format: `_s_{random_alphanumeric}` to the username field of the proxy. Any requests with using a proxy with the same alphanumeric session ID will try to link you to the same IP address as the first request with that session ID.
**Format**
```
mobile.byteful.com:8000:{username}_s_{random_alphanumeric}:{password}
```
**Example of a Sticky Proxy**
```
mobile.byteful.com:8000:stevejobs_s_we12NkllMSS:apple123
```
#### Session TTL (Time to Live)
You can maintain the same IP address for a specific duration by adding a TTL parameter in this format: `_ttl_{number}{unit}` to the username field of the proxy. The unit can be `m` for minutes, `h` for hours or `d` for days. The session TTL parameter must be accompanied by a session ID.
**Format**
```
mobile.byteful.com:8000:{username}_s_{random_alphanumeric}_ttl_{number}{unit}:{password}
```
**Examples of Session TTL Proxy**
```
mobile.byteful.com:8000:stevejobs_s_we12NkllMSS_ttl_30m:apple123
mobile.byteful.com:8000:stevejobs_s_we12NkllMSS_ttl_2h:apple123
mobile.byteful.com:8000:stevejobs_s_we12NkllMSS_ttl_1d:apple123
```
The minimum TTL is **1 minute** and the maximum TTL is **24 hours**. By default we try to hold the IP for as long as possible (7 days).
While TTL parameters allow you to specify how long to maintain the same IP address, mobile nodes cannot be guaranteed to be online for the entire duration. The IP address might change if the mobile device goes offline before the TTL expires.
### Enabling Smartpath
[Smartpath®](/general/using-smartpath-mobile) is an intelligent, AI-driven proxy routing feature designed to optimize your mobile proxy data usage by dynamically routing traffic through mobile or datacenter IPs.
You can easily enable Smartpath through the mobile generator or adding `_smartpath` to your proxy username field after your proxy\_user\_id.
**Format**
```
mobile.byteful.com:8000:{username}_smartpath:{password}
```
**Example of a Smartpath Proxy**
```
mobile.byteful.com:8000:stevejobs_smartpath:apple123
```
Smartpath is compatiable with all other mobile proxy parameters, however, if Smartpath classifies a request as not requiring mobile IP address then it does not respect other parameters and instead, routes the request through a datacenter proxy.
### Country Targeting
You can make a proxy have a IP address from a specific country by adding a country ISO 3166 code in this format: `_c_{country_iso_code}` to the username field of the proxy. Any requests with using a proxy with the ISO code will return a proxy with an IP address from the selected country.
**Format**
```
mobile.byteful.com:8000:{username}_c_{country_iso_code}:{password}
```
**Example of a United Kingdom Proxy**
```
mobile.byteful.com:8000:stevejobs_c_gb:apple123
```
### State Targeting
You can make a proxy have a IP address from a specific state by adding the state name in this format: `_state_{state_name}` to the username field of the proxy. Any requests with using a proxy with the state will return a proxy with an IP address from the selected state.
You can find out a full list of available state and their names via the dashboard or via the API where you can find all US states through the `/subdivision/search` endpoint while filtering by `country_id=us`.
**Format**
```
mobile.byteful.com:8000:{username}_c_us_state_{state_name}:{password}
```
**Example of a Florida Proxy**
```
mobile.byteful.com:8000:stevejobs_c_us_state_florida:apple123
```
### City Targeting
You can make a proxy have a IP address from a specific city by adding city name or alias in this format: `_city_{city_alias}` to the username field of the proxy. Any requests with using a proxy with the city alias will return a proxy with an IP address from the selected city.
You can find out a full list of available cities and their alias via the dashboard.
**Format**
```
mobile.byteful.com:8000:{username}_c_{country_iso_code_of_city}_city_{city_alias}:{password}
```
**Example of a London Proxy**
```
mobile.byteful.com:8000:stevejobs_c_gb_city_london:apple123
```
### Zip Code Targeting
You can make a proxy have a IP address from a specific ZIP code ID to the proxy in this format: `_zip_{zip_code_id}` to the username field of the proxy. Any requests with using a proxy with the ZIP code ID will return a proxy with an IP address from the selected ZIP code.
You can find out a full list of available ZIP codes and their ID's via the dashboard or via the API where we have a `/zip_code/search` endpoint.
Since ZIP codes represent a very specific, limited population area, it is unlikely we will have a large number of proxies online from every ZIP code at a single time. You can overcome this issue by ensuring the ZIP code you are targeting has currently online proxies using our `/mobile_availability/search` endpoint and filtering by `zip_code_id`. Alternatively, you can see an interactive, live view of all ZIP codes and their current node count on the mobile dashboard.
**Format**
```
mobile.byteful.com:8000:{username}_c_{country_iso_code_of_zip_code}_zip_{zip_code_id}:{password}
```
**Example of a ZIP Code 32808 Proxy**
```
mobile.byteful.com:8000:stevejobs_c_us_zip_32808:apple123
```
### ASN Targeting
You can make a proxy have a IP address from a specific ASN / Carrier by adding ASN in this format: `_asn_{asn_number}` to the username field of the proxy. Any requests with using a proxy with the ASN number will return a proxy with an IP address from that network.
You can find out a full list of available carriers and ASNs via the dashboard.
**Format**
```
mobile.byteful.com:8000:{username}_asn_{asn_number}:{password}
```
**Example of a AT\&T Proxy**
```
mobile.byteful.com:8000:stevejobs_asn_7018:apple123
```
### Combined Targeting
You can combine any of the above targeting methods together to your proxy information to further limit the IP Addresses of your proxies.
**Example of a AT\&T Proxy in Charlotte, NC USA**
```
mobile.byteful.com:8000:stevejobs_c_us_city_charlotte_asn_7018:apple123
```
**Example of a Sticky AT\&T Proxy in Charlotte, NC USA**
```
mobile.byteful.com:8000:stevejobs_c_us_city_charlotte_asn_7018_s_h12kJsas129:apple123
```
**Example of a Sticky United Kingdom Proxy**
```
mobile.byteful.com:8000:stevejobs_c_gb_s_dvnwcNOod12312s:apple123
```
## API Generation
You can also generate mobile proxies programmatically using our API:
Learn how to generate mobile proxies using the API with code examples in Python, JavaScript, PHP, Go, and Java.
# Generating Residential Proxies
Source: https://documentation.byteful.com/general/generating-residential-proxies
Learn how to generate and use residential proxies on our platform
If you have available residential data on your account you can generate residential proxies on the Residential Generator dashboard section.
You can generate 1,000 proxies at a time through the dashboard and you can do this an unlimited number of times.
The generator will allow you to select your geolocation and carrier settings as well as the session type.
![Byteful Residential Proxies Generator]()
## Syntax Generation
You can also generate residential proxies via syntax generation. Our proxies have a standardized format and as long as you generate proxy information in this format then your proxies will be accepted by our network.
### Basic Random Residential Proxy
**Format**
```
residential.byteful.com:8000:{username}:{password}
```
**Example**
```
residential.byteful.com:8000:stevejobs:apple123
```
### Sticky Residential Proxy
You can make a proxy have a sticky IP address by adding a session ID in this format: `_s_{random_alphanumeric}` to the username field of the proxy. Any requests with using a proxy with the same alphanumeric session ID will try to link you to the same IP address as the first request with that session ID.
**Format**
```
residential.byteful.com:8000:{username}_s_{random_alphanumeric}:{password}
```
**Example of a Sticky Proxy**
```
residential.byteful.com:8000:stevejobs_s_we12NkllMSS:apple123
```
#### Session TTL (Time to Live)
You can maintain the same IP address for a specific duration by adding a TTL parameter in this format: `_ttl_{number}{unit}` to the username field of the proxy. The unit can be `m` for minutes, `h` for hours or `d` for days. The session TTL parameter must be accompanied by a session ID.
**Format**
```
residential.byteful.com:8000:{username}_s_{random_alphanumeric}_ttl_{number}{unit}:{password}
```
**Examples of Session TTL Proxy**
```
residential.byteful.com:8000:stevejobs_s_we12NkllMSS_ttl_30m:apple123
residential.byteful.com:8000:stevejobs_s_we12NkllMSS_ttl_2h:apple123
residential.byteful.com:8000:stevejobs_s_we12NkllMSS_ttl_1d:apple123
```
The minimum TTL is **1 minute** and the maximum TTL is **24 hours**. By default we try to hold the IP for as long as possible (7 days).
While TTL parameters allow you to specify how long to maintain the same IP address, residential nodes cannot be guaranteed to be online for the entire duration. The IP address might change if the residential device goes offline before the TTL expires.
### Enabling Smartpath
[Smartpath®](/general/using-smartpath) is an intelligent, AI-driven proxy routing feature designed to optimize your residential proxy data usage by dynamically routing traffic through residential or datacenter IPs.
You can easily enable Smartpath through the residential generator or adding `_smartpath` to your proxy username field after your proxy\_user\_id.
**Format**
```
residential.byteful.com:8000:{username}_smartpath:{password}
```
**Example of a Smartpath Proxy**
```
residential.byteful.com:8000:stevejobs_smartpath:apple123
```
Smartpath is compatiable with all other residential proxy parameters, however, if Smartpath classifies a request as not requiring residential IP address then it does not respect other parameters and instead, routes the request through a datacenter proxy.
### Country Targeting
You can make a proxy have a IP address from a specific country by adding a country ISO 3166 code in this format: `_c_{country_iso_code}` to the username field of the proxy. Any requests with using a proxy with the ISO code will return a proxy with an IP address from the selected country.
**Format**
```
residential.byteful.com:8000:{username}_c_{country_iso_code}:{password}
```
**Example of a United Kingdom Proxy**
```
residential.byteful.com:8000:stevejobs_c_gb:apple123
```
### State Targeting
You can make a proxy have a IP address from a specific state by adding the state name in this format: `_state_{state_name}` to the username field of the proxy. Any requests with using a proxy with the state will return a proxy with an IP address from the selected state.
You can find out a full list of available state and their names via the dashboard or via the API where you can find all US states through the `/subdivision/search` endpoint while filtering by `country_id=us`.
**Format**
```
residential.byteful.com:8000:{username}_c_us_state_{state_name}:{password}
```
**Example of a Florida Proxy**
```
residential.byteful.com:8000:stevejobs_c_us_state_florida:apple123
```
### City Targeting
You can make a proxy have a IP address from a specific city by adding city name or alias in this format: `_city_{city_alias}` to the username field of the proxy. Any requests with using a proxy with the city alias will return a proxy with an IP address from the selected city.
You can find out a full list of available cities and their alias via the dashboard.
**Format**
```
residential.byteful.com:8000:{username}_c_{country_iso_code_of_city}_city_{city_alias}:{password}
```
**Example of a London Proxy**
```
residential.byteful.com:8000:stevejobs_c_gb_city_london:apple123
```
### Zip Code Targeting
You can make a proxy have a IP address from a specific ZIP code ID to the proxy in this format: `_zip_{zip_code_id}` to the username field of the proxy. Any requests with using a proxy with the ZIP code ID will return a proxy with an IP address from the selected ZIP code.
You can find out a full list of available ZIP codes and their ID's via the dashboard or via the API where we have a `/zip_code/search` endpoint.
Since ZIP codes represent a very specific, limited population area, it is unlikely we will have a large number of proxies online from every ZIP code at a single time. You can overcome this issue by ensuring the ZIP code you are targeting has currently online proxies using our `/residential_availability/search` endpoint and filtering by `zip_code_id`. Alternatively, you can see an interactive, live view of all ZIP codes and their current node count on the residential dashboard.
**Format**
```
residential.byteful.com:8000:{username}_c_{country_iso_code_of_zip_code}_zip_{zip_code_id}:{password}
```
**Example of a ZIP Code 32808 Proxy**
```
residential.byteful.com:8000:stevejobs_c_us_zip_32808:apple123
```
### ASN Targeting
You can make a proxy have a IP address from a specific ASN / Carrier by adding ASN in this format: `_asn_{asn_number}` to the username field of the proxy. Any requests with using a proxy with the ASN number will return a proxy with an IP address from that network.
You can find out a full list of available carriers and ASNs via the dashboard.
**Format**
```
residential.byteful.com:8000:{username}_asn_{asn_number}:{password}
```
**Example of a AT\&T Proxy**
```
residential.byteful.com:8000:stevejobs_asn_7018:apple123
```
### Combined Targeting
You can combine any of the above targeting methods together to your proxy information to further limit the IP Addresses of your proxies.
**Example of a AT\&T Proxy in Charlotte, NC USA**
```
residential.byteful.com:8000:stevejobs_c_us_city_charlotte_asn_7018:apple123
```
**Example of a Sticky AT\&T Proxy in Charlotte, NC USA**
```
residential.byteful.com:8000:stevejobs_c_us_city_charlotte_asn_7018_s_h12kJsas129:apple123
```
**Example of a Sticky United Kingdom Proxy**
```
residential.byteful.com:8000:stevejobs_c_gb_s_dvnwcNOod12312s:apple123
```
## API Generation
You can also generate residential proxies programmatically using our API:
Learn how to generate residential proxies using the API with code examples in Python, JavaScript, PHP, Go, and Java.
# Geolocation Targeting
Source: https://documentation.byteful.com/general/geolocation-targeting
How to target specific countries and cities with residential proxies
Country and city geolocation targeting comes as standard with all residential data purchases. We support over 195 countries and every major city in the world.
You can generate proxies which are geolocated to specific countries or cities through both our dashboard generator and through syntax generation in your API requests.
## Country Targeting
When generating residential proxies, you can specify the country using the ISO country code:
```bash theme={null}
# Generate 5 proxies from the United States
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&list_count=5' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
This will return proxies exclusively from the specified country:
```json theme={null}
{
"data": [
"socks5h://your_user_c_us_s_DDINPY7TQ0781XEO:your_password@residential.byteful.com:8000",
"socks5h://your_user_c_us_s_XIINPY7TQ0781XEA:your_password@residential.byteful.com:8000",
"socks5h://your_user_c_us_s_PPINPY7TQ0781XEB:your_password@residential.byteful.com:8000",
"socks5h://your_user_c_us_s_QQINPY7TQ0781XEC:your_password@residential.byteful.com:8000",
"socks5h://your_user_c_us_s_RRINPY7TQ0781XED:your_password@residential.byteful.com:8000"
],
"message": "Residential list successfully created."
}
```
## City Targeting
For more precise targeting, you can generate proxies from specific cities:
```bash theme={null}
# Generate 3 proxies from London, UK
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=gb&city_alias=london&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": [
"socks5h://your_user_c_gb_city_london_s_DDINPY7TQ0781XEO:your_password@residential.byteful.com:8000",
"socks5h://your_user_c_gb_city_london_s_XIINPY7TQ0781XEA:your_password@residential.byteful.com:8000",
"socks5h://your_user_c_gb_city_london_s_PPINPY7TQ0781XEB:your_password@residential.byteful.com:8000"
],
"message": "Residential list successfully created."
}
```
Notice that the city information is encoded in the proxy string (`city_london`).
## Subdivision Targeting
You can also target specific subdivisions (states, provinces, regions) within countries:
```bash theme={null}
# Generate 3 proxies from California, US
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&subdivision_id=us-ca&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Finding Available Cities
To discover which cities are available within a country, you can use the city search endpoint:
```bash theme={null}
# List cities in the United Kingdom
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/city/search?country_id=gb&city_is_populous=true' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Combining Geolocation with Other Filters
For advanced targeting, you can combine geolocation with ISP/ASN targeting:
```bash theme={null}
# Generate 3 proxies from AT&T (ASN 7018) in the US
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&asn_id=7018&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Dashboard Generation
You can also easily generate geotargeted proxies through our dashboard interface by selecting the desired country and city from the dropdown menus in the residential proxy generator.
For more information on generating residential proxies, see the [Generating Residential Proxies](/general/generating-residential-proxies) guide.
# Geolocation Targeting
Source: https://documentation.byteful.com/general/geolocation-targeting-mobile
How to target specific countries and cities with mobile proxies
Country and city geolocation targeting comes as standard with all mobile data purchases. We support over 195 countries and every major city in the world.
You can generate proxies which are geolocated to specific countries or cities through both our dashboard generator and through syntax generation in your API requests.
## Country Targeting
When generating mobile proxies, you can specify the country using the ISO country code:
```bash theme={null}
# Generate 5 proxies from the United States
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?country_id=us&list_count=5' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
This will return proxies exclusively from the specified country:
```json theme={null}
{
"data": [
"socks5h://your_user_c_us_s_DDINPY7TQ0781XEO:your_password@mobile.byteful.com:8000",
"socks5h://your_user_c_us_s_XIINPY7TQ0781XEA:your_password@mobile.byteful.com:8000",
"socks5h://your_user_c_us_s_PPINPY7TQ0781XEB:your_password@mobile.byteful.com:8000",
"socks5h://your_user_c_us_s_QQINPY7TQ0781XEC:your_password@mobile.byteful.com:8000",
"socks5h://your_user_c_us_s_RRINPY7TQ0781XED:your_password@mobile.byteful.com:8000"
],
"message": "Mobile list successfully created."
}
```
## City Targeting
For more precise targeting, you can generate proxies from specific cities:
```bash theme={null}
# Generate 3 proxies from London, UK
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?country_id=gb&city_alias=london&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
Response:
```json theme={null}
{
"data": [
"socks5h://your_user_c_gb_city_london_s_DDINPY7TQ0781XEO:your_password@mobile.byteful.com:8000",
"socks5h://your_user_c_gb_city_london_s_XIINPY7TQ0781XEA:your_password@mobile.byteful.com:8000",
"socks5h://your_user_c_gb_city_london_s_PPINPY7TQ0781XEB:your_password@mobile.byteful.com:8000"
],
"message": "Mobile list successfully created."
}
```
Notice that the city information is encoded in the proxy string (`city_london`).
## Subdivision Targeting
You can also target specific subdivisions (states, provinces, regions) within countries:
```bash theme={null}
# Generate 3 proxies from California, US
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?country_id=us&subdivision_id=us-ca&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Geo-targeting Accuracy
Country targeting for mobile proxies is reliable. State, city and ZIP targeting all work, but accuracy below country level is inherently more inconsistent for mobile IPs than for residential ones. It's worth understanding why before you rely on it for critical workloads.
The reason comes down to how mobile networks are built. Large carriers like Verizon, AT\&T and Vodafone run big, dynamic IP pools behind CGNAT (Carrier-Grade NAT). Those pools are linked to multiple regional gateways, so a single IP in one of these pools has no single fixed location. The same address can be in use by a customer in Texas and another in California at the same time.
That makes attributing a mobile IP to one specific city or state genuinely difficult, and you'll often see different geolocation databases disagree about where the same IP "lives".
**How we handle this.** We rely on at-point measurement, meaning we record where the IP was actually being used at the time we sampled it. That's the most accurate signal available for a mobile IP, but it can differ from what other geolocation databases report. When our targeting disagrees with a third party tool, that's usually a characteristic of these pools rather than an inaccuracy on either side.
**Why it usually doesn't matter in practice.** Most large websites already understand this behaviour and put less weight on the state, city or ZIP of a mobile IP. They lean primarily on country level signals along with other fingerprints, so unless you specifically need precise regional targeting, the practical impact of any mismatch is small.
## Finding Available Cities
To discover which cities are available within a country, you can use the city search endpoint:
```bash theme={null}
# List cities in the United Kingdom
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/city/search?country_id=gb&city_is_populous=true' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Combining Geolocation with Other Filters
For advanced targeting, you can combine geolocation with ISP/ASN targeting:
```bash theme={null}
# Generate 3 proxies from AT&T (ASN 7018) in the US
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?country_id=us&asn_id=7018&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Dashboard Generation
You can also easily generate geotargeted proxies through our dashboard interface by selecting the desired country and city from the dropdown menus in the mobile proxy generator.
For more information on generating mobile proxies, see the [Generating Mobile Proxies](/general/generating-mobile-proxies) guide.
# Integrating on Android or iOS
Source: https://documentation.byteful.com/general/integration/android-iphone
Learn how to use Byteful on mobile devices, including setup recommendations for iOS and Android.
Byteful can be used on mobile devices, but native proxy support on both iOS and Android has several limitations that affect compatibility and performance when using authenticated proxies.
## Limitations of Native Proxy Support
Both iOS and Android offer built-in proxy settings under Wi-Fi network configurations. While this allows basic proxy routing, it comes with the following limitations:
* No ability to restrict or route traffic by app
* No visibility into proxy status or traffic logs
* No support for rule-based routing or custom DNS
For this reason, we recommend using third-party proxy clients that are purpose-built for mobile.
## Recommended Apps
### iOS & Android — Use Shadowrocket
We recommend using **Shadowrocket**, a powerful proxy client that supports:
* Full authentication (username and password)
* HTTP, HTTPS, SOCKS5, and custom rule routing
* Per-domain and per-app rules
* DNS over HTTPS and custom DNS settings
* Detailed logging and connection stats
> 📘 To get started, follow our [Shadowrocket Integration Guide](/general/integration/shadowrocket) for a complete walkthrough.
Shadowrocket is a paid app available on the App Store. Once configured, it enables seamless proxy usage across all apps on the device.
# Integrating with a Browser
Source: https://documentation.byteful.com/general/integration/browser-integrations
Learn how to integrate Byteful services with popular browsers.
All Byteful services can be easily integrated into most internet browsers including Google Chrome, Firefox, Safari, Brave, and many more.
We currently recommend using FoxyProxy to add proxies to your browser. You can download the extension using the links below:
* [FoxyProxy Chrome](https://chrome.google.com/webstore/detail/foxyproxy-standard/gcknhkkoolaabfmlnjonogaaifnjlfnp?hl=en)
* [FoxyProxy Brave](https://chrome.google.com/webstore/detail/foxyproxy-standard/gcknhkkoolaabfmlnjonogaaifnjlfnp?hl=en)
* [FoxyProxy Firefox](https://addons.mozilla.org/en-GB/firefox/addon/foxyproxy-standard/)
## Setup Guides
Choose from our detailed integration guides below. We recommend FoxyProxy for most users, but also provide alternatives like Proxy SwitchyOmega for advanced users. Some browsers like Safari and Microsoft Edge have more limited proxy support or extension availability, so we've created dedicated setup guides for these browsers. For browsers without native proxy support, we recommend using Proxifier as a system-wide proxy solution.
Step-by-step guide to configure Byteful with the FoxyProxy browser extension.
Advanced proxy management with SwitchyOmega extension for Chrome and Firefox.
Native proxy configuration guide for Safari browser on macOS.
Dedicated setup guide for Microsoft Edge browser integration.
System-wide proxy solution for browsers without native proxy support.
# ClonBrowser
Source: https://documentation.byteful.com/general/integration/clonbrowser
# cURL
Source: https://documentation.byteful.com/general/integration/curl
# DICloak
Source: https://documentation.byteful.com/general/integration/dicloak
# DuckDuckGo
Source: https://documentation.byteful.com/general/integration/duckduckgo
# FoxyProxy
Source: https://documentation.byteful.com/general/integration/foxyproxy
# GoLogin
Source: https://documentation.byteful.com/general/integration/gologin
# Hayha
Source: https://documentation.byteful.com/general/integration/hayha
# ixBrowser
Source: https://documentation.byteful.com/general/integration/ixbrowser
# Lauth
Source: https://documentation.byteful.com/general/integration/lauth
# Microsoft Edge
Source: https://documentation.byteful.com/general/integration/microsoft-edge
# MuLogin
Source: https://documentation.byteful.com/general/integration/mulogin
# Multilogin
Source: https://documentation.byteful.com/general/integration/multilogin
# Nstbrowser
Source: https://documentation.byteful.com/general/integration/nstbrowser
# Octo Browser
Source: https://documentation.byteful.com/general/integration/octobrowser
# Proxifier
Source: https://documentation.byteful.com/general/integration/proxifier
# Proxy SwitchyOmega
Source: https://documentation.byteful.com/general/integration/proxy-switchyomega
# Safari
Source: https://documentation.byteful.com/general/integration/safari
# SessionBox
Source: https://documentation.byteful.com/general/integration/sessionbox
# Shadowrocket
Source: https://documentation.byteful.com/general/integration/shadowrocket
# Undetectable Browser
Source: https://documentation.byteful.com/general/integration/undetectable-browser
# VMLogin
Source: https://documentation.byteful.com/general/integration/vmlogin
# Invoices
Source: https://documentation.byteful.com/general/invoices
Learn how to view, pay, and download your invoices in the Byteful dashboard.
## View All Invoices
You can view all finalized invoices in your dashboard at the Billing Invoices section of your dashboard. Here you can see all invoices that have been are open or overdue, and have been paid or have been voided.
![Byteful Invoice List]()
## Invoice Status
| Status | Explanation |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Open | This invoice has been generated and requires payment to continue your service or begin your service. |
| Overdue | This invoice has been generated and requires payment to continue your service. It is overdue and your service is pending cancellation since the invoice is yet to be paid. Invoices stay overdue for around 24 hours until they are voided and your subscription is cancelled. |
| Paid | Your invoice is fully paid. No further action required. |
| Void | Your invoice has been voided and no payment is required as the invoice has now been invalidated. No further action required. |
## Paying an Invoice
Open invoices will appear at the top of your dashboard Billing Invoices section and you'll receive a pop-up when you login for each open invoice you have.
If you'd like you to pay your invoice, you can click **Pay** next to the invoice in the invoices table and a pop-up will appear with available payment options for this invoice.
1. Select your payment method and then click confirm
2. You'll be taken to the selected payment platform to complete the payment
3. Once paid, your invoice will be marked as paid and your subscription will be extended
![Byteful Invoice Pay]()
## Download Invoices
You can view and download all finalized invoices in your dashboard at the Billing Invoices section of your dashboard.
If you'd like to download any invoices:
1. Click **View** and then you'll be taken to a page which shows the specific information for the invoice
2. Click the **Download** button to save a PDF copy of the invoice to your local device
![Byteful Invoice download]()
# ISP / ASN Targeting
Source: https://documentation.byteful.com/general/isp-asn-targeting
Learn how to target specific internet service providers and ASNs with Byteful
All plans come with carrier and ASN targeting as standard and you can select from over 10,000 networks and ASNs.
Importantly, we won't have proxies from all ASNs available but there is a strong likelihood we will have ample availability of proxies in all large carriers such as China Mobile, Reliance Jio, Vodafone Group, Bharti Airtel, China Telecom, América Móvil, China Unicom, Telefónica, Orange, Telenor, Verizon, AT\&T, Deutsche Telekom, MTN Group, VEON, Axiata, Telkomsel, Zain Group, SoftBank, BSNL, Etisalat, Turkcell, Telecom Italia, T-Mobile US along with hundreds of others.
Limiting the ASN of your proxies reduces the number of available proxies. Unless you specifically need proxies from a specific carrier then we generally recommend leaving this feature off.
You can generate proxies which are targeting to specific ASNs through our dashboard generator and syntax generation. Find out more at [Generating Residential Proxies](/general/generating-residential-proxies).
# ISP / ASN Targeting
Source: https://documentation.byteful.com/general/isp-asn-targeting-mobile
Learn how to target specific internet service providers and ASNs with Byteful
All plans come with carrier and ASN targeting as standard and you can select from over 10,000 networks and ASNs.
Importantly, we won't have proxies from all ASNs available but there is a strong likelihood we will have ample availability of proxies in all large carriers such as China Mobile, Reliance Jio, Vodafone Group, Bharti Airtel, China Telecom, América Móvil, China Unicom, Telefónica, Orange, Telenor, Verizon, AT\&T, Deutsche Telekom, MTN Group, VEON, Axiata, Telkomsel, Zain Group, SoftBank, BSNL, Etisalat, Turkcell, Telecom Italia, T-Mobile US along with hundreds of others.
Limiting the ASN of your proxies reduces the number of available proxies. Unless you specifically need proxies from a specific carrier then we generally recommend leaving this feature off.
You can generate proxies which are targeting to specific ASNs through our dashboard generator and syntax generation. Find out more at [Generating Mobile Proxies](/general/generating-mobile-proxies).
# Know Your Customer Policy
Source: https://documentation.byteful.com/general/kyc-policy
Our comprehensive Know Your Customer (KYC) policy ensuring compliance and maintaining high ethical standards.
![Byteful KYC]()
We are committed to maintaining the highest ethical standards and ensuring our services are used responsibly. While we do not require KYC verification for every customer, we have implemented a risk-based approach to customer verification that helps us maintain a secure and compliant network environment.
## When KYC is Required
We regularly monitor network activity and may request KYC verification in the following circumstances:
##### Automatic KYC Requirements
* **All resellers:** Any customer operating as a reseller or redistributor of our services
* **Free trial requests:** Customers requesting access to free trial periods
* **Large usage patterns:** Customers with high data consumption or extensive proxy usage
##### Risk-Based KYC Triggers
* **Sensitive domain access:** Activity involving domains that are sensitive but not entirely blocked
* **Random compliance checks:** Small, randomly selected customer groups to ensure ongoing compliance and deter bad actors
* **Additional risk factors:** As determined by our automated monitoring systems and risk assessment protocols
**From 7 September 2026, traffic sent directly to IP addresses is blocked by default.** Customers who need access can request it by opening a ticket in the dashboard. Requests are reviewed case by case and typically require KYC verification.
## Verification Process
We partner with [**Idenfy**](https://www.idenfy.com/), a trusted identity verification provider, to conduct our KYC processes. This ensures secure, reliable, and compliant customer verification while protecting your personal information.
## Information Required
Our KYC process is designed to be comprehensive yet respectful of your privacy. We may request the following information:
### Company Details
* Registered company name
* Business industry and sector
* Date of incorporation
* Registered company address
### Contact Information
* Primary phone number
* Business email address
* Authorized contact person details
### Usage Information
* Business model description
* Methodology of proxy usage
* Planned use cases and applications
* Expected usage volumes
### Additional Documentation
* Business registration documents
* Identity verification for authorized representatives
* Any additional documentation requested by our Risk team
## Compliance and Cooperation
By maintaining these high ethical standards through selective KYC verification, we ensure that Byteful remains a trusted platform for legitimate business use while protecting the integrity of our network and the broader internet ecosystem.
## Contact
If you have questions about our KYC policy or have been requested to complete verification, please contact our compliance team at [compliance@byteful.com](mailto:compliance@byteful.com).
***
*This policy is subject to updates as we continue to enhance our compliance procedures and maintain the highest standards of service.*
# Listing and Exporting Proxies
Source: https://documentation.byteful.com/general/listing-and-exporting-proxies
How to view, filter, and export your static proxies
If you have active Datacenter Proxies or Static Residential ISP Proxies services, you can view all your assigned proxies through the Static List page. This page provides comprehensive information about each proxy, including:
* Proxy ID
* Proxy Type
* IP Address
* Carrier
* Location
* Proxy Users with access
## Static List Page
The Static List page offers a centralized view of all your static proxies with powerful filtering and export capabilities.
![Byteful Static List Export Page]()
## Filtering Proxies
You can easily search for specific proxies using various filters to quickly locate the proxies you need:
* Filter by proxy type (Datacenter, ISP)
* Filter by location (country, region, city)
* Filter by carrier/ASN
* Search by IP address
* Filter by proxy user access
## Exporting Proxies
The Static List page allows you to export your proxies to a text file in different formats to match your specific use case or software requirements.
### Export Options
When exporting your proxies, you can choose from several options:
1. **Protocol**:
* HTTP
* SOCKS5
2. **List Format**:
* Standard
* HTTP
* SOCKS5
3. **Authentication Type**:
* Proxy User authentication
* IP-based authentication
* Proxy-specific authentication
### Proxy Format Examples
| Format | Structure | Example |
| -------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Standard | `{ip_address}:{port}:{username}:{password}` | 42.34.59.198:8000:stevejobs:saM2iBP2A |
| HTTP | `http://{username}:{password}@{ip_address}:{port}` | [http://stevejobs:saM2iBP2A@42.34.59.198:8000](http://stevejobs:saM2iBP2A@42.34.59.198:8000) |
| SOCKS5 | `socks5://{username}:{password}@{ip_address}:{port}` | socks5://stevejobs:saM2iBP2A\@42.34.59.198:8000 |
The standard format (`IP:PORT:USERNAME:PASSWORD`) is widely supported across various proxy tools and software, making it the most versatile export option. However, HTTP and SOCKS5 formatted URLs may be more convenient for specific applications.
## Authentication Options
When exporting your proxies, you can choose different authentication methods based on your needs. To learn more about available authentication options, please refer to our [Proxy Authentication Types](/general/proxy-authentication-types) guide.
## Best Practices
* Regularly export updated proxy lists if your proxies get rotated or replaced
* Use meaningful filenames when exporting to keep track of different proxy groups
* Consider using IP authentication for server-based applications
* For applications requiring high security, use proxy user authentication with strict security enabled
# Live Network Activity
Source: https://documentation.byteful.com/general/live-network-activity
Learn how to use the real-time proxy debugging interface in the Byteful dashboard to monitor and troubleshoot requests as they happen.
The **Live Network Activity** viewer provides real-time visibility into every proxy request made through your account. It offers detailed metrics, a high-volume log stream, and flexible filtering—all designed to help you troubleshoot, monitor, and optimize traffic as it happens.
## Why use Live Network Activity?
Historically, proxy debugging has required combing through delayed logs, third-party monitoring tools, and disconnected status systems. The [Live Network Activity viewer](https://dashboard.byteful.com/observability/live) solves this by delivering all traffic-level insight in one place—updated in real time and tied directly to your usage.
This tool is essential for:
* Debugging failed or misrouted proxy requests
* Monitoring performance of specific hosts or applications
* Validating user-specific traffic behavior
* Troubleshooting internal service or network routing issues
## Core Capabilities
### Real-Time Request Monitoring
All proxy requests are streamed live and displayed as they happen. The table updates automatically and reflects:
* Request timestamps
* Byte counts
* Duration in milliseconds
* Target domains
* Proxy user and proxy ID
* Network type and IP addresses
You can observe immediate feedback from your requests without needing to reload the page or rely on static exports.
### Internal Error Codes
Due to TLS encryption, we do not display HTTP status codes. Instead, Byteful uses internal error codes that represent issues encountered during the connection or transmission phases.
These may include:
* DNS resolution failures
* TLS negotiation errors
* Target unreachable
* Timeout or socket closure issues
Each error code is accompanied by a user-friendly description. For a complete list, refer to our [Live Network Error Codes documentation](/general/debugging-and-error-codes#common-error-codes-and-troubleshooting).
### Flexible Filtering System
The **Add Filter** menu allows you to combine multiple filters to isolate specific events or troubleshoot traffic segments.
Available filters include:
* Log ID
* Network
* Protocol
* Error Code
* Bytes
* Duration
* Proxy User
* Client IP Address
* Proxy ID
* Proxy IP Address
* Service ID
Filters support chaining and are dynamically applied, letting you narrow down from thousands of requests to just a few relevant entries in seconds.
## Getting Started
Live Network Activity is available under the **Network Observability** section in your dashboard. It requires no setup—logging is automatic for all proxy requests made through your account.
To start:
1. Go to `Network Observability` → [Live Activity](https://dashboard.byteful.com/observability/live)
2. Use the filter menu to customize your view
3. Observe request activity in real time
The viewer is optimized for performance and can handle high request volumes without delay, even in enterprise-scale environments.
## Use Cases
Live Network Activity is especially useful for:
* **Technical debugging** of failed requests or slow responses
* **Traffic pattern inspection** for monitoring uptime and volume
* **Operational audits** tied to specific proxy users, networks, or service IDs
* **Performance monitoring** for latency or timeout detection
# Products & Purchasing
Source: https://documentation.byteful.com/general/making-your-first-purchase
Discover and purchase proxy services from the Byteful dashboard
Once you've made an account, you can login and purchase proxies from the dashboard Product Page.
![Byteful Product Page]()
Services can only be purchased via the API using your account credit balance. You must top up your account with credit prior to using the API to make purchases.
## Available Services
You can select from our four main services:
High-speed dedicated datacenter proxies with unlimited data
Dedicated residential-type IPs from major ISPs with unlimited data
Access to real residential IPs with pay-per-GB pricing
Access to real mobile IPs with pay-per-GB pricing
## Pay per IP vs Pay per GB
The two main pricing model differences between our services are **Pay per IP** vs **Pay per GB**.
* Used for **Datacenter Proxies** and **Static Residential ISP Proxies**
* Pay for each unique IP address you use
* Unlimited data for each IP
* Best for users requiring consistent, specific IPs
* Ideal for whitelisting or maintaining continuous connections
* Used for **Residential Proxies** and **Mobile Proxies**
* Pay based on the amount of data transferred
* Access to unlimited IP addresses from any region
* Similar to mobile phone data plans - pay for what you consume
* Best for users needing diverse geographic coverage with varying usage
## Quantity & Subscription Cycle
Once you've decided what service is best for you, the next decision will be the quantity and subscription cycle.
* **Quantity**: Determines the amount of data or IP addresses provisioned for you
* **Subscription Cycle**: Determines the frequency of your subscription payments and length of term
We automatically apply bulk quantity and subscription length discounts for all services at checkout.
## Payment Methods
We support a variety of payment methods including:
* All major cards
* Cryptocurrencies (via Bitpay and Coingate)
* ACH, Wire and UK BACs payments for purchase orders or store credit top-ups over \$1,000
For ACH, Wire and UK BACs payments over \$1,000, please contact [admin@byteful.com](mailto:admin@byteful.com).
## Order Fulfilment and Delivery
Once you've made a successful payment, your order should be delivered to your account within a few moments, and you'll receive a confirmation email.
If your order has not been delivered within ten minutes, please contact support via our dashboard ticket section or [support@byteful.com](mailto:support@byteful.com), providing your Service ID and email address.
# Observability Overview
Source: https://documentation.byteful.com/general/observability-overview
Learn how to monitor and analyze proxy usage across hostnames, users, and networks with the Byteful Observability Panel
![Byteful Network Observability]()
The **Network Observability Panel** provides real-time and historical insights into your proxy infrastructure. This panel is designed to give you comprehensive visibility across all usage dimensions—hostnames, proxy users, networks, and Smartpath® performance metrics—without needing third-party analytics tools.
## Why use Observability?
Whether you are debugging traffic anomalies, optimizing performance, or planning capacity, the Observability Panel helps you make data-driven decisions quickly and confidently. All key metrics and breakdowns are accessible in a single interface with intuitive filtering and real-time updates.
## Key Features
### Real-Time Metrics and Historical Data
* Monitor live traffic as it happens with minimal delay
* Access up to **90 days of historical data** to identify long-term trends and anomalies
* View data usage charts and request volume over time
### Advanced Filtering Options
The panel allows for precise filtering across multiple dimensions:
* Hostname
* Proxy User
* Network Type (Residential, Mobile, ISP, Datacenter)
* Time Span (Custom ranges with support for hourly to 90-day windows)
Filters support advanced operators such as `equals`, `not equals`, `contains`, and `greater than`.
### Top-Level Metrics
The top summary section includes:
* **Requests**: Total number of proxy requests
* **Bytes Usage**: Data consumption in gigabytes
* **Error Rate**: Percentage of failed or errored requests
These metrics update in near real-time and reflect the currently selected date range and filters.
## Hostnames, Users, and Networks
### Top Hostnames
Understand where your traffic is going. The panel lists the top 100 hostnames by:
* Request count
* Data usage
* Error rates
This helps in diagnosing domain-specific issues or validating traffic targets.
We may summarise hostnames in the format \*.hostname.TLD when we detect high cardinality between a large number of hostnames.
### Top Proxy Users
Gain visibility into your heaviest users:
* Track request volume and data consumption per user
* Identify abnormal usage patterns
* Pinpoint users causing elevated error rates
### Network Distribution
View traffic split by:
* Residential
* Mobile
* ISP
* Datacenter
Percentages and total volume are displayed clearly to assess distribution across your available network types.
## Smartpath® Metrics
If Smartpath is enabled for your account, the observability panel includes the following metrics:
| Metric | Description |
| --------------------- | ----------------------------------------------------- |
| AI Optimized Requests | Number of requests routed intelligently via Smartpath |
| AI Optimized Bytes | Data optimized through Smartpath routing decisions |
| Money Saved | Estimated cost savings achieved with Smartpath |
These metrics are filterable and help measure Smartpath’s impact across specific users, domains, and time periods.
![Byteful Smartpath Analytics]()
## Network Activity Table
At the bottom of the observability panel, a detailed activity table logs all traffic events by the hour, grouped by:
* Timestamp
* Proxy User
* Hostname
* Network Type
* Request Count
* Bytes Usage
* Smartpath Savings
* Billed Bytes
# OS Targeting
Source: https://documentation.byteful.com/general/os-targeting
How to target specific operating systems with residential proxies
Operating system targeting comes as standard with residential data purchases. You can target proxies on devices running the following operating systems: `windows`, `linux`, and `android`.
BETA: we cannot guarantee that OS targeting will persist in the future for our residential network proxies.
Limiting the operating system of your proxies reduces the number of available proxies. Unless you specifically need proxies from devices running a specific operating system then we generally recommend leaving this feature off.
You can specify an operating system for a proxy by adding the OS in this format: `_os_{operating_system}` to the username field of the proxy.
## OS Targeting
```bash theme={null}
# Generate 5 proxies from devices running Linux
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?list_os=linux&list_count=5' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
This will return proxies exclusively from devices running the specified operating system:
```json theme={null}
{
"data": [
"residential.byteful.com:8065:your_user_os_linux_s_TNJJENYJ5F4802LK:your_password",
"residential.byteful.com:8668:your_user_os_linux_s_RK9TB7HK0CIW0TC0:your_password",
"residential.byteful.com:8688:your_user_os_linux_s_PGSQD4C0LTV2UZ8B:your_password",
"residential.byteful.com:8811:your_user_os_linux_s_7QA931N9NE57I87U:your_password",
"residential.byteful.com:8628:your_user_os_linux_s_WPNYF1EMPF9UKSNH:your_password"
],
"message": "Residential list successfully generated."
}
```
## Combining OS Targeting with Other Filters
For advanced targeting, you can combine OS targeting with geolocation targeting:
```bash theme={null}
# Generate 3 proxies from Windows devices in the US
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&list_os=windows&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Dashboard Generation
You can also easily generate OS targeted proxies through our dashboard interface by selecting the desired operating system from the dropdown menu in the residential proxy generator.
For more information on generating residential proxies, see the [Generating Residential Proxies](/general/generating-residential-proxies) guide.
# OS Targeting
Source: https://documentation.byteful.com/general/os-targeting-mobile
How to target specific operating systems with mobile proxies
Operating system targeting comes as standard with mobile data purchases. You can target proxies on devices running the following operating systems: `windows`, `linux`, and `android`.
BETA: we cannot guarantee that OS targeting will persist in the future for our mobile network proxies.
Limiting the operating system of your proxies reduces the number of available proxies. Unless you specifically need proxies from devices running a specific operating system then we generally recommend leaving this feature off.
You can specify an operating system for a proxy by adding the OS in this format: `_os_{operating_system}` to the username field of the proxy.
## OS Targeting
```bash theme={null}
# Generate 5 proxies from devices running Linux
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?list_os=linux&list_count=5' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
This will return proxies exclusively from devices running the specified operating system:
```json theme={null}
{
"data": [
"mobile.byteful.com:15391:your_user_os_linux_s_TNJJENYJ5F4802LK:your_password",
"mobile.byteful.com:15452:your_user_os_linux_s_RK9TB7HK0CIW0TC0:your_password",
"mobile.byteful.com:15288:your_user_os_linux_s_PGSQD4C0LTV2UZ8B:your_password",
"mobile.byteful.com:15034:your_user_os_linux_s_7QA931N9NE57I87U:your_password",
"mobile.byteful.com:15863:your_user_os_linux_s_WPNYF1EMPF9UKSNH:your_password"
],
"message": "Mobile list successfully generated."
}
```
## Combining OS Targeting with Other Filters
For advanced targeting, you can combine OS targeting with geolocation targeting:
```bash theme={null}
# Generate 3 proxies from Windows devices in the US
curl --request GET \
--url 'https://api.byteful.com/1.0/public/user/mobile/list?country_id=us&list_os=windows&list_count=3' \
--header 'X-API-Public-Key: your_public_key' \
--header 'X-API-Private-Key: your_private_key'
```
## Dashboard Generation
You can also easily generate OS targeted proxies through our dashboard interface by selecting the desired operating system from the dropdown menu in the mobile proxy generator.
For more information on generating mobile proxies, see the [Generating Mobile Proxies](/general/generating-mobile-proxies) guide.
# Proxy Authentication Types
Source: https://documentation.byteful.com/general/proxy-authentication-types
Understanding and choosing between different proxy authentication methods
![Byteful Proxy User Dashboard]()
Byteful supports multiple authentication methods to provide flexible, secure access to your proxies. Our innovative [Proxy User and IAM system](https://dashboard.byteful.com/proxy-users) lets you create and manage proxy users, track their usage, limit residential/mobile data, and link their access to specific proxies and services—all from our dashboard.
## Authentication Methods
### Proxy User Authentication
This authentication type allows you to create a Proxy User and access all available proxies using their username and password credentials.
* **Benefits**: Use consistent credentials across all your proxies
* **Recommended for**: Resellers who want to assign each customer a dedicated proxy user with access to specific services
### IP Authentication
With IP authentication, you can access your static proxies without entering username and password credentials. This method works by:
1. Creating a proxy user
2. Attaching a whitelisted IP address to that user for authentication
**Important**: Each whitelisted IP address must be unique and cannot be assigned to multiple proxy users.
IP Authentication is not available on our rotating residential/mobile data network since the username parameters are used to infer targeting and geolocation settings.
All authentication methods can be managed through our dashboard or programmatically via our API.
# Refund Policy
Source: https://documentation.byteful.com/general/refund-policy
Understanding our refund policy and eligibility requirements for Byteful services
We offers limited refunds on standard monthly or longer service plans under specific conditions outlined in this policy. We are committed to providing high-quality proxy services and will consider refund requests that meet our eligibility criteria.
## Eligibility Requirements
To qualify for a refund, **all** of the following conditions must be met:
* **Time Limit**: Refund must be requested within 24 hours of purchase
* **Usage Limit**: Data usage cannot exceed 2GB or 25% of your allocated data (whichever is lower)
* **Customer Limit**: Each customer is limited to one refund during their lifetime with our service
* **Account Standing**: Account must be in good standing with no Acceptable Use Policy violations
## How to Request a Refund
To request a refund:
1. Email [support@byteful.com](mailto:support@byteful.com) within 24 hours of your purchase
2. Include your account details and order information
3. Provide a clear reason for your refund request
4. Our support team will review your request and respond within 1-2 business days
All refund decisions are made at our sole discretion based on the eligibility criteria outlined in this policy.
## Processing Timeline
Approved refunds will be processed within **5-10 business days** to your original payment method. Processing times may vary depending on your payment provider.
## Exclusions
The following services and situations are **not eligible** for refunds:
### Service Exclusions
* Free trials and promotional services
* Services with terms shorter than one month
* Custom term services or special contracts
### Customer Exclusions
* Customers who have previously received a refund from us
* Customers who have initiated chargebacks or payment disputes
* Accounts with Acceptable Use Policy violations
### Usage Exclusions
* Services where data usage exceeds 2GB or 25% of allocation
* Requests submitted after the 24-hour purchase window
## Important Notes
* Refunds are processed to the original payment method only
* We do not offer partial refunds or account credits as alternatives to full refunds
* This policy may be updated at our discretion; the most current version will always be available on our website
* Refund eligibility is determined solely by Ping Technology Labs LTD
## Contact Information
For questions about this refund policy or to submit a refund request, please contact:
**Email**: [support@byteful.com](mailto:support@byteful.com)
Our support team is available to assist you with any questions regarding refund eligibility or the refund process.
# Resizing your service
Source: https://documentation.byteful.com/general/resizing-your-service
Learn how to resize and reconfigure your Byteful services
Datacenter, Static Residential, Mobile Data and Residential Data services can be reconfigured and resized through your Byteful dashboard by going to your Summary Page and clicking the three dots next to the specific service.
![Service options menu]()
## Reconfiguration Options
Once clicked, a pop-up will appear and it will allow you to change your subscription payment cycle and either add or remove proxies from your service.
If you select a quantity below your current subscription size then you be able to select the specific proxies you want removed from the service. These proxies will be lost instantly after confirming the reconfiguration and you will not be able to recover them.
![Service reconfiguration options]()
## Reconfiguration Review
After making your reconfiguration options, you can click calculate to get a preview of the change. This will show you the new billing date of the subscription along with amount due immediately.
If you increase the quantity of your subscription, the additional cost will be prorated.
If you're happy with the change then you can click confirm and your reconfiguration will be instantly processed. If you've added new IPs then they'll be delivered within a few moments by our system and you'll get an email confirmation of the change.
![Service reconfiguration review]()
## Can't reconfigure your service?
Some services may not be reconfigurable and when you attempt to reconfigure them you'll see an error. This is usually the case if you've received a bespoke service or have a discount code applied to the service which is no longer supported.
# Restricted Domains
Source: https://documentation.byteful.com/general/restricted-domains
Understanding domain restrictions in the Byteful network
Byteful maintains a comprehensive list of restricted domains to ensure network security, prevent abuse, and maintain compliance with regulations.
## Direct IP Address Traffic
**From 7 September 2026, traffic sent directly to IP addresses is blocked by default.**
This kind of traffic carries a higher risk of abuse, so we are restricting it across our network.
If your use case requires it, you can request access by opening a ticket in your dashboard with a short explanation of what you need it for. Requests are reviewed case by case and typically require KYC verification.
## Why We Restrict Certain Domains
We block access to a large number of financial, banking, NSFW websites, and all government domains for several important reasons:
* **Security Purposes**: To protect sensitive financial and government infrastructure
* **Abuse Prevention**: To proactively stop any abusive activity from appearing on our network
* **Regulatory Compliance**: As an IWF (Internet Watch Foundation) member, we enforce some of their blocklists
* **Risk Management**: To reduce the risk of fraudulent activities through our proxy services
## Types of Restricted Domains
The main categories of restricted domains include:
* **Government Websites** (`.gov` domains and country-specific government domains)
* **Banking & Financial Services** (banks, payment processors, financial institutions)
* **NSFW Websites** (adult content and related services)
* **Payment Processors** (PayPal, Stripe, etc.)
* **Mail Services** (national postal services)
* **Select E-commerce Platforms** (case-by-case basis)
* **Direct IP Addresses** (requests that target an IP address instead of a hostname)
## Indicative Examples Only
Our full blocklist contains **over 6,000 items and grows dynamically every day**. Many entries are entire top-level domains (TLDs) — for example blocking `gov` or `mil` restricts millions of individual websites in a single rule.
The examples below are **indicative, not exhaustive**. They illustrate the *kinds* of domains we restrict; they are not the complete list.
We do not publish or share our full blocklist. Keeping it private is a deliberate part of how we prevent fraud and abuse across the network. If you have a legitimate use case and need to know whether a specific domain is accessible, our support team can review your use case and confirm. Contact [support@byteful.com](mailto:support@byteful.com).
```
gov.za
gov.ug
gov.im
gov.cu
gov.ca
gov.bb
gov.gq
gov.bm
gov.kn
gov.sc
gov.lk
gov.ba
gov.vu
gov.km
gov.tj
gov.do
gov.rs
gov.mw
gov.sm
gov.vg
gov.co
gov.lu
gov.ps
gov.bs
gov.tc
gov.id
gov.md
gov.cr
gov.mv
gov.pk
gov.tt
gov.pl
gov.ch
gov.fm
gov.gh
gov
gov.pm
gov.gr
gov.aw
gov.as
gov.cm
gov.mm
gov.sd
gov.cz
gov.nl
gov.lc
gov.ly
gov.ad
gov.gb
gov.ee
gov.mr
gov.xk
gov.ie
.gov.tr
gov.ml
gov.ye
gov.so
gov.gy
gov.uz
gov.gg
gov.ai
gov.az
gov.tz
gov.in
gov.vn
gov.bw
gov.ng
gov.al
gov.ao
gov.sa
gov.sk
gov.sz
gov.gd
gov.ss
gov.bn
gov.zm
gov.wf
gov.mp
gov.mg
gov.ec
gov.tm
gov.cg
gov.ga
gov.cv
gov.gl
gov.sr
gov.nc
gov.mc
gov.gm
gov.cn
gov.mo
gov.es
gov.ls
gov.is
gov.no
gov.gn
gov.dk
gov.bj
gov.lv
gov.hk
gov.sv
gov.et
gov.ck
gov.mt
gov.ir
gov.bl
gov.mk
gov.dz
gov.kr
gov.py
gov.jm
gov.cw
gov.fo
gov.bq
gov.by
gov.ky
gov.vi
gov.dj
gov.na
gov.ae
gov.si
gov.bg
gov.tl
gov.ws
gov.mz
gov.gi
gov.mf
gov.iq
gov.sx
gov.st
gov.tn
gov.ru
gov.bi
gov.jp
.gov
gov.rw
gov.af
gov.me
gov.mh
gov.bo
gov.bt
gov.ms
gov.mq
gov.er
gov.ua
gov.bd
gov.np
gov.th
gov.ve
gov.pw
gov.cd
gov.be
gov.sl
gov.cf
gov.kh
gov.fi
gov.cy
gov.sg
gov.ar
gov.pa
gov.mx
gov.ki
gov.sn
gov.se
gov.om
gov.at
gov.pr
gov.dm
gov.tg
gov.pg
gov.tw
gov.kw
gov.cl
gov.yt
gov.my
gov.br
gov.fr
gov.tr
gov.gp
gov.hu
gov.gu
gov.eg
gov.mu
gov.hr
gov.ge
gov.ke
gov.au
gov.pe
gov.gt
gov.jo
gov.ci
mil
gov.hn
gov.lr
gov.qa
gov.li
gov.fj
gov.bf
gov.ax
gov.td
gov.kz
gov.us
gov.pt
gov.nz
gov.ne
gov.sb
gov.la
gov.gf
gov.lb
gov.vc
gov.ag
gov.bh
gov.ro
gov.ni
gov.ma
gov.de
gov.re
gov.sy
gov.mn
gov.gw
```
```
banif.pt
inps.it
accordbank.com.ua
apac.bnpparibas
laposte.fr
apsbank.com.mt
jusan.kz
dnb.no
altyn-i.kz
arabbank.com
jetstar.com
bank-portal.com.ua
delphibank.com.au
mbank.com.ua
weixin.qq.com
njcb.com.cn
bankfirst.com
intesasanpaolo.com
95559.com.cn
propay.com
td.com
bsnl.co.in
cristalbank.com.ua
citibank.kz
habibbank.com
forward-bank.com
rabobank.nl
hellenicbank.com
spron.is
settlement.com.ua
rkb.lv
fastspring.com
ii-bank.com.ua
bankcomm.com
kb.com.mk
venmo.com
ebs.ie
sky.bank
policombank.com
bgl.lu
ukrsibbank.com
bancoinversion.es
bankwest.com.au
jsbchina.cn
land.lv
ccb.com
fraspa1822.de
midlandbank.co.uk
aizkraukles.com
istrobanka.sk
iboxbank.online
raiffeisen.ua
bancamarche.it
motor-bank.ua
rietumu.lv
spar.is
bankerstrust.com
atlas.co.yu
icbc.com.cn
payoneer.com
hcsbk.kz
bankofscotland.co.uk
pumb.ua
bbv.es
mcb-bank.com
spdb.com.cn
oenb.co.at
tbanquetransatlantique.com
ceflandre.com
sogip-banque.fr
scotiabank.com
amagerbanken.dk
bvr.com.ua
ideabank.ua
citi.com
lateko.lv
cmbc.com.cn
alhilalbank.kz
stadtsparkasse-augsburg.de
anz.com
ccf.fr
icscards.nl
halykbank.kz
bankofbaroda.com
bolt.com
quickbooks.intuit.com
coopinvest.com.ua
oschadbank.ua
hsbc.ca
kredobank.com.ua
cajaespana.es
alfabank.ua
unibanka.lv
urkb.ch
bluesnap.com
emspay.nl
eubank.kz
mos.ru
creditwest.kiev.ua
bcee.lu
privatbank.ua
bancaroma.it
sparkasse-neu-ulm-illertissen.de
banc-agricol.ad
tkb.lv
nalog.ru
psbc.com
apehorse.com
todobank.ua
concord.ua
paritate.lv
hsbc.co.uk
bacob.be
sportbank.ua
bankcoop.kappa.ro
bank34.ua
adyen.com
bpb.it
hbl.lv
caixacat.es
ssc.nic.in
tascombank.ua
zhkb.ch
abnamro.com
union.cz
leu.com
cwbank.com
bocau.com
otpbank.com.ua
go.wepay.com
mynrma.com.au
cebbank.com
banxico.org.mx
firstdirect.co.uk
bradesco.com
banksa.com.au
skrill.com
mbczh.ch
bankofmelbourne.com
cash.app
homecredit.kz
barclays.com
clhs.com.ua
alipay.com
fbank.com.ua
halifax.co.uk
dgbank.de
vpbank.com
bankofshanghai.com
skb.si
cmbchina.com
ddb.dk
banksyd.com.au
sparda-hh.de
hxb.com.cn
sgz-bank.de
ubs.com
bank-girotel.de
nbcb.com.cn
bankofamerica.com
bec.ch
gcmutual.bank
defencebank.com.au
bmo.com
authorize.net
czbank.com
gon.to
santander.com
bendigobank.com.au
uk.com
dwolla.com
sarkariresult.com
lkb.lv
oxibank.ua
huginonline.no
grant.ua
arabbank.com.au
bankofbeijing.com.cn
bendigotelco.com.au
paypal.com
ecitic.com
cibc.com
bisbank.com.ua
bank-von-ernst.com
ccb.com.cn
bank.lv
pinbank.ua
bankvic.com.au
isbank.is
mhbs.co.uk
rbi.org.in
piraeus-bank.gr
kasnetbank
ap-bank.com
boc.kz
lacaixa.es
universalbank.com.ua
laurentianbank.ca
bsct.ch
bankofireland.com
a-bank.com.ua
bankvostok.com.ua
royalmail.com
ukrcapital.com.ua
balticbankinggroup.com
rbs.co.at
nab.com.au
wise.com
globusbank.com.ua
natwest.co.uk
izibank.com.ua
socgen.com
teachersbs.co.uk
vtb-bank.kz
gocardless.com
postnl.nl
deutsche-bank.de
fortisbank.lu
pravex.ua
cgd.pt
eximb.com
creditmutuel.fr
keb.co.kr
dwolla.com
kutxa.es
sebi.gov.in
braintreepayments.com
n-lb.si
ingbank.nl
procreditbank.com.ua
nationwide.co.uk
paylinedata.com
gpayments.com
credit-agricole.ua
postbank.nl
noticiasconcursos.com.br
citigroup.com
28degreescard.com.au
altbank.ua
desjardins.com
bbk.es
au.ccb.com
boqspecialist.com.au
europrombank.kiev.ua
nbg.gr
falkenbergs-sparb.se
jpbank.se
obank.com.ua
beyondbank.com
mebank.com
bilderlings.com
ubrr.com.ua
commerzbank.com
unexbank.ua
bankofengland.co.uk
industrialbank.ua
bancsabadell.es
santander.de
kz.icbc.com.cn
passbanca.it
caixagalicia.es
squareup.com
opayo.co.uk
cib.com.ua
mizuhogroup.com
country.db.com
sskba.de
banklviv.com
megabank.com.tw
nurbank.kz
ing.com
bayernlb.lu
sbil.co.uk
cgbchina.com.cn
kaspi.kz
bankfirst.com.au
credit-suisse.ch
bpel.it
crediteurope.com.ua
dofi.ibz.be
rbcroyalbank.com
ulsterbank.com
commbank.com.au
poltavabank.com
cypruspopularbank.com
rbs.co.uk
credit-suisse.com
piraeusbank.ua
cpp.pt
asviobank.ua
tsb.co.uk
bankofwales.co.uk
parliamentofindia.nic.in
cib.com.cn
bankrbk.kz
paypalobjects.com
boc.cn
unionpay.com
service-public.fr
amp.com.au
zellepay.com
purneauniversity.org
bnp.fr
boq.com.au
bankalliance.ua
handelsbanken.se
pictet.com
bnl.it
ukrgasbank.com
jpmorgan.com
bankalpari.com
mtb.ua
bankaust.com.au
bank.com.ua
americanexpress.com
fivethirtyeight.com
bkm.de
argentina.gob.ar
zamanbank.kz
osuuspankki.fi
stripe.com
paysimple.com
oeb.se
btabank.ua
pingan.com.cn
saules.com
macquarie.com.au
abchina.com
lbs-wuertt.de
rwsbank.com.ua
bankgesellschaft.de
creditdnepr.com.ua
pay.amazon.com
tinet.ch
sebgroup.com
btb.lv
esb.ee
radabank.com.ua
comdirect.de
ubib.com.ua
smc.fr
2checkout.com
bbva.com
```
```
japanpost.jp
correios.com.br
apple.com
slate.com
public.app
145.237.204.52:443
mhlw.go.jp
canada.ca
145.237.204.52
europa.eu
kemdikbud.go.id
edu
gob.mx
dpboss.net
```
## Reporting Domains That Should Be Blocked
No blocklist is ever complete, and we welcome help keeping ours current. If you are affiliated with an organisation that should be shielded from proxy traffic but does not appear to be covered, such as operators of essential or public-interest services, please contact us at [compliance@byteful.com](mailto:compliance@byteful.com) with the relevant domain, your connection to it, and why it warrants protection. We may ask you to confirm your affiliation, and we prioritise reports involving genuine safety, security, or compliance risk. We are not able to act on requests to restrict commercial websites simply because they carry valuable public data, as that falls outside the purpose this list serves.
## Impact on Proxy Usage
When attempting to access restricted domains through our proxies, you may experience:
* Connection failures
* Access denied errors
* Network timeouts
* HTTP 403 errors
## Requesting Exceptions
In certain cases, legitimate business needs may require access to specific domains that are on our restricted list. If you have a legitimate use case that requires access to a blocked domain:
1. Contact our support team at [support@byteful.com](mailto:support@byteful.com)
2. Provide details about the specific domain you need access to
3. Explain your legitimate use case
4. Our team will review your request on a case-by-case basis
Please note that exceptions are rarely granted for government, banking, and financial domains due to security and compliance requirements.
## Staying Informed
Our list of restricted domains is regularly updated to maintain security and compliance standards. For the most current information:
* Check this documentation page for general updates
* Contact [support@byteful.com](mailto:support@byteful.com) for specific inquiries
* Review our [Acceptable Usage Policy](/general/acceptable-usage-policy) for more information on our network guidelines
# Service Cancellation
Source: https://documentation.byteful.com/general/service-cancellation
Learn how to cancel or pause your Byteful subscriptions, including Datacenter, Static Residential, Mobile Data and Residential Data services.
Datacenter, Static Residential, Mobile Data and Residential Data subscriptions can be cancelled through your Byteful dashboard by going to your Subscriptions Page and clicking the three dots next to the specific service.
![Byteful Cancellation Button]()
## Cancellation
Once clicked, a pop-up will appear and it will allow you to cancel your subscription and service.
You'll be able to leave us feedback on the reason you are cancelling - we really appreciate any and all feedback as it helps us improve our services.
If you have a Datacenter or Static Residential Proxies service then your proxies will be be lost instantly after confirming the cancellation and you will not be refunded unless customer support has specifically stated prior.
If you are using residential or mobile data, cancelling a subscription and service will not effect your existing residential or mobile data. This data will remain on your account for your use in the future.
![Byteful Cancellation Options]()
## Pause rather than cancel
Residential or mobile subscriptions can be easily and indefinitely paused rather than cancelled. This allows you to maintain the same service but take a break if you don't need anymore data.
While the service is paused, all invoices will be voided and you won't be charged or credited new data until the subscription is unpaused.
Pausing is not available to Static Residential or Datacenter Proxies.
# Datacenter Proxies
Source: https://documentation.byteful.com/general/static-datacenter-proxies
Understanding datacenter proxies, their benefits, and limitations
![Byteful Datacenter Proxies]()
## What is a Datacenter Proxy?
A datacenter proxy is a type of proxy server that provides an IP address from a datacenter rather than one linked to an internet service provider (ISP). Like all proxy types, datacenter proxies:
* Hide your real IP address
* Change your digital location
* Route your traffic through an intermediary server before it reaches the internet
## Key Characteristics
Datacenter proxies are hosted in commercial datacenters and have several distinctive features:
* **High Speed**: Typically offer the fastest connection speeds among proxy types
* **Unlimited Data**: No data transfer limitations
* **Stability**: Highly reliable connections with minimal downtime
* **Cost-Effective**: Generally less expensive than residential or ISP proxies
* **Datacenter ASN**: Use IP addresses with Autonomous System Numbers (ASNs) from datacenter networks
## Benefits and Use Cases
Datacenter proxies excel in many scenarios:
* **Web Scraping**: Perfect for high-volume data collection projects
* **Market Research**: Gather competitive intelligence efficiently
* **SEO Monitoring**: Track search rankings across different locations
* **Automation**: Support bots and automated tasks with reliable connections
* **Load Testing**: Test website performance under various conditions
## Limitations
While powerful, datacenter proxies do have some limitations to consider:
* **Detection Risk**: Some websites can detect and block datacenter IPs
* **Less Legitimacy**: Don't appear as regular consumer connections
* **Geographic Precision**: Less accurate geo-targeting than residential proxies
## Unlimited Concurrency and Data
Our datacenter proxies include:
* **No Data Limits**: Transfer as much data as needed
* **Unlimited Threads**: Run multiple concurrent connections
* **No Speed Throttling**: Utilize the full connection speed
These features make datacenter proxies ideal for high-volume web scraping and other data-intensive tasks, subject only to our [Anti-Abuse Limitations & Fair Use](/general/anti-abuse-policy) policies.
## Pricing and Discounts
We offer significant discounts when you commit to longer payment cycles or purchase larger quantities:
* **Bulk Quantity Discounts**: Up to 64% off standard pricing with increased quantities
* **Payment Cycle Discounts**:
* **Quarterly Plans**: 10% discount
* **Annual Plans**: 20% discount
These discounts are applied on a sliding scale, with larger discounts for larger commitments.
## Proxy Replacements
Need to replace your datacenter proxies? Please consult our [Proxy Replacements](/general/static-proxy-replacements) policy for information about:
* How to request proxy replacements
* Replacement eligibility and limitations
* The proxy replacement process
## Getting Started
Ready to use datacenter proxies? Here's how to get started:
1. [Create an account](/general/account-registration) if you haven't already
2. Choose datacenter proxies from our product offerings
3. Select your preferred quantity and payment cycle
4. Complete your purchase
5. Access your proxies through our dashboard or API
## Related Resources
* [Acceptable Usage Policy](/general/acceptable-usage-policy)
* [Anti-Abuse Policy](/general/anti-abuse-policy)
* [Static Proxy Replacements](/general/static-proxy-replacements)
* [Listing and Exporting Proxies](/general/listing-and-exporting-proxies)
# Proxy Replacement Policy
Source: https://documentation.byteful.com/general/static-proxy-replacements
Understanding our policy for proxy replacements and how to handle replacement events
This page applies to static proxy services such as Static Residential ISP Proxies and Static Datacenter Proxies. These services are sold on a per-IP address basis and may occasionally require replacements or IP address updates.
## Our Philosophy
We are not a rapid turnover service that facilitates frequent proxy changes. Instead, we focus on providing stable, high-quality proxy services for long-term, ethical use cases. We expect our customers to use proxies responsibly and maintain them for their intended duration. This approach allows us to deliver consistent performance and build lasting partnerships with clients who value reliability over constant turnover. We expect our customers to use proxies responsibly and maintain them for their intended duration. This approach allows us to deliver consistent performance and build lasting partnerships with clients who value reliability over constant turnover.
## Standard Replacement Policy
**We do not offer in-term proxy replacements as a standard policy.** This ensures service stability and maintains the integrity of our IP allocation system.
### Exception Cases
We may consider replacement requests in limited circumstances:
* **Recent renewals**: You have just renewed your proxy service
* **New purchases**: You purchased proxies within the last four hours
### How to Request a Replacement
If you meet the exception criteria above and need to replace proxies:
1. **Email**: Contact [support@byteful.com](mailto:support@byteful.com)
2. **Dashboard**: Open a support ticket through your account dashboard
All replacement requests undergo case-by-case review. Approval is not guaranteed for requests outside our standard policy exceptions.
## Mandatory Replacements
In rare circumstances, we may need to replace proxies due to events beyond our control, including:
* **Subnet lease recalls** from upstream providers
* **Extended network disruptions** in specific geographic locations
* **Force majeure events** or other circumstances deemed necessary by Ping Technology Labs LTD
**Our commitment**: We work diligently to minimize service disruptions and maintain consistent proxy quality. Mandatory replacements are uncommon occurrences.
### What Happens During a Replacement
When we initiate a mandatory replacement:
1. **Notification**: You'll receive immediate electronic communication about the replacement
2. **Dashboard access**: View detailed replacement information via the Replacements page
3. **Service continuity**: We ensure minimal downtime during the transition process
## Managing Your Replacements
### Accessing the Replacements Dashboard
The Replacements page in your dashboard provides comprehensive tracking:
* **Complete replacement history** for your account
* **Detailed logs** showing which specific proxies were replaced
* **Replacement reasons** and status updates for each event
* **Export functionality** to download your new proxy configurations
![Byteful Replacement Dashboard]()
### Best Practices for Replacement Events
Follow these steps when a replacement occurs:
1. **Update immediately**: Integrate new proxy information into your systems as soon as possible
2. **Test thoroughly**: Verify that replacement proxies meet your performance requirements
3. **Discontinue old proxies**: Stop using replaced IP addresses, as they will no longer function
4. **Monitor performance**: Ensure new proxies maintain expected connection quality
5. **Contact support**: Reach out immediately if you experience any issues with replacement proxies
# Static Residential ISP Proxies
Source: https://documentation.byteful.com/general/static-residential-isp-proxies
Understanding Static Residential ISP Proxies, their capabilities, and advantages
![Byteful Static Residential Proxies]()
Static Residential ISP Proxies represent a powerful hybrid solution in the proxy market, combining the reliability and performance of datacenter hosting with the legitimacy of residential IP addresses.
## What Are Static Residential ISP Proxies?
Static Residential ISP Proxies are hosted in datacenters but use IP addresses announced and assigned by residential internet networks (ASNs). These IP addresses belong to Internet Service Providers (ISPs) like AT\&T, Spectrum, Comcast, BT, Deutsche Telekom, and others who provision residential broadband services to end users.
## How They Bypass Datacenter Blocks
Many websites employ filtering systems to block traffic from datacenter IPs. Here's how Static Residential ISP Proxies solve this problem:
IP addresses can be profiled by their ASN (Autonomous System Number), which allows datacenter proxies to be easily identified and blocked.
Websites that want to block datacenter traffic typically:
1. Maintain or subscribe to lists of known datacenter ASNs (like the Udger list)
2. Check the ASN of incoming connections against these lists
3. Block connections from matches on this list
Static Residential ISP Proxies circumvent this common blocking method because:
* They use IP addresses announced to residential internet networks rather than datacenter networks
* Their ASNs are not present on datacenter block lists
* They appear indistinguishable from regular internet users
* They maintain the high performance and reliability of datacenter infrastructure
## Carriers and ASNs
We work with several large carriers to provision our Static Residential ISP services, including:
* AT\&T
* Comcast
* Deutsche Telekom AG
* Glide
* Spectrum
* RCN
* Virgin Media
* Windstream
* And others
Our inventory is dynamic, and all the providers mentioned may not be available at any given time.
## Enterprise Solutions
We can offer bespoke deployments which target specific carriers for B2B clients requiring:
* Quantities over 1,000+ proxies
* Multiple month commitments
Please reach out to [support@byteful.com](mailto:support@byteful.com) for more information about enterprise solutions.
## Payment Cycle and Bulk Quantity Discounts
We offer substantial discounts of up to 56% off standard Static Residential Proxies pricing when payment cycles and quantities are increased.
Our discounting structure includes:
* Volume-based discounts on a sliding scale for larger quantities
* 10% discount for quarterly purchasing commitments
* 20% discount for annual plan commitments
For detailed pricing information, please visit our [Pricing Page](https://byteful.com/pricing).
## IP Allocation and Subnet Distribution
All our Static Residential ISP Proxies are randomly allocated from our available regional pools:
* We maintain a large number of subnets across various carriers
* Proxies are typically provisioned across multiple subnets and different carriers
* This natural distribution provides good IP diversity for most use cases
* We do not guarantee specific subnet diversity in standard packages
If you have specific requirements for IP diversity, please contact [support@byteful.com](mailto:support@byteful.com) prior to ordering.
## Proxy Replacements
For information about our replacement policies for Static Residential ISP Proxies, please consult our [Proxy Replacements](/general/static-proxy-replacements) documentation.
## Usage Limitations
Static Residential ISP Proxies offer exceptional flexibility with:
* No concurrency limits
* No data caps or metering
* Unlimited threads for high-volume operations
All proxies remain subject to our [Anti-Abuse Limitations & Fair Use](/general/anti-abuse-policy) policies.
These unlimited capabilities make Static Residential ISP Proxies perfect for high-volume web scraping on websites which require residential IP addresses while maintaining enterprise-level performance and reliability.
# Sticky vs Rotating Mobile Proxies
Source: https://documentation.byteful.com/general/sticky-vs-rotating-mobile-proxies
Understanding the differences between sticky and rotating mobile proxies and their use cases
## Sticky Mobile Proxies
Sticky proxies assign a single IP address to a user for an extended period. When you use a sticky proxy, you maintain the same mobile IP address across multiple requests, providing consistency for your online activities.
**Key features:**
* Consistent IP address for an extended duration
* Longer session persistence
* Better suited for maintaining user accounts or sessions
* More closely mimics regular user behavior
**Common use cases:**
* Accessing geo-restricted content
* Managing multiple social media accounts
* E-commerce operations requiring consistent identity
* Login-based website interactions
Sticky sessions can return the same IP address for up to 24 hours. However, since our proxies are sourced through real mobile devices, IP availability is not guaranteed and a specific IP address may occasionally become offline.
## Rotating Mobile Proxies
Rotating proxies automatically change the IP address assigned to a user after each request. This provides a new mobile IP for every connection you make.
**Key features:**
* Dynamic IP address allocation
* Shorter session duration
* Higher level of anonymity
* More difficult to track or block
**Common use cases:**
* Web scraping and data collection
* Price comparison
* Ad verification
* SEO monitoring
## Choosing Between Sticky and Rotating Proxies
| Feature | Sticky Proxies | Rotating Proxies |
| ----------------- | --------------------------------------- | ------------------------------------- |
| IP Persistence | Same IP for extended period | New IP with each request |
| Anonymity | Moderate | High |
| Session Stability | High | Low |
| Best For | Account management, consistent sessions | Data collection, avoiding rate limits |
## Generating Sticky and Rotating Proxies
You can generate both sticky and rotating proxies through our dashboard generator and syntax generation. These options give you flexibility to choose the right proxy type for your specific use case.
For detailed instructions on generating mobile proxies, visit our [Generating Mobile Proxies](/general/generating-mobile-proxies) guide.
# Sticky vs Rotating Residential Proxies
Source: https://documentation.byteful.com/general/sticky-vs-rotating-residential-proxies
Understanding the differences between sticky and rotating residential proxies and their use cases
## Sticky Residential Proxies
Sticky proxies assign a single IP address to a user for an extended period. When you use a sticky proxy, you maintain the same residential IP address across multiple requests, providing consistency for your online activities.
**Key features:**
* Consistent IP address for an extended duration
* Longer session persistence
* Better suited for maintaining user accounts or sessions
* More closely mimics regular user behavior
**Common use cases:**
* Accessing geo-restricted content
* Managing multiple social media accounts
* E-commerce operations requiring consistent identity
* Login-based website interactions
Sticky sessions can return the same IP address for up to 24 hours. However, since our proxies are sourced through real residential devices, IP availability is not guaranteed and a specific IP address may occasionally become offline.
## Rotating Residential Proxies
Rotating proxies automatically change the IP address assigned to a user after each request. This provides a new residential IP for every connection you make.
**Key features:**
* Dynamic IP address allocation
* Shorter session duration
* Higher level of anonymity
* More difficult to track or block
**Common use cases:**
* Web scraping and data collection
* Price comparison
* Ad verification
* SEO monitoring
## Choosing Between Sticky and Rotating Proxies
| Feature | Sticky Proxies | Rotating Proxies |
| ----------------- | --------------------------------------- | ------------------------------------- |
| IP Persistence | Same IP for extended period | New IP with each request |
| Anonymity | Moderate | High |
| Session Stability | High | Low |
| Best For | Account management, consistent sessions | Data collection, avoiding rate limits |
## Generating Sticky and Rotating Proxies
You can generate both sticky and rotating proxies through our dashboard generator and syntax generation. These options give you flexibility to choose the right proxy type for your specific use case.
For detailed instructions on generating residential proxies, visit our [Generating Residential Proxies](/general/generating-residential-proxies) guide.
# Store Credit
Source: https://documentation.byteful.com/general/store-credit
Learn how to add and use store credit for your Byteful account
Your Byteful account can have store credit which can be used to pay for invoices and services. Store Credit can be managed and viewed in the Billing Section of your dashboard.
![Byteful Credit Amount]()
## Adding Store Credit
Store Credit can be added to your account by clicking **+Top-up** in the Billing Section of your dashboard.
Once clicked, you'll be prompted to select the amount of store credit you'd like to add to your account, you can add between $5-$10,000 at a time. There is no maximum store credit.
Once you've entered the amount, you'll be prompted to select your payment method and once confirmed, you'll be taken off platform to complete your payment. Once the payment is received and confirmed, store credit will be automatically added to your account.
![Byteful Top Up Credit]()
## Using Store Credit
If there is Store Credit on your account, any new invoices which are generated for subscriptions or new orders will attempt to apply the store credit to the invoice at the point of generation.
If an invoice has already been generated and finalized, store credit can not be applied to it.
You can not select which invoices have store credit applied to them. Any and all new invoices will attempt to use store credit.
If an invoice has already been generated and finalized, store credit can not be applied to it.
These behaviours can not be changed as they are our billing system's (Stripe) default payment behaviour but if you run into any trouble then don't hesitate to contact [support@byteful.com](mailto:support@byteful.com) or open a ticket via the dashboard.
## Adding credit via Wire, UK BACS or ACH Payment
We can also accept ACH, Wire and UK BACs payments for purchase orders or store credit top-ups over \$1,000. Please contact [admin@byteful.com](mailto:admin@byteful.com) if you would like to make a ACH, Wire and UK BACs payment.
# Sub-Processors
Source: https://documentation.byteful.com/general/sub-processors
List of third-party sub-processors that Byteful uses to provide our services
This page provides a comprehensive list of third-party sub-processors that Byteful engages to help deliver our services. These sub-processors may process personal data on our behalf in accordance with our data processing agreements and privacy policies.
| Sub-Processor | Category | Purpose |
| -------------------------------- | ---------------------------------- | ------------------------------------------------------------- |
| Wise Payments Limited | Payments | International payment processing and currency exchange |
| Stripe, Inc. | Payments | Credit card and online payment processing |
| Revolut Ltd | Payments | Business payment processing and transactions |
| BitPay, Inc. | Payments | Cryptocurrency payment processing |
| CoinGate | Payments | Cryptocurrency payment processing |
| Idenfy | Identity Verification | KYC (Know Your Customer) identity verification and compliance |
| Slack Technologies, LLC | Customer Support & Communication | Internal team communication and customer support coordination |
| Google LLC (Gmail) | Customer Support & Communication | Email communication with customers |
| Discord, Inc. | Customer Support & Communication | Community support and customer engagement |
| Sinch Mailgun Technologies, Inc. | Customer Support & Communication | Transactional email delivery and notifications |
| Twilio Inc. | Customer Support & Communication | Communication APIs and customer messaging |
| Google LLC (Google Analytics) | Analytics | Website analytics and usage tracking |
| n8n GmbH | Integrations & Workflow Automation | Workflow automation and system integrations |
***
## Updates to This List
This sub-processor list may be updated from time to time as we engage new service providers or discontinue existing ones. We recommend checking this page periodically for any changes.
## Contact Us
If you have any questions about our sub-processors or how your data is processed, please contact us at [support@byteful.com](mailto:support@byteful.com).
# Supported Protocols
Source: https://documentation.byteful.com/general/supported-protocols
Protocol support information for Byteful services
All proxy services from Byteful support multiple protocols on the same port to ensure compatibility and ease of use with a wide range of applications.
## Protocol Support Matrix
The table below details the protocol support across our various proxy services:
| Service Type | HTTP/S | SOCKS5 TCP | SOCKS5 UDP |
| -------------------------- | ------ | ---------- | ----------- |
| Datacenter Proxies | ✅ | ✅ | ✅ |
| Static Residential Proxies | ✅ | ✅ | ✅ |
| Residential Data | ✅ | ✅ | Coming Soon |
| Mobile Data | ✅ | ✅ | Coming Soon |
## HTTP/S Support
Our proxies support the tunneling of HTTPS connections. Both HTTP and HTTPS proxy connections tunnel HTTPS connections to SSL targets via the CONNECT method. Bytes flow through the connection to the target website, encrypted and not visble for the proxy server to see. This is known as "HTTPS to the Target".
* HTTPS to the Proxy means that when talking to our server to begin proxying, information such as your target website and your authentication credentials are encrypted. To do HTTPS to the Proxy, simply set "HTTPS" as the scheme in your proxy string (see tables above for product support).
* HTTPS to the Target means that when talking to your end website, all data is encrypted and unreadable to anyone but you. This inlcudes us, we cannot see what you are doing either. To do HTTPS to the Target, simply set the scheme of your desired website to "HTTPS". However, the initial communication with the proxy server, where authentication credentials and your desired target is provided, is unencrypted.
To summarise, set the scheme of your proxy string to "HTTPS" to protect your proxy authentication credentials and set the scheme of your target website to "HTTPS" to protect the data being sent between you and the target website.
## SOCKS5 TCP Support
All of our proxy services support SOCKS5 TCP connections, providing a versatile option for applications that require this protocol. SOCKS5 offers advantages for certain use cases where HTTP proxying might be insufficient.
## Protocol Selection
When connecting to our proxies, you can choose the protocol that best fits your needs:
* Use *HTTP/S* for web browsing, data collection, and most general use cases
* Use *SOCKS5 TCP* for applications that require TCP protocol support beyond HTTP
Learn about supported protocol versions on different services. See where and how you can do HTTP/1.1, HTTP/2, HTTP/3 and SOCKS5 on our services.
Learn how to establish HTTP/1.1, HTTP/2, HTTP3 and SOCKS5 proxy connections. See how you can tunnel all traffic types, including QUIC through Byteful services.
# Two-factor Authentication (2FA)
Source: https://documentation.byteful.com/general/two-factor-authentication
Learn how to secure your account with Two-factor Authentication (2FA)
We support basic Two-factor Authentication (2FA) via email and plan to add further 2FA support in the future.
Your Two-factor Authentication (2FA) status can be managed in your Account Security section of the dashboard.
![Byteful Account Settings]()
## Enabling Two-factor Authentication (2FA)
1. Click **Turn on two-factor authentication**
2. A pop-up will appear and an email will be sent to you with a code confirming you have access to your account email address.
3. Enter the code and click **Confirm**
4. Your account is now Two-factor Authentication (2FA) protected and all logins will require a 2FA code in the future.
# Using Smartpath®
Source: https://documentation.byteful.com/general/using-smartpath
Learn about Smartpath, its benefits, and how it optimizes your residential proxy usage at Byteful
![Byteful Smartpath]()
Smartpath® is an intelligent, AI-driven proxy routing feature designed to optimize your residential proxy data usage by dynamically routing traffic through residential or datacenter IPs. Unlike traditional residential proxies that route all traffic through residential IP addresses, Smartpath intelligently decides which requests genuinely require a residential IP and routes non-essential traffic via more economical datacenter IPs.
## Why use Smartpath?
Smartpath ensures efficient use of your proxy data, significantly reducing costs without sacrificing success rates. It automatically manages proxy routing, simplifying operations, and eliminating the need for manual optimization.
## How Smartpath Optimizes Data Costs
Smartpath utilizes advanced artificial intelligence and real-time data analysis to assess each request. It instantly determines—within under 10 milliseconds—whether a residential IP is necessary, routing non-essential requests through datacenter IPs at no additional cost.
## How to use the Smartpath Beta
Enabling Smartpath can be done with a single click of a button. Simply head over to our [residential proxy generator on the dashboard](https://dashboard.byteful.com/residential) and click Enable in the Smartpath settings area. All proxies generated with this configuration will be assessed by Smartpath and optimized where possible.
![Byteful Smartpath Generator Settings]()
You can also create Smartpath enabled proxy lists via the API by passing in the list\_smartpath\_enabled parameter with a value of `True`.
## When to use Smartpath and when to avoid it?
Smartpath is designed to work across a wide range of targets and use-cases, however, when utilizing AI and applying a solution across hundreds of millions of websites across the internet, there is always the chance of false positives.
You should exercise caution when when using Smartpath in workloads involving ad verification, compliance critical workloads, and on targets which have extremely sensitive fingerprinting.
If you are experiencing poor performance or elevated false positive rates when using Smartpath, don't hesitate to contact our customer support team at [support@byteful.com](mailto:support@byteful.com) so we can investigate.
Smartpath requests which are classified as not requiring a residential IP address do not respect sticky IP address session parameters as they're routed through a different datacenter IP address. All requests that are classified as requiring a residential IP address will be routed through the same sticky IP address in the session.
## Measuring the success of Smartpath
We've integrated Smartpath metrics across our suite of observability tools so you track track exactly what requests were optimized by Smartpath and assess your cost savings over any period. You can filter these analytics by proxy user and domain so you can understand which workloads Smartpath works best for.
![Byteful Smartpath Analytics]()
# Using Smartpath®
Source: https://documentation.byteful.com/general/using-smartpath-mobile
Learn about Smartpath, its benefits, and how it optimizes your mobile proxy usage at Byteful
![Byteful Smartpath]()
Smartpath® is an intelligent, AI-driven proxy routing feature designed to optimize your mobile proxy data usage by dynamically routing traffic through mobile or datacenter IPs. Unlike traditional mobile proxies that route all traffic through mobile IP addresses, Smartpath intelligently decides which requests genuinely require a mobile IP and routes non-essential traffic via more economical datacenter IPs.
## Why use Smartpath?
Smartpath ensures efficient use of your proxy data, significantly reducing costs without sacrificing success rates. It automatically manages proxy routing, simplifying operations, and eliminating the need for manual optimization.
## How Smartpath Optimizes Data Costs
Smartpath utilizes advanced artificial intelligence and real-time data analysis to assess each request. It instantly determines—within under 10 milliseconds—whether a mobile IP is necessary, routing non-essential requests through datacenter IPs at no additional cost.
## How to use the Smartpath Beta
Enabling Smartpath can be done with a single click of a button. Simply head over to our [mobile proxy generator on the dashboard](https://dashboard.byteful.com/mobile) and click Enable in the Smartpath settings area. All proxies generated with this configuration will be assessed by Smartpath and optimized where possible.
![Byteful Smartpath Generator Settings]()
You can also create Smartpath enabled proxy lists via the API by passing in the list\_smartpath\_enabled parameter with a value of `True`.
## When to use Smartpath and when to avoid it?
Smartpath is designed to work across a wide range of targets and use-cases, however, when utilizing AI and applying a solution across hundreds of millions of websites across the internet, there is always the chance of false positives.
You should exercise caution when when using Smartpath in workloads involving ad verification, compliance critical workloads, and on targets which have extremely sensitive fingerprinting.
If you are experiencing poor performance or elevated false positive rates when using Smartpath, don't hesitate to contact our customer support team at [support@byteful.com](mailto:support@byteful.com) so we can investigate.
Smartpath requests which are classified as not requiring a mobile IP address do not respect sticky IP address session parameters as they're routed through a different datacenter IP address. All requests that are classified as requiring a mobile IP address will be routed through the same sticky IP address in the session.
## Measuring the success of Smartpath
We've integrated Smartpath metrics across our suite of observability tools so you track track exactly what requests were optimized by Smartpath and assess your cost savings over any period. You can filter these analytics by proxy user and domain so you can understand which workloads Smartpath works best for.
![Byteful Smartpath Analytics]()
# What is a Proxy?
Source: https://documentation.byteful.com/general/what-is-a-proxy
A beginner-friendly guide to understanding proxies, how they work, and their most common use cases
## Understanding Proxies
A **proxy server** acts as an intermediary between your device and the internet. When you use a proxy, your internet traffic is routed through the proxy server before reaching its final destination. This means websites and online services see the proxy's IP address instead of your own.
Think of a proxy like a postal forwarding service: instead of sending mail directly from your home address, you send it through a forwarding service that uses their address. The recipient sees the forwarding service's address, not yours.
## Popular Use Cases
### Web Scraping & Data Collection
Proxies are essential for businesses that need to collect large amounts of web data. They allow you to:
* Gather market research and competitive intelligence
* Monitor prices across e-commerce platforms
* Collect real estate listings and property data
* Aggregate news articles and social media content
Learn more: [What is a Residential Proxy?](https://byteful.com/blog/what-is-a-residential-proxy)
### Online Automation
Proxies enable businesses to automate various online tasks efficiently:
* Automate social media posting and engagement
* Monitor competitor activities and pricing changes
* Perform automated testing of websites and applications
* Execute large-scale marketing and outreach campaigns
Discover proxy types commonly used in automation:
* [What Are Datacenter Proxies?](https://byteful.com/blog/what-are-datacenter-proxies)
* [What Are ISP Proxies?](https://byteful.com/blog/what-are-isp-proxies)
There are many other use cases for proxies, including privacy enhancement, geo-location testing, ad verification, SEO monitoring, and more.
## Learn More
Proxies can get quite complicated, as there are many different types available—residential, mobile, datacenter, static, rotating, and others—each with their own specific advantages and ideal use cases.
To better understand the different types of proxies and their applications, explore these helpful resources:
Understand how residential proxies work and their ideal use cases for scraping and automation.
Explore the benefits and limitations of fast, cost-effective datacenter proxies.
Learn how ISP proxies offer the stability of datacenter IPs with the trust of residential ranges.
Understand the key differences between proxies and VPNs and when to use each one.
Compare IPv4 and IPv6 proxy formats and how each impacts compatibility and scalability.
Learn about the legality of using residential proxies and how to remain compliant.
Find out the pros and cons of different proxy session types for various use cases.
Troubleshoot frequent proxy-related errors and how to resolve them quickly.
Have additional questions about proxies or need help choosing the right solution for your specific needs? Contact our support team at [support@byteful.com](mailto:support@byteful.com) for personalized assistance.
# Introduction
Source: https://documentation.byteful.com/introduction
Your comprehensive guide to Byteful services, tools, and resources
![Byteful]()
# Welcome to Byteful
Welcome to the Byteful knowledge base! Here you will find everything you need to know to start using our proxies, tools, website, and dashboard.
## Getting Started
Get up and running with Byteful in minutes:
Create your Byteful account to access our services
Learn how to purchase and set up your first proxies
## Essential Resources
Learn about different proxy authentication methods
Create and manage proxy users for access control
HTTP, HTTPS, SOCKS5 and other supported protocols
Integrate Byteful with your applications
## Need Help?
If you can't find something you need in this knowledge base, our support team is here to help.
Email our support team for assistance
Our main support hours are Europe Daytime, specifically weekdays between 5AM to 7PM EST but have 24/7 support available with slower response times. We currently only provide support in English.
# Need Help?
Source: https://documentation.byteful.com/need-help
If you can not find something you need in this knowledge base, our support team is here to help.
If you can't find something you need in this knowledge base, our support team is here to help. We provide support via Email, Ticket System, Discord and Telegram.
We also provide dedicated Slack channels for start-up, scale-up and enterprise customers.
Email our support team for assistance
Our main support hours are Europe Daytime, specifically weekdays between 5AM to 7PM EST but have 24/7 support available with slower response times. We currently only provide support in English.
# Product Update Log
Source: https://documentation.byteful.com/product-updates
What we've changed and added to Byteful. A straightforward timeline of our improvements.
## Introducing OS Targeting Beta for Residential and Mobile Proxies
![OS Targeting on Residential and Mobile Proxies]()
You can now specify the operating system your proxy node should be running, for both Residential and Mobile proxies. If websites you are visiting use fingerprinting techniques to determine the OS of the client connecting (and many do!), you can now rest assured that your OS will align with your intent.
If you are running automated systems that rely on the existing API endpoints that allow for current active node counts with our Residential and Mobile proxies, then you will be pleased to know that you can also filter by the OS! As with geolocation adjusted counts, the available proxy node counts for the OS can be found in your Byteful dashboard in addition to the API.
[Read More →](https://byteful.com/blog/introducing-os-targeting)
## Byteful Becomes EWDCI Certified
![EWDCI Certified]()
We've earned the EWDCI Trust Seal, the certification awarded by the Ethical Web Data Collection Initiative to web data companies that meet its standards for legality, ethics, ecosystem engagement, and social responsibility.
Getting the seal meant an independent review of how we actually operate against the EWDCI Core Principles, covering transparency, data handling, privacy safeguards, and accountability. It builds on our Internet Watch Foundation membership, Made in Britain certification, and the compliance policies we continue to tighten—adding external verification on top of commitments we'd already made.
[Read More →](https://byteful.com/blog/byteful-becomes-ewdci-certified)
## Improved Checkout & Reconfiguration For Per-IP Products
![Better Checkout]()
Our checkout & reconfiguration flow for our ISP and Datacenter products has been greatly improved. Multiple proxy locations can now be bought in a single transaction, making it faster to get the proxies you need as well as making it easier to hit the bulk discount thresholds.
## Improved Proxy Observability and Debugging
![Better Error Codes]()
Error codes returned by our proxies have been overhauled to be both more fine-grained *and* easier to understand. You can find the meanings of these codes in by hovering over any code you see within the network observability portion of our dashboard or by reading our documentation [here](https://documentation.byteful.com/general/debugging-and-error-codes#byteful-customer-error-reference).
Addittionally, our proxies now return headers that allow for better correlating requests in your client to what you see in the dashboard. We provide you the request ID and the Byteful error code in the `x-byteful-request-id` and `x-byteful-status-code` headers respectively.
## Mobile Proxies Proxy Count Update
![Mobile Proxies Node Count]()
Both the dashboard and API now surface live node counts for your mobile proxy parameter selections. As you refine targeting by country, region, city, carrier, or any combination, you'll see exactly how many nodes match your criteria—making it easier to gauge pool size before you generate credentials and to fine-tune selections that are too narrow or broader than needed.
## Introducing Mobile Proxies
![Mobile Proxies]()
We've launched our mobile proxy network—over 6 million monthly IPs spanning 650+ mobile carriers, 1,500+ cities, and 190+ countries. We're extending the same pro-consumer model from our residential product to mobile traffic, including non-expiring data, making us the first major mobile proxy provider to offer data that does not expire.
Carrier Grade NAT (CGNAT) protection makes this network particularly effective against the hardest websites to access—mobile IPs are shared by many real users behind CGNAT, so target sites cannot block these addresses without also cutting off other users. For sites that aggressively ban residential or datacenter proxies, mobile is often the only option that consistently works.
[Read More →](https://byteful.com/blog/mobile-proxies-launch)
### Key Features
* **6M+ monthly IPs across 650+ carriers** for broad targeting flexibility and expansive global reach
* **1,500+ cities in 190+ countries** with city-level reach across every major market
* **Carrier Grade NAT protection** makes target-side bans impractical and extends the useful lifespan of each address
* **Sub-600ms average speeds** for latency-sensitive workflows that previously required residential
* **Non-expiring data**—the bandwidth you buy stays yours until you use it
* **Dashboard and API access** with full feature parity for easy integration into your own systems
## Network Observability Changes
We have began to collate certain hostnames based on how many unique hostnames there are for a given domain. This will primarily effect hostnames that contain unique elements, for example a UUID.
Hostnames with a high cardinality will now display in 1 of 3 formats: hostname.TLD, [www.hostname.TLD](http://www.hostname.TLD) or \*.hostname.TLD
### Key Changes
* **Understand Your Usage** Previously, certain hostnames that would change showed as seperate entries making it hard to track usage. The new system makes this much clearer
* **Dashboard Performance** Customers with a large number of requests may begin to see speed-ups as we collate more and more hostnames
## Dashboard Overhaul
![Byteful Dashboard Overhaul]()
We've completely rebuilt the Byteful dashboard. Born from five years of daily usage, around 10,000 hours inside the product, and over 6,000 support tickets in the last year alone—this overhaul addresses the core issue with our previous dashboard: it was intuitive, but only if you were already familiar with it.
[Read the Full Story →](https://byteful.com/blog/10000-hours-in-the-dashboard)
### Key Changes
* **New design system** with a distinct visual identity for every data type—IPs, UUIDs, metrics, and metadata are immediately recognizable at a glance
* **Consistent tables** with unified filtering, sorting, pagination, and column selection across the entire platform
* **Fixed-width central viewport** for a more focused, readable layout with less eye movement
* **Product-first structure** where each service has its own space showing usage, allocation, and implementation up front
* **Unified IAM layer** with Proxy Users now clearly managing team members, applications, and agents across the whole platform
* **Contextual code examples** built from your actual account configuration—copy and use immediately, no placeholder filling
* **Real-time API analytics** with table and graph views for live debugging without jumping between tools
* **Persistent table preferences** that carry across sessions, with an easy reset option
## Ping Proxies is Now Byteful
![Byteful Rebrand]()
We've rebranded from Ping Proxies to Byteful, marking our commitment to building the leading ethical proxy infrastructure for web scraping, large-scale data collection, and agentic AI. What started as a bootstrapped side project at the University of Leeds has grown into a platform trusted by more than 1,500 active customers processing over 20 billion requests monthly.
The name reflects the scale of what we've built—last year alone, more than thirty-one quadrillion bytes flowed through our network.
[Read the Full Story →](https://byteful.com/blog/ping-proxies-is-now-byteful)
### What's Changed
* **New domain** at byteful.com with all applications unified under the Byteful brand
* **Redesigned platform** with improved proxy analytics, network observability, and enterprise team access features
* **Existing infrastructure** remains accessible via residential.pingproxies.com and api.pingproxies.com during the transition
* **No disruption** for existing customers—everything continues to work as before
### What's Next
* **Extended API-first proxy management** and developer tooling for AI companies
* **TCP/IP fingerprinting** technologies for more advanced proxy management
* **Infrastructure designed for agentic AI** workflows at scale
* **New carrier partnerships**, additional product lines, and a startup program launching later this year
## IPv6 Website Compatibility Checker
We've released a free tool that lets you instantly check whether any website supports IPv6 connections. Simply enter a URL and get immediate results showing IPv6 compatibility status, resolved addresses, and connection details.
This tool addresses a common pain point—manually testing IPv6 support is tedious and time-consuming. Whether you're planning IPv6 proxy deployments, auditing target sites, or troubleshooting connectivity issues, this checker gives you the answers in seconds.
[Try the IPv6 Compatibility Checker →](https://byteful.com/ipv6-website-compatibility-checker)
### Key Features
* **Instant compatibility detection** for any website URL
* **DNS resolution details** showing AAAA records and IPv6 addresses
* **Connection testing** to verify actual IPv6 reachability
* **No account required**—completely free to use
## Proxy Formatter Tool
We've launched a utility that converts proxy lists between different formats with a single click. Paste your proxies in any common format and instantly export them in the format your tools require.
Reformatting proxy lists manually is repetitive work that eats into productive time. This tool handles the conversion automatically, supporting formats like `ip:port:user:pass`, `user:pass@ip:port`, URL-encoded strings, and more.
[Try the Proxy Formatter →](https://byteful.com/proxy-formatter)
### Key Features
* **Multi-format support** for all common proxy string formats
* **Batch conversion** for processing entire proxy lists at once
* **Protocol prefixes** with optional HTTP/HTTPS/SOCKS5 formatting
* **One-click copy** to clipboard for immediate use
## Proxy List Options & Proxy User ID Search
We've added new proxy list options and the ability to search proxies by proxy user ID to the API, giving you more flexibility when managing and filtering your proxy inventory.
### Key Features
* **Proxy list options** for more flexible proxy listing configurations
* **Search by proxy user ID** to quickly find proxies assigned to specific users
## Proxy User ACL Rules
We've introduced Proxy User Access Control Lists (ACLs), giving you fine-grained control over which proxies each proxy user can access. This feature enables precise permission management for teams, projects, AI agents, or customers operating on your account.
Previously, proxy users had broad access across your account. With ACL rules, you can now restrict users to specific services or individual proxies, ensuring your setup aligns with operational, security, and compliance requirements.
[Read the Access Control Guide →](/api-explainers/proxy-user-access-control)
### Key Features
* **Service-restricted access** limits users to specific proxy services
* **Proxy-restricted access** limits users to individual proxies you choose
* **Flexible rule creation** through the dashboard or [API](/api-objects/proxy-user-acl)
* **Built-in proxy filtering** to easily select which resources to grant
* **Available to all users** at no additional cost
## Enhanced Proxy Error Reporting
We've shipped a major upgrade to our Online Proxy Tester with clearer diagnostics, improved error interpretation, and global testing capabilities. This update helps you identify and resolve proxy issues faster with complete visibility into connection behavior.
The tool now shows exactly where failures occur in the request chain, explains why they happen in plain language, and suggests how to fix them. Over 115 error types have been rewritten into human-readable explanations with actionable hints.
[Try the Proxy Tester →](https://byteful.com/proxy-tester)
### Key Features
* **Connection trace visualization** showing the full Client → Proxy Server → Target Server path
* **Human-readable error explanations** for 115+ error types
* **Hint solutions** for authentication, upstream, and network-related issues
* **Multi-region testing** to detect geo-specific failures and routing inconsistencies
* **API support** for automated testing and global error reporting
* **Shareable results** with expanded technical metadata
## Proxy Testing Capability
![Proxy Testing Capability]()
We’ve introduced a multi-region proxy testing to our API that allows you to test your proxies from multiple vantage points. This way, you gain a clear understanding of real-world latency and reliability, ensuring that your users experience consistently high performance, no matter where they are located.
[Read More →](https://byteful.com/blog/launching-our-proxy-tester-public-api)
### Key Features
* **Tesitng across multiple regions** allows realistic world-wide measurement
* **Latency testing** enables performance analysis of your proxies
* **Test against any website** to validate real-world scenarios
* **Accurate geolocation data** for geographic understanding of your proxies
* **Instant data retrieval** so you can test quickly and reliably
## Session TTL (Time To Live) Support
![Session TTL]()
We've added Session TTL functionality to provide greater control over IP address persistence. You can now specify how long to maintain the same IP address by adding TTL parameters to your proxy username, with support for minutes, hours, or days.
## HTTP2/HTTP3 Support on Residential Network Beta
![HTTP2/HTTP3 Support]()
HTTP2 and HTTP3 protocol support is now available on the residential network beta. This provides improved performance and connection efficiency for supported clients.
* Access the beta at: `https://beta.residential.byteful.com`
* Expected to ship to production within the next month.
## HTTPS Launch on Residential Network Beta
![HTTPS Launch]()
HTTPS support is now live on the residential network beta, providing enhanced security and encrypted connections.
* Access the beta at: `https://beta.residential.byteful.com`
* Expected to ship to production within the next month.
## Live Pool Indicators and Advanced Geographic Targeting
We’ve introduced real-time pool size indicators and advanced geo-targeting to give users greater transparency and control. This update supports our commitment to network visibility, responsible usage, and more precise, data-driven decision-making.
[Read More →](https://byteful.com/blog/new-residential-targeting-options)
### Key Features
* **Live pool size indicators** show real-time IP availability for selected parameters
* **U.S. state-level targeting** allows precise geographic control across all 50 states
* **ZIP code targeting** enables hyper-local traffic routing for granular use cases
* **Node counts per configuration** let you validate availability before sending requests
* **Dashboard and API access** gives full control via UI or integration
## Improved Automated KYC Procedure
![Byteful KYC]()
We've partnered with [Idenfy](https://www.idenfy.com/) to launch improved automated KYC procedures. We are committed to maintaining the highest ethical standards and ensuring our services are used responsibly. We have implemented a risk-based approach to customer verification that helps us maintain a secure and compliant network environment.
[Read More →](/general/kyc-policy)
## Smartpath® Launch
We've launched **Smartpath®**—an AI-powered residential proxy optimization system that intelligently cuts data costs by 40%. The system uses artificial intelligence to automatically determine whether each request genuinely requires a residential IP, routing non-essential requests through datacenter IPs at no charge while maintaining full performance.
[Read More →](https://byteful.com/blog/introducing-smartpath-ai-proxy)
### Key Features
* **AI-powered optimization** that reduces data costs by up to 40%
* **Zero setup required**—enable with a single click or API parameter
* **Intelligent request routing** through datacenter IPs for non-essential traffic
* **Continuous learning** from hundreds of millions of network requests daily
## Live Network Activity
![Live Network Activity]()
We've launched Live Network Activity—a real-time debugging interface.
The dashboard provides real-time detailed breakdowns of every request including elapsed time, byte counts, status codes, target hostnames, and user-friendly error messages.
[Read More ->](https://byteful.com/blog/live-proxy-traffic-launch)
**Key Features**
* Monitor requests in real-time with automatic updates
* View detailed metrics for each proxy connection
* Filter by network, proxy IP, target domain, response codes and more!
* Get clear explanations of status codes and error conditions
## Residential Network Improvements in US East
![Residential Network Improvements in US East]()
We've deployed major infrastructure upgrades to our US East Coast network, achieving a 61% latency reduction and 4X capacity increase to better serve the 40% of residential traffic originating from this critical region.
[Read More →](https://byteful.com/blog/residential-network-improvements-us-east)
**Key Improvements**
* 61% additional latency reduction (75% total improvement from baseline)
* 4X server capacity expansion in the region
* New Points of Presence (PoPs) added to bare-metal infrastructure
* Enhanced failover and redundancy capabilities
* Improved performance stability during peak usage periods
* Increased reliability for high-volume traffic handling
## Network Observability Panel
![Byteful Network Observability]()
Our new Network Observability Panel tracks your proxy usage by hostname, proxy user and network while offering flexible filtering and visualization options.
![Byteful Network Observability Panel]()
[Read More →](https://byteful.com/blog/network-observability-panel)
**Key Features**
* Filter activity by hostname, proxy user, and network for any time period
* Apply advanced filtering with operators like != and contains
* View error rates, request counts, and data usage summaries
* Analyze top 100 hostnames with detailed traffic statistics
* Monitor top 100 proxy users with performance metrics
* Examine traffic distribution across different networks
* Track usage patterns with daily traffic graphs
* Access hourly log summaries organized by proxy user, network, and hostname
![Byteful Network Filtering]()
## Residential Generator Improvements
We're excited to announce improvements to our residential endpoint generator on our dashboard.
**Key Improvements**
* Added format generation including socks5h
* Improved searching for city, country and ASN targeting options
* Availability labels have been added for city, country and ASN targeting options to allow customers to see whether nodes are available for particular options.
![Byteful Residential Endpoint Generator]()
## Dashboard API Panel Launch
**API Key Manager**
![API Key Management Interface]()
Create and manage API keys directly from your dashboard with just a few clicks:
* Label keys for easy tracking
* View creation dates
* Delete keys when no longer needed
* Create multiple keys for different applications or team members
**API Analytics**
![API Analytics Graph]()
Monitor your API usage with our new analytics dashboard:
* Track all API calls including endpoints, response codes, and timestamps
* View request volume over time
* Access complete details for every API call
* Easily monitor performance and troubleshoot integration issues
## Byteful REST API Launch
We're excited to announce the general availability of our fully-featured Byteful REST API, enabling programmatic access to our platform and proxy networks.
**Major capabilities**
* Comprehensive proxy search with filtering by country, ASN, subnet, and more
* Residential proxy generation (sticky or rotating) tied to any proxy user
* Complete proxy user management (create, edit, delete, rotate passwords)
* Real-time analytics for detailed traffic usage across all networks
* Object metadata for attaching key-value pairs to resources
* Programmatic purchasing with complete checkout flow
* Powerful search operators for precise resource queries
**API management features**
* Simple API key creation and management from your dashboard
* Detailed request logs and usage statistics
* Multi-language support (Python, JavaScript/TypeScript, PHP, Go, Java)
* Developer-friendly documentation with OpenAPI specification
* Try It buttons for testing against sandbox environment
* Structured error definitions and request IDs for easy troubleshooting
![Byteful API Release]()