---
title: "Proxy API Reference: Usage, Proxy Lists & SERP | Proxonym"
description: "REST API reference for Proxonym: API keys, rate limits, errors, and endpoints for account, usage, proxy lists, IP whitelist, sub-users and the SERP API."
url: https://proxonym.com/docs/api
updated: 2026-10-01T21:31:28+00:00
---

# Proxonym API reference

Manage balances, usage, proxy lists, the IP whitelist and sub-users over a JSON REST API, and fetch parsed Google results with the SERP API.

- Base URL `https://api.proxonym.com/v1`
- Auth `Authorization: Bearer API_KEY`
- Format `JSON`
- Rate limit `60 / min`

### Contents

API at a glance

- **Base URL**: `api.proxonym.com/v1`
- **Auth**: `Bearer API_KEY`
- **Format**: `JSON`
- **Rate limit**: `60 / min`

Endpoints

- [`GET` /account](https://proxonym.com/docs/api#account)
- [`GET` /usage](https://proxonym.com/docs/api#usage)
- [`GET` /proxies/{product}](https://proxonym.com/docs/api#proxy-lists)
- [`GET POST DEL` /whitelist](https://proxonym.com/docs/api#whitelist)
- [`GET POST PATCH DEL` /sub-users](https://proxonym.com/docs/api#sub-users)
- [`GET` serp…/v1/search](https://proxonym.com/docs/api#serp-api)

**Stuck?** The help center covers billing, errors and account questions.

[Help center](https://proxonym.com/help) [Test a proxy](https://proxonym.com/proxy-checker)

## Overview

The Proxonym API lets you manage your account from code: read balances and plans, pull usage, download proxy lists, edit the IP whitelist and manage sub-users. The Google SERP API, on its own host, returns parsed search results as JSON.

### Base URL

**Text**

```text
https://api.proxonym.com/v1
```

Paths in this reference are relative to the base URL. All requests use HTTPS. The SERP API has its own base URL, `https://serp.proxonym.com/v1`.

### OpenAPI description

The account API is also described in OpenAPI 3.1 at [/docs/api/openapi.json](https://proxonym.com/docs/api/openapi.json), ready for client generators, API tools and AI agents.

### Versioning

The major version is part of the path. Breaking changes ship under a new version. Within `v1`, new endpoints, optional parameters and response fields can appear, so write clients that ignore fields they don't recognize.

### Conventions

- **Format:** responses are JSON in UTF-8 with `Content-Type: application/json`, except proxy lists requested with `format=txt`. Send request bodies as JSON with `Content-Type: application/json`.
- **Status codes:** `200` on success and `201` when a resource is created. Failures are described in [Errors](https://proxonym.com/docs/api#errors).
- **Timestamps:** ISO 8601 in UTC, for example `2026-10-01T09:30:00Z`. Date parameters accept a full timestamp or a date such as `2026-09-24`, read as midnight UTC.
- **Traffic:** gigabytes as decimal numbers, for example `17.836`.
- **IDs:** strings with a type prefix, such as `su_3k9x2m7q` for a sub-user. Treat them as opaque.
- **Missing values:** `null`, for example `"expires_at": null` on a pack that never expires.
- **Products:** `residential`, `mobile`, `unlimited`, `isp`, `datacenter`, `dedicated` and `serp`.

### Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `GET` | [`/account`](https://proxonym.com/docs/api#account-get) | Account, GB balances and active plans |
| `GET` | [`/usage`](https://proxonym.com/docs/api#usage-get) | Usage of one product over time |
| `GET` | [`/proxies/{product}`](https://proxonym.com/docs/api#proxy-lists-get) | Proxy list for datacenter, ISP or dedicated |
| `GET` | [`/whitelist`](https://proxonym.com/docs/api#whitelist-list) | List whitelisted IPs |
| `POST` | [`/whitelist`](https://proxonym.com/docs/api#whitelist-add) | Add an IP to the whitelist |
| `DELETE` | [`/whitelist/{ip}`](https://proxonym.com/docs/api#whitelist-remove) | Remove an IP from the whitelist |
| `GET` | [`/sub-users`](https://proxonym.com/docs/api#sub-users-list) | List sub-users |
| `POST` | [`/sub-users`](https://proxonym.com/docs/api#sub-users-create) | Create a sub-user |
| `PATCH` | [`/sub-users/{id}`](https://proxonym.com/docs/api#sub-users-update) | Update a sub-user |
| `DELETE` | [`/sub-users/{id}`](https://proxonym.com/docs/api#sub-users-delete) | Delete a sub-user |
| `GET` | [`https://serp.proxonym.com/v1/search`](https://proxonym.com/docs/api#serp-api-search) | Google results as parsed JSON |

### Your first call

Create an API key in the dashboard, export it, then request your account:

**Shell**

```bash
export PROXONYM_API_KEY="your_api_key"

curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

Examples in this reference read the account API key from `$PROXONYM_API_KEY` and the SERP API key from `$PROXONYM_SERP_KEY`.

## Authentication

The account API authenticates every request with an API key, sent as a bearer token in the `Authorization` header:

**Text**

```text
Authorization: Bearer <API_KEY>
```

Create and revoke keys in the dashboard. A key acts on your whole account: it can read usage, download proxy credentials and manage sub-users. A request with a missing, malformed or revoked key fails with `401`:

**Shell**

```bash
curl -i https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer wrong_key"
```

**Text**

```text
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed or revoked."
  }
}
```

### Keep keys secret

- Call the API from your servers only. Never ship a key in a web page, a mobile app or a public repository.
- Load keys from environment variables or a secrets manager, and keep them out of logs.
- Use a separate key for each service, so you can revoke one without touching the others.
- API keys aren't proxy credentials. Proxy connections use your proxy username and password; see [proxy authentication](https://proxonym.com/docs#authentication).

### Rotate keys

1. Create a new key in the dashboard.
2. Deploy it to every service that calls the API.
3. Confirm that calls succeed with the new key, then revoke the old one.

Rotate on a schedule, and revoke a key at once if it may have leaked. Requests with a revoked key fail with `401`.

### SERP API key

The SERP API reads its key from the `X-API-Key` header instead of `Authorization`. See [SERP API](https://proxonym.com/docs/api#serp-api).

## Rate limits

The account API accepts 60 requests per minute. Every response tells you where you stand:

| Header | Description |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed per minute: `60` |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `Retry-After` | On `429` responses only: seconds to wait before the next request |

Over the limit, the API answers `429`:

**Text**

```text
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 18

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 60 requests per minute exceeded. Retry after 18 seconds."
  }
}
```

SERP API usage is metered by your plan's monthly requests instead; see [SERP API](https://proxonym.com/docs/api#serp-api).

### Handling 429

Wait the number of seconds in `Retry-After`, then retry. To stay under the limit:

- Cache data that changes slowly, such as proxy lists and the whitelist.
- Poll usage every few minutes, not every few seconds. The finest granularity is one hour.
- Spread batch jobs, such as creating many sub-users, over several minutes.

**Python**

```python
import os
import time

import requests

API = "https://api.proxonym.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"}

def api_get(path, params=None, attempts=5):
    for _ in range(attempts):
        r = requests.get(API + path, headers=HEADERS, params=params, timeout=30)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        time.sleep(int(r.headers.get("Retry-After", "5")))
    raise RuntimeError(f"{path}: still rate limited after {attempts} attempts")

print(api_get("/usage", {"product": "residential", "granularity": "day"}))
```

## Errors

Errors use standard HTTP status codes and a JSON body with a stable, machine-readable `code` and a human-readable `message`:

**JSON**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed or revoked."
  }
}
```

Branch on `code`, never on `message`: messages can be reworded, codes stay stable.

| Status | Code | Meaning | What to do |
| --- | --- | --- | --- |
| `400` | `invalid_request` | The request is malformed: invalid JSON, a missing required parameter, or a value of the wrong type | Fix the request. Retrying won't help |
| `401` | `invalid_api_key` | The API key is missing, malformed or revoked | Check the header and the key |
| `403` | `product_not_active`, `quota_exceeded` | The key is valid, but the product has no active plan, or the SERP plan has no requests left | Buy or renew the plan |
| `404` | `not_found` | The path, product, sub-user ID or whitelisted IP doesn't exist | Check the path and the ID |
| `409` | `already_exists` | The IP is already whitelisted, or another sub-user has that name | Use the existing resource or choose another value |
| `422` | `validation_failed`, `whitelist_full` | A value is well formed but not accepted, such as an invalid IP, an unknown product or a date range that is too long, or every whitelist slot is taken | Correct the value, or remove an IP from the whitelist first |
| `429` | `rate_limited` | More than 60 requests in a minute | Wait `Retry-After` seconds, then retry |
| `500` | `internal_error` | An unexpected error on our side | Retry with exponential backoff |

Only `429` and `500` are worth retrying unchanged. If a `500` persists, note the endpoint, the time of the request and the full error body: on a dedicated datacenter plan, send them to our team in a ticket.

## Account

Read your account details, GB balances and active plans.

### Get the account

`GET /account`

Returns the account, its GB balances and every active plan. Expired plans aren't included.

#### Parameters

None.

#### Example request

**Shell**

```bash
curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### Example response

**JSON**

```json
{
  "id": "acc_7d3f9k2m",
  "email": "you@company.example",
  "created_at": "2026-03-14T08:21:47Z",
  "credit_usd": 245.5,
  "balances": {
    "residential": {
      "gb_remaining": 37.836,
      "expires_at": "2026-10-12T14:03:51Z",
      "packs": [
        {
          "gb_purchased": 40,
          "gb_remaining": 17.836,
          "purchased_at": "2026-09-12T14:03:51Z",
          "expires_at": "2026-10-12T14:03:51Z"
        },
        {
          "gb_purchased": 20,
          "gb_remaining": 20.0,
          "purchased_at": "2026-08-02T16:40:55Z",
          "expires_at": null
        }
      ]
    },
    "datacenter": {
      "gb_remaining": 687.52,
      "expires_at": "2026-10-18T09:12:40Z"
    }
  },
  "plans": [
    {
      "id": "pl_4k8d2pqm",
      "product": "unlimited",
      "bandwidth_mbps": 200,
      "gateway": "use.unl.proxonym.com",
      "udp": false,
      "started_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-10-02T10:00:00Z"
    },
    {
      "id": "pl_3n7q1wza",
      "product": "datacenter",
      "ips": 1000,
      "bandwidth_gb": 1000,
      "started_at": "2026-09-18T09:12:40Z",
      "expires_at": "2026-10-18T09:12:40Z"
    },
    {
      "id": "pl_6t2r9exb",
      "product": "isp",
      "ips": 20,
      "started_at": "2026-09-20T15:30:00Z",
      "expires_at": "2026-10-20T15:30:00Z"
    },
    {
      "id": "pl_2h5j8kvc",
      "product": "serp",
      "requests_limit": 100000,
      "requests_used": 41827,
      "started_at": "2026-09-08T11:45:19Z",
      "expires_at": "2026-10-08T11:45:19Z"
    }
  ]
}
```

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Account ID |
| `email` | string | Account email address |
| `created_at` | string | When the account was created |
| `credit_usd` | number | Account balance in US dollars, available to buy plans. Top-ups and bonus credit add to it |
| `balances` | object | GB balances keyed by product: `residential`, which mobile shares, and `datacenter`, the monthly bandwidth allowance. Products without a balance are left out |
| `balances.{product}.gb_remaining` | number or null | GB left. `null` on the Unlimited datacenter tier |
| `balances.{product}.expires_at` | string or null | Earliest expiry of the traffic in this balance. `null` if none of it expires |
| `balances.residential.packs[]` | array | One entry per GB pack with traffic left: `gb_purchased`, `gb_remaining`, `purchased_at` and `expires_at`, which is `null` for packs with no expiry |
| `plans[]` | array | Active plans. Every plan has `id`, `product`, `status` (`active`, or `provisioning` while static IPs are being prepared), `started_at` and `expires_at` |
| `plans[].bandwidth_mbps`, `gateway`, `udp` | integer, string, boolean | Unlimited residential: speed tier, gateway server, and whether the UDP add-on is active |
| `plans[].ips` | integer | ISP, datacenter and dedicated: number of IPs |
| `plans[].bandwidth_gb` | integer or null | Datacenter: monthly bandwidth tier in GB, `null` on the Unlimited tier |
| `plans[].requests_limit`, `requests_used` | integer | SERP API: requests included in the plan, and requests used so far |

Mobile traffic draws from the residential balance, so there is no `mobile` balance. Residential GB packs appear under `balances`, not `plans`. Plans never auto-renew: compare `expires_at` with the current time to decide when to renew.

#### Example: warn on a low balance

**Python**

```python
import os

import requests

r = requests.get(
    "https://api.proxonym.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
residential = r.json()["balances"].get("residential")
if residential is None or residential["gb_remaining"] < 5:
    left = residential["gb_remaining"] if residential else 0
    print(f"Residential balance is low: {left:.1f} GB left. Top up before jobs fail with 402.")
```

## Usage

Read how much traffic, or how many SERP requests, you used over time.

### Get usage

`GET /usage`

Returns the usage of one product over a time range, as a total and a time series.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | string, query | Yes | `residential`, `mobile`, `unlimited`, `isp`, `datacenter`, `dedicated` or `serp` |
| `from` | string, query | No | Start of the range, inclusive: an ISO 8601 date or timestamp in UTC. Default: 7 days before `to` |
| `to` | string, query | No | End of the range, exclusive. Default: now |
| `granularity` | string, query | No | `day` (default) or `hour`. Buckets are aligned to UTC |

A range can span up to 366 days at `day` granularity and 31 days at `hour`. A longer range, or a `from` later than `to`, returns `422` with `validation_failed`. Mobile usage is reported on its own, but it's deducted from the residential balance.

#### Example request

**Shell**

```bash
curl -G https://api.proxonym.com/v1/usage \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d product=residential \
  -d from=2026-09-24 \
  -d to=2026-10-01 \
  -d granularity=day
```

#### Example response

**JSON**

```json
{
  "product": "residential",
  "granularity": "day",
  "from": "2026-09-24T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "total": {
    "traffic_gb": 9.964
  },
  "series": [
    { "timestamp": "2026-09-24T00:00:00Z", "traffic_gb": 1.204 },
    { "timestamp": "2026-09-25T00:00:00Z", "traffic_gb": 1.587 },
    { "timestamp": "2026-09-26T00:00:00Z", "traffic_gb": 0.932 },
    { "timestamp": "2026-09-27T00:00:00Z", "traffic_gb": 1.411 },
    { "timestamp": "2026-09-28T00:00:00Z", "traffic_gb": 1.876 },
    { "timestamp": "2026-09-29T00:00:00Z", "traffic_gb": 1.309 },
    { "timestamp": "2026-09-30T00:00:00Z", "traffic_gb": 1.645 }
  ]
}
```

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `product`, `granularity` | string | The values used for the query |
| `from`, `to` | string | The resolved range, as UTC timestamps |
| `total.traffic_gb` | number | Traffic in the range, in GB. Proxy products only |
| `total.requests` | integer | SERP API requests in the range. `serp` only |
| `series[]` | array | One point per bucket, in time order. Buckets without usage report `0` |
| `series[].timestamp` | string | Start of the bucket |
| `series[].traffic_gb` or `series[].requests` | number or integer | Usage in the bucket, in the same unit as `total` |

For `serp`, totals and points count requests instead of GB. An hourly query such as `?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour` returns:

**JSON**

```json
{
  "product": "serp",
  "granularity": "hour",
  "from": "2026-09-30T00:00:00Z",
  "to": "2026-09-30T03:00:00Z",
  "total": {
    "requests": 1854
  },
  "series": [
    { "timestamp": "2026-09-30T00:00:00Z", "requests": 612 },
    { "timestamp": "2026-09-30T01:00:00Z", "requests": 587 },
    { "timestamp": "2026-09-30T02:00:00Z", "requests": 655 }
  ]
}
```

## Proxy lists

Download the proxies assigned to your static plans. Residential, mobile and unlimited residential have no list: they connect through a gateway, described in [Endpoints and ports](https://proxonym.com/docs#endpoints-and-ports).

### List proxies

`GET /proxies/{product}`

Returns every proxy of your active plans for one product, as JSON or as plain text with one proxy per line.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `product` | string, path | Yes | `datacenter`, `isp` or `dedicated` |
| `format` | string, query | No | `json` (default) or `txt` |
| `country` | string, query | No | Return only proxies in this country: an ISO 3166-1 alpha-2 code in lowercase, such as `us` |

#### Example request

**Shell**

```bash
curl https://api.proxonym.com/v1/proxies/isp \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### Example response

Trimmed to three entries; `count` is the full number.

**JSON**

```json
{
  "product": "isp",
  "count": 20,
  "proxies": [
    {
      "ip": "198.51.100.61",
      "port": 6200,
      "username": "isp_k8w2m4",
      "password": "Tz6pW1qR8nVb3xYc",
      "country": "us",
      "location": "New York",
      "expires_at": "2026-10-20T15:30:00Z"
    },
    {
      "ip": "198.51.100.62",
      "port": 6200,
      "username": "isp_k8w2m4",
      "password": "Tz6pW1qR8nVb3xYc",
      "country": "us",
      "location": "New York",
      "expires_at": "2026-10-20T15:30:00Z"
    },
    {
      "ip": "198.51.100.63",
      "port": 6200,
      "username": "isp_k8w2m4",
      "password": "Tz6pW1qR8nVb3xYc",
      "country": "us",
      "location": "New York",
      "expires_at": "2026-10-20T15:30:00Z"
    }
  ]
}
```

#### Plain text format

With `format=txt`, the response is `text/plain` with one proxy per line: `ip:port` for datacenter, where the port is the HTTP port, and `ip:port:username:password` for ISP and dedicated.

**Shell**

```bash
curl -G https://api.proxonym.com/v1/proxies/datacenter \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d format=txt \
  -d country=us
```

**Text**

```text
198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129
```

#### Proxy fields

| Field | Products | Description |
| --- | --- | --- |
| `ip` | All | Proxy IP address |
| `port` | ISP, dedicated | Port for both HTTP and SOCKS5 |
| `http_port`, `socks5_port` | Datacenter | HTTP port `3129` and SOCKS5 port `1081` |
| `username`, `password` | ISP, dedicated | Credentials for this proxy |
| `country` | All | Country of the IP, as a lowercase ISO 3166-1 alpha-2 code |
| `location` | ISP | City or carrier pool, such as `New York` or `Comcast pool` |
| `expires_at` | ISP, dedicated | End of the term for this IP |

A datacenter entry in JSON looks like `{"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}`. Without an active plan for the product, the API returns `403` with `product_not_active`. A product that has no list, such as `residential`, returns `404`:

**JSON**

```json
{
  "error": {
    "code": "not_found",
    "message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
  }
}
```

## Whitelist

The whitelist lets machines connect to your shared datacenter proxies without credentials. Every shared datacenter plan includes 3 slots, and entries apply to all your datacenter IPs. Background: [IP whitelist](https://proxonym.com/docs#authentication-ip-whitelist) in the docs.

### List whitelisted IPs

`GET /whitelist`

#### Parameters

None.

#### Example request

**Shell**

```bash
curl https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### Example response

**JSON**

```json
{
  "limit": 3,
  "ips": [
    { "ip": "192.0.2.10", "created_at": "2026-09-18T09:20:11Z" },
    { "ip": "192.0.2.57", "created_at": "2026-09-22T17:02:45Z" }
  ]
}
```

`limit` is the number of slots on your account, and `ips` lists the entries, oldest first.

### Add an IP

`POST /whitelist`

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ip` | string, body | Yes | Public IP address of the machine that will connect, such as `192.0.2.44` |

#### Example request

**Shell**

```bash
curl -X POST https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "192.0.2.44"}'
```

#### Example response

Status `201`:

**JSON**

```json
{
  "ip": "192.0.2.44",
  "created_at": "2026-10-01T09:30:00Z"
}
```

An IP that is already listed returns `409` with `already_exists`, and an invalid address returns `422` with `validation_failed`. When every slot is taken, the API returns `422`:

**JSON**

```json
{
  "error": {
    "code": "whitelist_full",
    "message": "All 3 whitelist slots are in use. Remove an IP before adding another."
  }
}
```

### Remove an IP

`DELETE /whitelist/{ip}`

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ip` | string, path | Yes | The whitelisted IP to remove |

#### Example request

**Shell**

```bash
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### Example response

**JSON**

```json
{
  "ip": "192.0.2.10",
  "deleted": true
}
```

From then on, requests from that IP without credentials fail with `407`. An IP that isn't on the list returns `404` with `not_found`.

## Sub-users

Sub-users are extra proxy credentials under your account, each with an optional traffic limit. Their traffic counts against your account balance. Background: [Sub-users](https://proxonym.com/docs#authentication-sub-users) in the docs.

### The sub-user object

**JSON**

```json
{
  "id": "su_3k9x2m7q",
  "name": "price-monitor",
  "username": "sub_k3v9q2xd",
  "password": "Qm7vT2xK9pLr4sWz",
  "traffic_limit_gb": 25,
  "traffic_used_gb": 6.412,
  "status": "active",
  "created_at": "2026-09-14T08:05:22Z"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Sub-user ID, used in API paths |
| `name` | string | Your label for the sub-user, unique in your account |
| `username` | string | Proxy username, generated. It takes the same options as your main username, such as `sub_k3v9q2xd-country-us-session-a7k2` |
| `password` | string | Proxy password, generated |
| `traffic_limit_gb` | number or null | Maximum traffic in GB. `null` means no limit beyond your account balance |
| `traffic_used_gb` | number | Traffic used so far, in GB |
| `status` | string | `active` or `disabled`. The proxy answers `407` to disabled sub-users |
| `created_at` | string | When the sub-user was created |

When `traffic_used_gb` reaches `traffic_limit_gb`, the sub-user's requests fail with `402` until you raise the limit.

### List sub-users

`GET /sub-users`

#### Parameters

None.

#### Example request

**Shell**

```bash
curl https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### Example response

**JSON**

```json
{
  "sub_users": [
    {
      "id": "su_3k9x2m7q",
      "name": "price-monitor",
      "username": "sub_k3v9q2xd",
      "password": "Qm7vT2xK9pLr4sWz",
      "traffic_limit_gb": 25,
      "traffic_used_gb": 6.412,
      "status": "active",
      "created_at": "2026-09-14T08:05:22Z"
    },
    {
      "id": "su_8d1f4n6p",
      "name": "qa-team",
      "username": "sub_p8w2n5tf",
      "password": "Hx4bN9cR2vLq7mKs",
      "traffic_limit_gb": null,
      "traffic_used_gb": 1.207,
      "status": "disabled",
      "created_at": "2026-09-20T13:47:09Z"
    }
  ]
}
```

### Create a sub-user

`POST /sub-users`

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string, body | Yes | Label of 1 to 64 characters, unique in your account |
| `traffic_limit_gb` | number or null, body | No | Traffic limit in GB, greater than 0. Omit it or send `null` for no limit |

#### Example request

**Shell**

```bash
curl -X POST https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "eu-crawler", "traffic_limit_gb": 10}'
```

#### Example response

Status `201`, with a generated username and password:

**JSON**

```json
{
  "id": "su_6v2c8r1t",
  "name": "eu-crawler",
  "username": "sub_t6r1y8bw",
  "password": "Lp3sV8kQ1zXn6wRd",
  "traffic_limit_gb": 10,
  "traffic_used_gb": 0,
  "status": "active",
  "created_at": "2026-10-01T09:30:00Z"
}
```

A name that's already taken returns `409` with `already_exists`. The new credentials work on the gateway right away, with the usual username options:

**Shell**

```bash
curl -x http://gw.proxonym.com:8000 \
  -U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
  https://api.ipify.org
```

### Update a sub-user

`PATCH /sub-users/{id}`

Send only the fields you want to change.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string, path | Yes | Sub-user ID |
| `name` | string, body | No | New label, 1 to 64 characters |
| `traffic_limit_gb` | number or null, body | No | New limit in GB, or `null` for no limit |
| `status` | string, body | No | `active` or `disabled` |
| `reset_password` | boolean, body | No | `true` generates a new password. The old one stops working immediately |

#### Example request

Raise the limit and reset the password:

**Shell**

```bash
curl -X PATCH https://api.proxonym.com/v1/sub-users/su_3k9x2m7q \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"traffic_limit_gb": 40, "reset_password": true}'
```

#### Example response

**JSON**

```json
{
  "id": "su_3k9x2m7q",
  "name": "price-monitor",
  "username": "sub_k3v9q2xd",
  "password": "Wd5nX8qT3vKz6pRm",
  "traffic_limit_gb": 40,
  "traffic_used_gb": 6.412,
  "status": "active",
  "created_at": "2026-09-14T08:05:22Z"
}
```

### Delete a sub-user

`DELETE /sub-users/{id}`

Deletes the sub-user, and its credentials stop working immediately. Traffic it already used stays in your usage. To pause a sub-user instead, set its `status` to `disabled`.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string, path | Yes | Sub-user ID |

#### Example request

**Shell**

```bash
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
  -H "Authorization: Bearer $PROXONYM_API_KEY"
```

#### Example response

**JSON**

```json
{
  "id": "su_8d1f4n6p",
  "deleted": true
}
```

An unknown ID returns `404` with `not_found`.

## SERP API

The [Google SERP API](https://proxonym.com/serp-api) returns Google search results as parsed JSON, for any country or city, on desktop or mobile. Each call returns one results page and counts as one request on your plan.

### Search

`GET https://serp.proxonym.com/v1/search`

Send your SERP API key from the dashboard in the `X-API-Key` header. Errors use the same format as the account API: a missing or invalid key returns `401` with `invalid_api_key`. Without an active SERP plan, the API returns `403` with `product_not_active`, and once the plan's requests are used up, `403` with `quota_exceeded`.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | Search query, URL-encoded |
| `gl` | string | No | Country of the results, as a lowercase ISO 3166-1 alpha-2 code. Default `us` |
| `hl` | string | No | Interface language code, such as `en` or `de`. Default `en` |
| `location` | string | No | City-level location written as `City,Region`, such as `Chicago,Illinois`. Use a place inside the `gl` country |
| `device` | string | No | `desktop` (default) or `mobile` |
| `page` | integer | No | Results page, starting at `1` (default). Each page is a separate request |

#### Example request

**Shell**

```bash
curl -G https://serp.proxonym.com/v1/search \
  -H "X-API-Key: $PROXONYM_SERP_KEY" \
  --data-urlencode "q=running shoes" \
  -d gl=us \
  -d hl=en \
  --data-urlencode "location=Chicago,Illinois" \
  -d device=desktop \
  -d page=1
```

The same request in Python:

**Python**

```python
import os

import requests

params = {
    "q": "running shoes",
    "gl": "us",
    "hl": "en",
    "location": "Chicago,Illinois",
    "device": "desktop",
    "page": 1,
}
r = requests.get(
    "https://serp.proxonym.com/v1/search",
    headers={"X-API-Key": os.environ["PROXONYM_SERP_KEY"]},
    params=params,
    timeout=60,
)
r.raise_for_status()
for result in r.json()["organic_results"]:
    print(result["position"], result["title"], result["link"])
```

#### Example response

Trimmed for length:

**JSON**

```json
{
  "search_parameters": {
    "q": "running shoes",
    "gl": "us",
    "hl": "en",
    "location": "Chicago,Illinois",
    "device": "desktop",
    "page": 1
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Running Shoes for Men and Women | Stride Supply",
      "link": "https://www.stridesupply.example/running-shoes",
      "snippet": "Shop road and trail running shoes in every size. Compare cushioning, drop and weight across 40 models."
    },
    {
      "position": 2,
      "title": "How to Choose Running Shoes: A Buyer's Guide",
      "link": "https://www.runnersdesk.example/guides/choosing-running-shoes",
      "snippet": "Gait, arch type and weekly mileage matter more than brand. Here is how to narrow the field."
    },
    {
      "position": 3,
      "title": "Running Shoes in Chicago, IL | Lakeshore Run Co.",
      "link": "https://www.lakeshorerun.example/",
      "snippet": "Gait analysis and fittings at our Lincoln Park store, open 7 days a week."
    }
  ],
  "ads": [
    {
      "position": 1,
      "title": "Running Shoes Sale | Up to 40% Off",
      "link": "https://www.shoeoutlet.example/running",
      "snippet": "Last season's models in stock. Ships in 1 business day."
    }
  ],
  "people_also_ask": [
    {
      "question": "How often should you replace running shoes?",
      "snippet": "Many runners replace their shoes every 300 to 500 miles.",
      "link": "https://www.runnersdesk.example/guides/shoe-lifespan"
    }
  ],
  "related_searches": [
    { "query": "running shoes near me" },
    { "query": "trail running shoes" },
    { "query": "running shoes for flat feet" }
  ],
  "local_results": [
    {
      "position": 1,
      "title": "Lakeshore Run Co.",
      "address": "2312 N Lincoln Ave, Chicago, IL",
      "phone": "(312) 555-0142"
    },
    {
      "position": 2,
      "title": "Windy City Running",
      "address": "845 W Randolph St, Chicago, IL",
      "phone": "(312) 555-0187"
    }
  ]
}
```

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `search_parameters` | object | The parameters of the search, with defaults filled in |
| `organic_results[]` | array | Organic results in page order |
| `organic_results[].position` | integer | Rank on the page, starting at 1 |
| `organic_results[].title` | string | Result title |
| `organic_results[].link` | string | Result URL |
| `organic_results[].snippet` | string | Text shown under the title |
| `ads[]` | array | Paid results, with `position`, `title`, `link` and `snippet` |
| `people_also_ask[]` | array | Questions from the "People also ask" box, with `question`, `snippet` and `link` |
| `related_searches[]` | array | Related queries, each with `query` |
| `local_results[]` | array | Local pack results, with `position`, `title`, `address` and `phone` |

Blocks that don't appear on the page come back as empty arrays. To follow rankings over time, see the [SERP tracking use case](https://proxonym.com/use-cases/serp-tracking) and our guide to [scraping Google search results](https://proxonym.com/blog/scrape-google-search-results).

- [Documentation](https://proxonym.com/docs): Gateway, sessions, targeting, errors
- [Integrations](https://proxonym.com/integrations): Puppeteer, Playwright, Scrapy and more
