> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodemaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the account API with the SDKs

> Read traffic and locations, retrieve statistics, and manage sub-users and whitelisted IPs.

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](https://docs.nodemaven.com/developer-sdks/python.md), [Rust](https://docs.nodemaven.com/developer-sdks/rust.md), or [Go](https://docs.nodemaven.com/developer-sdks/go.md) installation guide. Rust examples use the SDK's default HTTP feature.

## 1. Set your API key

In the [dashboard](https://dashboard.nodemaven.com), open **Profile → API key** and copy the key.

On macOS or Linux:

```bash theme={null}
export NODEMAVEN_APIKEY='YOUR_API_KEY'
```

On Windows PowerShell:

```powershell theme={null}
$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**

```python theme={null}
from nodemaven import Client

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

**Rust**

```rust theme={null}
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(())
}
```

**Go**

```go theme={null}
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**

```python theme={null}
page = client.cities(country__code="us", region__code="california")
for city in client.iterate(page):
    print(city["code"])
```

**Rust**

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

**Go**

Add `net/url` to the imports:

```go theme={null}
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**

```python theme={null}
from nodemaven import Proxy

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

**Rust**

```rust theme={null}
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());
}
```

**Go**

```go theme={null}
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](https://docs.nodemaven.com/developer-sdks/connection-checks.md).

## 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**

```python theme={null}
import os

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

**Rust**

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

**Go**

Add `os` and `net/url` to the imports:

```go theme={null}
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**

```python theme={null}
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.")
```

**Rust**

```rust theme={null}
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.");
```

**Go**

Add `os` to the imports:

```go theme={null}
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](https://docs.nodemaven.com/proxy-api/sub-users.md) 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**

```python theme={null}
import os

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

**Rust**

```rust theme={null}
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.");
```

**Go**

Add `os` to the imports:

```go theme={null}
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](https://docs.nodemaven.com/residential-mobile/ip-whitelist.md) and the [IP whitelist API reference](https://docs.nodemaven.com/proxy-api/whitelist.md).

## 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](https://docs.nodemaven.com/proxy-api/overview.md) 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](https://docs.nodemaven.com/developer-sdks/connection-checks.md) for error types in each language.

## References

* [NodeMaven API overview](https://docs.nodemaven.com/proxy-api/overview.md)
* [Interactive endpoint reference](https://dashboard.nodemaven.com/documentation/v2/swagger/)
* [Python SDK source](https://github.com/nodemaven/nodemaven-python)
* [Rust SDK reference](https://docs.rs/nodemaven/0.2.2/nodemaven/)
* [Go SDK reference](https://pkg.go.dev/github.com/nodemaven/nodemaven-go@v0.1.1)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.