Proxies

Three read endpoints. This is where your connection credentials come from.

A proxy assignment pairs one residential exit IP with one set of gateway credentials. You connect to the shared gateway host and port using the assignment's username and password, and the gateway routes you out through the residential IP. The credentials stay the same when the exit IP behind them is replaced.

GET /proxies
GET /proxies/{assignment_id}
GET /workspaces/{account_id}/proxies

List proxies

GET /proxies

Every proxy assignment in the organization, optionally filtered to one workspace.

Returns all assignments across all workspaces, with the gateway credentials for each. This is usually the only proxy call an integration needs: fetch once at startup, cache the result, and refresh when you change your plan.

Query parameters

Name	Type	Description
`account_id` Optional	`string`	Restrict results to one workspace. Equivalent to `GET /workspaces/{account_id}/proxies`.

Example request

cURL

curl https://api.proxycharm.com/api/v1/public/proxies \
  -H "Authorization: Bearer $PROXYCHARM_API_KEY"

Python

import os
import requests

API_KEY = os.environ["PROXYCHARM_API_KEY"]

response = requests.get(
    "https://api.proxycharm.com/api/v1/public/proxies",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)
payload = response.json()

if not payload["success"]:
    raise RuntimeError(payload["error"]["message"])

print(payload["data"])

Node.js

const apiKey = process.env.PROXYCHARM_API_KEY;

const response = await fetch("https://api.proxycharm.com/api/v1/public/proxies", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});
const payload = await response.json();

if (!payload.success) {
  throw new Error(payload.error.message);
}

console.log(payload.data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type envelope struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data"`
	Error   *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	req, err := http.NewRequest("GET", "https://api.proxycharm.com/api/v1/public/proxies", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PROXYCHARM_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var payload envelope
	if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
		panic(err)
	}
	if !payload.Success {
		panic(payload.Error.Message)
	}
	fmt.Println(string(payload.Data))
}

PHP

<?php
$apiKey = getenv("PROXYCHARM_API_KEY");

$ch = curl_init("https://api.proxycharm.com/api/v1/public/proxies");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
    ],
]);
$payload = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$payload["success"]) {
    throw new RuntimeException($payload["error"]["message"]);
}

print_r($payload["data"]);

Example response

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "assignment_id": "9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4",
        "proxy_ip_id": "2f8e5d13-9a7c-4f62-b0d4-6e3a1c58b7f9",
        "ip_address": "203.0.113.42",
        "country": "US",
        "city": "Chicago",
        "status": "live",
        "host": "zephyr.proxy.rlwy.net",
        "port": null,
        "username": "pc_9c1f7a2e",
        "password": "s3cr3t-value",
        "replaced_at": null
      }
    ],
    "total": 1
  },
  "error": null,
  "request_id": null,
  "timestamp": "2026-02-18T09:31:04.512Z"
}

Response fields

Name	Type	Description
`items`	`array<object>`	The assignments.
`assignment_id`	`string`	Assignment id. Use this wherever an endpoint takes `{assignment_id}`.
`proxy_ip_id`	`string`	Id of the underlying IP record. Changes when the exit is replaced.
`ip_address`	`string \| null`	Residential exit IP. Null while the assignment is still provisioning.
`country`	`string \| null`	ISO 3166-1 alpha-2 country of the exit.
`city`	`string \| null`	City of the exit, when known.
`status`	`string`	Assignment lifecycle state.
`host`	`string`	Gateway hostname to connect to. Shared across all customers.
`port`	`integer`	Gateway port. Shared across all customers.
`username`	`string`	Gateway username for this assignment.
`password`	`string`	Gateway password for this assignment. Treat as a secret.
`replaced_at`	`string \| null`	ISO timestamp of the last exit replacement. Null if never replaced.
`total`	`integer`	Number of assignments returned.

Errors

Code	HTTP	What it means
`PROFILE_NOT_FOUND`	`200`	The profile that created the key no longer exists.
`API_KEY_INVALID`	`401`	The Authorization header is missing the key prefix, the key does not exist, or its organization has been deleted.
`API_KEY_REVOKED`	`401`	The key was revoked in the dashboard.
`API_KEY_EXPIRED`	`401`	The key passed the expiry date it was created with.
`RATE_LIMIT_EXCEEDED`	`429`	The key exceeded its request budget for the current window.

Get proxy

GET /proxies/{assignment_id}

Read one proxy assignment by id.

Returns a single assignment. The lookup is scoped to your organization, so an id belonging to someone else returns HTTP 404 and not the record.

Path parameters

Name	Type	Description
`assignment_id` Required	`string`	Assignment id, from `GET /proxies`.

Example request

cURL

curl https://api.proxycharm.com/api/v1/public/proxies/9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4 \
  -H "Authorization: Bearer $PROXYCHARM_API_KEY"

Python

import os
import requests

API_KEY = os.environ["PROXYCHARM_API_KEY"]

response = requests.get(
    "https://api.proxycharm.com/api/v1/public/proxies/9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)
payload = response.json()

if not payload["success"]:
    raise RuntimeError(payload["error"]["message"])

print(payload["data"])

Node.js

const apiKey = process.env.PROXYCHARM_API_KEY;

const response = await fetch("https://api.proxycharm.com/api/v1/public/proxies/9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});
const payload = await response.json();

if (!payload.success) {
  throw new Error(payload.error.message);
}

console.log(payload.data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type envelope struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data"`
	Error   *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	req, err := http.NewRequest("GET", "https://api.proxycharm.com/api/v1/public/proxies/9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PROXYCHARM_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var payload envelope
	if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
		panic(err)
	}
	if !payload.Success {
		panic(payload.Error.Message)
	}
	fmt.Println(string(payload.Data))
}

PHP

<?php
$apiKey = getenv("PROXYCHARM_API_KEY");

$ch = curl_init("https://api.proxycharm.com/api/v1/public/proxies/9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
    ],
]);
$payload = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$payload["success"]) {
    throw new RuntimeException($payload["error"]["message"]);
}

print_r($payload["data"]);

Example response

200 OK

{
  "success": true,
  "data": {
    "assignment_id": "9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4",
    "proxy_ip_id": "2f8e5d13-9a7c-4f62-b0d4-6e3a1c58b7f9",
    "ip_address": "203.0.113.42",
    "country": "US",
    "city": "Chicago",
    "status": "live",
    "host": "zephyr.proxy.rlwy.net",
    "port": null,
    "username": "pc_9c1f7a2e",
    "password": "s3cr3t-value",
    "replaced_at": null
  },
  "error": null,
  "context": {
    "affected_entities": [],
    "suggested_next_actions": [
      "list_proxies"
    ],
    "warnings": []
  },
  "request_id": null,
  "timestamp": "2026-02-18T09:31:04.512Z"
}

Response fields

Name	Type	Description
`assignment_id`	`string`	Assignment id. Use this wherever an endpoint takes `{assignment_id}`.
`proxy_ip_id`	`string`	Id of the underlying IP record. Changes when the exit is replaced.
`ip_address`	`string \| null`	Residential exit IP. Null while the assignment is still provisioning.
`country`	`string \| null`	ISO 3166-1 alpha-2 country of the exit.
`city`	`string \| null`	City of the exit, when known.
`status`	`string`	Assignment lifecycle state.
`host`	`string`	Gateway hostname to connect to. Shared across all customers.
`port`	`integer`	Gateway port. Shared across all customers.
`username`	`string`	Gateway username for this assignment.
`password`	`string`	Gateway password for this assignment. Treat as a secret.
`replaced_at`	`string \| null`	ISO timestamp of the last exit replacement. Null if never replaced.

Errors

Code	HTTP	What it means
`ASSIGNMENT_NOT_FOUND`	`404`	No proxy assignment with that id exists in your organization.
`PROFILE_NOT_FOUND`	`200`	The profile that created the key no longer exists.
`API_KEY_INVALID`	`401`	The Authorization header is missing the key prefix, the key does not exist, or its organization has been deleted.
`API_KEY_REVOKED`	`401`	The key was revoked in the dashboard.
`API_KEY_EXPIRED`	`401`	The key passed the expiry date it was created with.
`RATE_LIMIT_EXCEEDED`	`429`	The key exceeded its request budget for the current window.

List workspace proxies

GET /workspaces/{account_id}/proxies

Proxies assigned to one workspace.

Returns the assignments belonging to a single workspace. Identical in result to GET /proxies?account_id={account_id}, and more readable when the workspace is the subject of the code path.

Path parameters

Name	Type	Description
`account_id` Required	`string`	Workspace id whose proxies you want.

Example request

cURL

curl https://api.proxycharm.com/api/v1/public/workspaces/3b7d2c48-6e19-4a5f-8b0c-9d1e2f3a4b5c/proxies \
  -H "Authorization: Bearer $PROXYCHARM_API_KEY"

Python

import os
import requests

API_KEY = os.environ["PROXYCHARM_API_KEY"]

response = requests.get(
    "https://api.proxycharm.com/api/v1/public/workspaces/3b7d2c48-6e19-4a5f-8b0c-9d1e2f3a4b5c/proxies",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)
payload = response.json()

if not payload["success"]:
    raise RuntimeError(payload["error"]["message"])

print(payload["data"])

Node.js

const apiKey = process.env.PROXYCHARM_API_KEY;

const response = await fetch("https://api.proxycharm.com/api/v1/public/workspaces/3b7d2c48-6e19-4a5f-8b0c-9d1e2f3a4b5c/proxies", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});
const payload = await response.json();

if (!payload.success) {
  throw new Error(payload.error.message);
}

console.log(payload.data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type envelope struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data"`
	Error   *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	req, err := http.NewRequest("GET", "https://api.proxycharm.com/api/v1/public/workspaces/3b7d2c48-6e19-4a5f-8b0c-9d1e2f3a4b5c/proxies", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PROXYCHARM_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var payload envelope
	if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
		panic(err)
	}
	if !payload.Success {
		panic(payload.Error.Message)
	}
	fmt.Println(string(payload.Data))
}

PHP

<?php
$apiKey = getenv("PROXYCHARM_API_KEY");

$ch = curl_init("https://api.proxycharm.com/api/v1/public/workspaces/3b7d2c48-6e19-4a5f-8b0c-9d1e2f3a4b5c/proxies");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
    ],
]);
$payload = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$payload["success"]) {
    throw new RuntimeException($payload["error"]["message"]);
}

print_r($payload["data"]);

Example response

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "assignment_id": "9c1f7a2e-4b5d-4c3a-8e11-2d7b6f0a91c4",
        "proxy_ip_id": "2f8e5d13-9a7c-4f62-b0d4-6e3a1c58b7f9",
        "ip_address": "203.0.113.42",
        "country": "US",
        "city": "Chicago",
        "status": "live",
        "host": "zephyr.proxy.rlwy.net",
        "port": null,
        "username": "pc_9c1f7a2e",
        "password": "s3cr3t-value",
        "replaced_at": null
      }
    ],
    "total": 1
  },
  "error": null,
  "request_id": null,
  "timestamp": "2026-02-18T09:31:04.512Z"
}

Response fields

Name	Type	Description
`items`	`array<object>`	Assignments for this workspace.
`assignment_id`	`string`	Assignment id. Use this wherever an endpoint takes `{assignment_id}`.
`proxy_ip_id`	`string`	Id of the underlying IP record. Changes when the exit is replaced.
`ip_address`	`string \| null`	Residential exit IP. Null while the assignment is still provisioning.
`country`	`string \| null`	ISO 3166-1 alpha-2 country of the exit.
`city`	`string \| null`	City of the exit, when known.
`status`	`string`	Assignment lifecycle state.
`host`	`string`	Gateway hostname to connect to. Shared across all customers.
`port`	`integer`	Gateway port. Shared across all customers.
`username`	`string`	Gateway username for this assignment.
`password`	`string`	Gateway password for this assignment. Treat as a secret.
`replaced_at`	`string \| null`	ISO timestamp of the last exit replacement. Null if never replaced.
`total`	`integer`	Number of assignments returned.

Errors

Code	HTTP	What it means
`ORGANIZATION_PERMISSION_DENIED`	`403`	The workspace id in the path belongs to another organization, or the profile that created the key is not an owner. Invoices require owner-level access.
`PROFILE_NOT_FOUND`	`200`	The profile that created the key no longer exists.
`API_KEY_INVALID`	`401`	The Authorization header is missing the key prefix, the key does not exist, or its organization has been deleted.
`API_KEY_REVOKED`	`401`	The key was revoked in the dashboard.
`API_KEY_EXPIRED`	`401`	The key passed the expiry date it was created with.
`RATE_LIMIT_EXCEEDED`	`429`	The key exceeded its request budget for the current window.