Use the account API with the SDKs

Read your traffic, retrieve locations and usage statistics, and manage supported account resources from code. The SDK account client is separate from the proxy builder. It uses your API key, not your proxy password, and sends management requests directly to the account API. You do not need to route those requests through a proxy. This guide covers Python 0.1.7, Rust 0.2.2, and Go v0.1.1. Start with the corresponding Python, Rust, or Go installation guide. Rust examples use the SDK’s default HTTP feature.

1. Set your API key

In the dashboard, open Profile → API key and copy the key. On macOS or Linux:

export NODEMAVEN_APIKEY='YOUR_API_KEY'

On Windows PowerShell:

$env:NODEMAVEN_APIKEY = 'YOUR_API_KEY'

Set the raw key, without an x-api-key or Bearer prefix. The client builds the authorization header for you. Keep the key in server-side environment variables or your application’s secret store. Use the SDK’s default base URL unless your deployment specifically requires an override. Do not replace it with a complete endpoint URL copied from the REST reference: the SDK appends its own paths.

2. Read your traffic balance

These are complete programs. Use separate files/projects from the proxy quickstarts because each example has its own entry point.

Python
Rust
Go

from nodemaven import Client

client = Client()
me = client.me()
print(f"Traffic left: {me['data']} bytes")

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = nodemaven::Client::builder().build()?;
    let me = client.me()?;
    println!("Traffic left: {} bytes", me["data"]);
    Ok(())
}

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/nodemaven/nodemaven-go"
)

func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

func run() error {
    ctx := context.Background()
    client, err := nodemaven.NewClient()
    if err != nil {
        return err
    }
    me, err := client.Me(ctx)
    if err != nil {
        return err
    }
    fmt.Printf("Traffic left: %v bytes\n", me["data"])
    return nil
}

The data field is the remaining traffic in bytes. The response also contains proxy credentials, so print only the fields you need. Do not log me or sub-user responses in full. In this endpoint’s response, is_traffic_frozen is a string, not a boolean; do not treat a nonempty string as a true/false flag. The remaining examples are fragments that reuse client. Add Rust fragments before Ok(()); add Go fragments inside run, before return nil. Additional Go imports are named where needed.

3. Retrieve location codes

Read the location catalogue instead of guessing names. For example, retrieve US cities in a selected region.

Python
Rust
Go

page = client.cities(country__code="us", region__code="california")
for city in client.iterate(page):
    print(city["code"])

let page = client.cities(&[
    ("country__code", "us"),
    ("region__code", "california"),
])?;
for row in client.iterate(page) {
    let city = row?;
    println!("{}", city["code"]);
}

Add net/url to the imports:

page, err := client.Cities(ctx, url.Values{
    "country__code": {"us"},
    "region__code":  {"california"},
})
if err != nil {
    return err
}
rows := client.Iterate(ctx, page)
for rows.Next() {
    city, ok := rows.Row().(map[string]any)
    if !ok {
        return fmt.Errorf("unexpected city row type")
    }
    fmt.Println(city["code"])
}
if err := rows.Err(); err != nil {
    return err
}

Use regions first to find the relevant region code for your country. Filter names such as country__code have two underscores. The server can ignore an unknown filter name, so check spelling carefully.

Catalogue	Python / Rust	Go
Countries	`countries`	`Countries`
Regions	`regions`	`Regions`
Cities	`cities`	`Cities`
Carriers	`isps`	`ISPs`
ZIP codes	`zip_codes`	`ZipCodes`

List methods return a page, not necessarily every row. Use the iterator to walk the remaining pages. Reading ZIP catalogue entries does not make zip an accepted proxy-builder parameter.

4. Check the country and required region

The account client’s validate method checks whether a country is in the current catalogue and detects a city without a region. It does not fully match region, city, or carrier values against their catalogues, and it does not open a proxy tunnel. These snippets also need your proxy credentials in the environment.

Python
Rust
Go

from nodemaven import Proxy

proxy = Proxy(country="us", region="california", city="los angeles")
problems = client.validate(proxy)
if problems:
    raise SystemExit("\n".join(problems))

let proxy = nodemaven::Proxy::builder()
    .param("country", "us")
    .param("region", "california")
    .param("city", "los angeles")
    .build()?;
let problems = client.validate(&proxy)?;
if !problems.is_empty() {
    return Err(problems.join("\n").into());
}

proxy, err := nodemaven.New(
    nodemaven.WithParam("country", "us"),
    nodemaven.WithParam("region", "california"),
    nodemaven.WithParam("city", "los angeles"),
)
if err != nil {
    return err
}
problems, err := client.Validate(ctx, proxy)
if err != nil {
    return err
}
if len(problems) > 0 {
    return fmt.Errorf("location validation: %v", problems)
}

An empty list means these checks found no problem. It is not a complete configuration or availability guarantee. Follow with a connection check and real request.

5. Retrieve usage statistics

Statistics use the base proxy username, without targeting/session suffixes. Set NODEMAVEN_LOGIN to the main user’s or sub-user’s proxy username, then request a time window.

Python
Rust
Go

import os

stats = client.statistics_data(os.environ["NODEMAVEN_LOGIN"], period="today")
print(stats)

let username = std::env::var("NODEMAVEN_LOGIN")?;
let stats = client.statistics_data(&username, &[("period", "today")])?;
println!("{stats}");

Add os and net/url to the imports:

username := os.Getenv("NODEMAVEN_LOGIN")
if username == "" {
    return fmt.Errorf("set NODEMAVEN_LOGIN to the base proxy username")
}
stats, err := client.StatisticsData(ctx, username, url.Values{
    "period": {"today"},
})
if err != nil {
    return err
}
fmt.Println(stats)

Use statistics_requests / StatisticsRequests for request counts and domain_statistics / DomainStatistics for traffic by domain. For an explicit range, supply both start and end as dd-mm-yyyy, for example 01-10-2026 and 07-10-2026. Do not omit both the range and period.

6. Manage sub-users

Creating a sub-user changes the account. The example below creates worker_001 with an enabled traffic limit of 1,000,000,000 bytes. Choose an unused username and set NODEMAVEN_SUBUSER_PASSWORD to the password you want to assign before running it. Usernames and passwords must be 9–100 characters and contain only letters, digits, or underscores.

Python
Rust
Go

import os

client.create_sub_user(
    "worker_001",
    os.environ["NODEMAVEN_SUBUSER_PASSWORD"],
    is_traffic_limited=True,
    traffic_limit=1_000_000_000,
)
print("Sub-user created.")

let password = std::env::var("NODEMAVEN_SUBUSER_PASSWORD")?;
client.create_sub_user(
    "worker_001",
    &password,
    &[
        ("is_traffic_limited", true.into()),
        ("traffic_limit", 1_000_000_000_u64.into()),
    ],
)?;
println!("Sub-user created.");

Add os to the imports:

password := os.Getenv("NODEMAVEN_SUBUSER_PASSWORD")
if password == "" {
    return fmt.Errorf("set NODEMAVEN_SUBUSER_PASSWORD before creating a sub-user")
}
_, err = client.CreateSubUser(ctx, "worker_001", password, map[string]any{
    "is_traffic_limited": true,
    "traffic_limit":      1_000_000_000,
})
if err != nil {
    return err
}
fmt.Println("Sub-user created.")

Traffic limits are in bytes. When updating a limit, send either an absolute traffic_limit or a relative traffic_limit_increment_bytes, not both. The clients also support listing, updating, deleting, and resetting usage for sub-users. See the sub-user API reference for the effects and field constraints.

7. Manage the IP whitelist

The clients can list, inspect, add/update, and delete whitelist entries. An upsert can create an entry or update an existing one, so use it only when you intend to change account access. Set NODEMAVEN_WHITELIST_IP to the public egress IP of the machine you want to authorize. This example requests one HTTP proxy port for that entry. The calling machine’s IP is not detected or added automatically.

Python
Rust
Go

import os

client.upsert_whitelist_ip(
    os.environ["NODEMAVEN_WHITELIST_IP"],
    1,
    name="sdk_example",
    protocol="HTTP",
)
print("Whitelist entry saved.")

let ip = std::env::var("NODEMAVEN_WHITELIST_IP")?;
client.upsert_whitelist_ip(
    &ip,
    1,
    &[("name", "sdk_example".into()), ("protocol", "HTTP".into())],
)?;
println!("Whitelist entry saved.");

Add os to the imports:

ip := os.Getenv("NODEMAVEN_WHITELIST_IP")
if ip == "" {
    return fmt.Errorf("set NODEMAVEN_WHITELIST_IP before changing the whitelist")
}
_, err = client.UpsertWhitelistIP(ctx, ip, 1, map[string]any{
    "name":     "sdk_example",
    "protocol": "HTTP",
})
if err != nil {
    return err
}
fmt.Println("Whitelist entry saved.")

Whitelisting is a separate authentication workflow from the username/password proxy examples. See IP Whitelist setup and the IP whitelist API reference.

SDK coverage and API errors

The REST API includes areas that these SDK clients do not wrap, such as webhooks and API-key management. Use the API Reference for those operations; do not infer an SDK method from an endpoint name. Account responses use the server’s field names. Python returns dictionaries, Rust uses serde_json::Value, and Go uses map[string]any with JSON numbers represented as json.Number. For 401/403, check the API key and account permissions. For 429, apply bounded backoff in your application. The clients do not retry automatically. A non-JSON response is an API error even if its HTTP status is 2xx. See Check connections and handle SDK errors for error types in each language.

Get started

Products

More

Use the account API with the SDKs

1. Set your API key

2. Read your traffic balance

3. Retrieve location codes

4. Check the country and required region

5. Retrieve usage statistics

6. Manage sub-users

7. Manage the IP whitelist

SDK coverage and API errors

References

​1. Set your API key

​2. Read your traffic balance

​3. Retrieve location codes

​4. Check the country and required region

​5. Retrieve usage statistics

​6. Manage sub-users

​7. Manage the IP whitelist

​SDK coverage and API errors

​References

1. Set your API key

2. Read your traffic balance

3. Retrieve location codes

4. Check the country and required region

5. Retrieve usage statistics

6. Manage sub-users

7. Manage the IP whitelist

SDK coverage and API errors

References