GlobeData Proxy & API Reference

Two things live here. Proxy usage — how to rotate, how to hold an IP with a sticky session and a TTL, and how to target a country, region or city. And the Reseller API, which provisions the sub-accounts that use those proxies: creation, GB allocation, suspension, usage reporting. Everything you can do in the dashboard, you can do here.

Proxy endpoint (HTTP/S)

proxy.globedata.io:8080

Proxy endpoint (SOCKS5)

proxy.globedata.io:1080

Reseller API base URL

https://api.globedata.io/api/v1/reseller

API authentication

Authorization: Bearer gd_…

API rate limit

60 requests / minute / key

Metering

KB, +2 KB overhead / request

JavaScript is off

The interactive examples on this page are rendered in the browser. The full plain-text reference is always available at /RESELLER-API.md.

New here? Read in this order

How it works → Quickstart → Proxy usage: rotating, sticky & TTL → Best use cases → Recipes. Every example on this page comes in cURL, Python and Node.js; switching the tab on one example switches them all and remembers your choice.

Looking for the LinkedIn Scraper API?

It has its own reference: globedata.io/scraper-api-docs.html. Same API key, separate billing (per request, not per GB).

How it works

Four moving parts. Understand these and the whole API follows.

1 · you buy

Parent package

GB you purchased, with an expiry date. Your pool. Identified by user_package_id.

→

2 · you create

Sub-user

An end customer or a project. Draws GB from one parent package, and gets its own dashboard login.

→

3 · they use

Proxy credentials

A sub_… username + password, valid on proxy.globedata.io instantly.

→

4 · we meter

Usage

Traffic is billed to that sub-user's package and readable per-day or per-request.

Traffic never touches your parent package directly — a sub-user's bytes come out of the allocation you gave them, which is why per-customer billing works without you counting anything yourself.

What each API is for

You want to…	Use
Create accounts for your own customers and bill them for traffic	Reseller API
Give a customer more GB, take unused GB back, or cut them off	POST /subusers/:id/allocate, PATCH /subusers/:id
Show a customer what they used, or invoice from it	GET /subusers/:id/usage
Send HTTP traffic through a residential IP	Proxy credentials — no API call needed
Keep the same exit IP across several requests	Sticky sessions — `-session-ID-ttl-SECONDS`
Turn a LinkedIn handle into structured data	Scraper API — separate reference

You do not need the API to use the proxy

Proxy credentials are plain HTTP proxy auth. The API exists to provision and meter them. If you only want to send traffic, skip to Using proxy credentials.

Quickstart

From zero to a working sub-user with live proxy credentials — three calls.

Create an API key

In the dashboard, open Sub-Users → API Keys → New API Key. The key looks like gd_a1b2c3… and is shown exactly once — we store only a SHA-256 hash and cannot recover it. Keep it server-side; it carries full authority over your sub-users.

export GD_KEY="gd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Check what you have to allocate

GET /summary lists your parent packages with free GB. You need a user_package_id from here and enough gb_free on it.

Create a sub-user and use its proxy

The response contains proxy credentials that work immediately against proxy.globedata.io:8080. The customer signs into the dashboard with the email and the dashboard_password you chose.

curl -x "http://sub_8j6hVeUj:DHczgmgZksQNvpKx@proxy.globedata.io:8080" https://api.ipify.org

Authentication

One header on every request. No sessions, no token exchange, no expiry.

Authorization: Bearer gd_<32 alphanumeric chars>

A key inherits the permissions of the account that owns it — it can manage that account's sub-users and nothing else. Keys never expire; revoke them from the dashboard when a key is rotated or leaked. Revocation is immediate.

Key hygiene

One key per consumer. Each key has its own rate-limit bucket, so a batch job can't starve your web app.
Never ship a key to a browser or mobile app. It is a server-side credential.
Lost a key? Revoke and create a new one — the raw value is not recoverable.
Audit: the dashboard shows last_used_at and last_used_ip per key.

Authentication errors

Status	Reason
`401`	Header missing or malformed, key not found, key revoked, account inactive, or (reseller API) the key owner is not a reseller
`403`	Account lacks the required entitlement for that endpoint
`429`	More than 60 requests in the trailing 60 seconds for this key

{ "error": "Unauthorized", "message": "API key has been revoked" }

Reseller API

Create sub-accounts, move GB between them and your parent packages, and read their usage. Hard cap: 200 active sub-users per reseller.

How GB accounting works

Free GB on a parent package is computed live as parent.total − parent.used − Σ(child.allocated). Nothing is decremented at allocation time, so reclaiming a sub-user's unused GB returns it to the pool instantly. A sub-user's traffic is billed to the sub-user's own package.

Proxy usage

There is no proxy SDK and no session API to call. Everything — rotation, stickiness, TTL, geo-targeting — is expressed as suffixes on the username you send in ordinary proxy auth. Any HTTP client that supports http://user:pass@host:port can do all of it.

Protocol	Host	Port	Client scheme
HTTP / HTTPS	`proxy.globedata.io`	`8080`	`http://…`
SOCKS5	`proxy.globedata.io`	`1080`	`socks5h://…` (remote DNS)

sub_8j6hVeUj -country-us -region-california -session-acct42 -ttl-600 └─ base ───┘ └─ where ─────────────────────┘ └─ which IP, for how long ──┘ # Order does not matter — the proxy parses tokens, not positions. # Only the base username and password are mandatory.

Rotating vs sticky

This is the one decision that decides your success rate. There are exactly two modes, and you choose per request by whether you include a -session- token.

Default — no session token

Rotating

A new exit IP for every request. Nothing to manage, nothing to expire.

curl -x "http://sub_8j6hVeUj:PASS@proxy.globedata.io:8080" \ https://api.ipify.org # different IP each run

Use it for anything stateless and high-volume: crawling listings, fetching pages, collecting datasets. Spreading requests across many IPs is exactly what keeps you unblocked.

Add -session-ID

Sticky

The same exit IP for every request carrying that session ID, until the TTL runs out.

curl -x "http://sub_8j6hVeUj-session-acct42-ttl-600:PASS@proxy.globedata.io:8080" \ https://api.ipify.org # same IP for 10 minutes

Use it whenever the target keeps state across requests: logins, carts, checkouts, multi-step forms, anything behind a cookie that is bound to an IP.

The session ID is the identity, not the connection

Stickiness is keyed on the ID string, not on a TCP connection or a client instance. Two different processes sending -session-acct42 share one exit IP. The same process sending -session-a and -session-b gets two different IPs concurrently. That is how you run many isolated identities through one credential.

Session IDs and TTL in detail

Token	Accepts	Behaviour
`-session-ID`	Letters, digits and underscores (`[A-Za-z0-9_]+`). Passed through verbatim — case-sensitive.	Switches the request into sticky mode and names the IP lease. A hyphen ends the token, so never put one inside an ID.
`-ttl-SECONDS`	A positive integer, in seconds.	How long that session ID keeps its IP. Ignored unless a `-session-` token is also present.

TTL is rounded up to whole minutes

You specify seconds; the upstream network leases IPs by the minute, so the value is rounded up to the next minute and clamped to the range 1 minute – 3600 minutes (60 hours). Practical consequences: -ttl-30 and -ttl-60 both mean one minute, and there is no such thing as a 10-second sticky session. Omit -ttl- entirely and the network applies its own default lease.

TTL	Effective lease	Fits
`-ttl-60`	1 minute	A single login or form submission — the shortest useful window.
`-ttl-300`	5 minutes	Search → detail page → add to cart. The common default.
`-ttl-600`	10 minutes	Checkout and multi-step flows with human-speed pauses.
`-ttl-1800`	30 minutes	A logged-in scraping session working through paginated results.
`-ttl-3600`	1 hour	Account automation where an IP change looks like a hijack.
`-ttl-86400`	24 hours	Long-lived per-account identity. Expect the IP to be replaced if the underlying peer disappears.

What happens at expiry: the lease is released and the next request carrying that session ID gets a fresh IP. Nothing errors and you do not have to re-register anything — reusing the ID after expiry simply starts a new lease. A residential peer can also drop before the TTL is up; treat the IP as best-effort for the window, not a guarantee.

Picking session IDs

One ID per logical identity — per end-user account, per shopping cart, per browser profile. Not per request (that is just rotating with extra steps) and not one global ID for your whole fleet (that funnels everything through a single IP).
Derive it deterministically from something you already have — -session-acct_4192, -session-cart_88fa1 — so any worker that picks up the job lands on the same IP without coordination.
Force a new IP by changing the ID, not by waiting. If a session gets blocked, append a counter: acct_4192_v2.
Keep them opaque. IDs are passed to the upstream network verbatim, so do not encode customer emails or anything else sensitive in them.

Geo-targeting

Targeting narrows the pool the exit IP is drawn from. It composes with either rotation mode — a sticky session inside a city, or rotating inside a country, both work.

Token	Format	Notes
`-country-XX`	ISO 3166-1 alpha-2, case-insensitive (`US`, `gb`, `DE`)	The only token that works on its own, and the prerequisite for every token below.
`-state-SLUG`	Region slug: lowercase words joined by underscores — `california`, `new_york`	Requires a country, and is dropped silently without one. A bare two-letter US code (`-state-tx`) is expanded for you as a fallback.
`-city-SLUG`	City slug, same shape — `san_francisco`, `new_york_city`	Requires a country. Send the region too whenever you know it; that is what makes city matching reliable.
`-asn-N`	Numeric ASN — `-asn-3320`	Advanced: pins the exit to one network operator. Requires a country. Combines with sticky sessions.
`-pool-SLUG`	A named pool slug	Only for accounts that have been given one; an unknown slug is rejected by the gateway. Ask support which pool applies to you.
`-port25`	Flag, no value	Routes through the SMTP-capable pool so port 25 is reachable. Requires the mail entitlement on your account; without it the flag is ignored and a real port-25 connection fails. Overrides any other `-pool-`.

Never use a hyphen inside a slug

Hyphens delimit tokens, so -city-new-york parses as a city of new followed by garbage. Underscores are the word separator: -city-new_york_city. Unrecognised or unavailable targeting is dropped rather than rejected, so a request that silently comes out of the wrong country is almost always a malformed slug.

Worked examples

# Rotating, worldwide — a new IP per request curl -x "http://sub_8j6hVeUj:PASS@proxy.globedata.io:8080" https://api.ipify.org # Rotating inside one country curl -x "http://sub_8j6hVeUj-country-US:PASS@proxy.globedata.io:8080" https://api.ipify.org # Rotating inside a city (region included for accuracy) curl -x "http://sub_8j6hVeUj-country-US-state-new_york-city-new_york_city:PASS@proxy.globedata.io:8080" \ https://api.ipify.org # Sticky for 10 minutes — same IP on every call with this session ID curl -x "http://sub_8j6hVeUj-session-acct42-ttl-600:PASS@proxy.globedata.io:8080" https://api.ipify.org # Sticky AND geo-targeted — a stable US IP for one account curl -x "http://sub_8j6hVeUj-country-US-session-acct42-ttl-1800:PASS@proxy.globedata.io:8080" \ https://api.ipify.org # Two concurrent identities, two different IPs, one credential curl -x "http://sub_8j6hVeUj-session-worker_a-ttl-300:PASS@proxy.globedata.io:8080" https://api.ipify.org & curl -x "http://sub_8j6hVeUj-session-worker_b-ttl-300:PASS@proxy.globedata.io:8080" https://api.ipify.org & wait # SOCKS5 (socks5h resolves DNS at the exit, which is what you want) curl -x "socks5h://sub_8j6hVeUj:PASS@proxy.globedata.io:1080" https://api.ipify.org

Prove stickiness works before you build on it: two calls with the same session ID must return the same IP, and two calls with different IDs must not.

A session manager you can copy

The pattern that survives production: map each identity to a stable session ID, rotate the ID on failure, and never let two identities share one.

Limits and timeouts

Limit	Value	What you see
Request timeout	None imposed	Your client owns the deadline — deliberate, so large downloads are not cut off. Always set your own; 60s+ suits residential exits.
Idle tunnel timeout	60 seconds of total silence	A CONNECT tunnel with no bytes in either direction for 60s is closed. Long-poll and idle SMTP sessions need application-level keepalive.
Concurrent connections	50,000 per account	`429 Too many connections`. Concurrency is yours to manage — the proxy rejects rather than queues.
Metering	KB, plus 2 KB overhead per request	Deducted from that credential's package; visible in `/logs` and `/usage`.
Auth cache	Up to 30 minutes	See the warning below.

Credential changes take up to 30 minutes on live traffic

Suspensions, deletions and password rotations are written to the database immediately and are visible over the API at once. The proxy edge caches authentication for up to 30 minutes, so traffic using an old password can keep working that long. Plan rotations and cut-offs around that window.

Proxy error codes

These come from the proxy itself, not from the site you are fetching.

Status	Meaning	Fix
`407`	Proxy authentication required — username or password not recognised.	Check the credential pair. A malformed token can also break the base username: `-city-new-york` makes the whole username unresolvable.
`402`	Your package. No package, all packages expired, or no data remaining — the body says which.	Top up or extend. For a sub-user, allocate GB with POST /subusers/:id/allocate.
`429`	Too many concurrent connections for this account.	Lower client concurrency, and make sure you close responses so tunnels are released.
`502`	Upstream network failure. The response carries an `X-Upstream-Status` header with the real cause.	Retry with backoff. A `502` is never about your balance — a provider-side `402` is deliberately not forwarded as a client `402`.

Best use cases

What this infrastructure is good at, and the settings that make each job work. Rotation strategy is the single biggest factor in success rate — pick it from the job, not from habit.

Use case	Recommended setup	Why
Web scraping at scale catalogues, listings, public datasets	Rotating (no session). Add `-country-XX` only when the content is geo-dependent.	A fresh IP per request spreads the footprint. Pinning a session here concentrates all your requests on one IP and gets it rate-limited.
Price & stock monitoring retail, travel, marketplaces	`-country-XX`, rotating. Switch to a short sticky session (`-ttl-120`) only for multi-step flows like adding to a cart.	Prices and availability are localised, so the exit country decides what you see. Cart and checkout flows break if the IP changes mid-session.
SERP & ad verification	`-country-XX-state-XX-city-NAME`, rotating, and `-hq` when you need the cleanest pool (country-level only).	Search results and ad placements change street by street. City targeting is what makes the check meaningful.
Account operations social media management, multi-account tools	One sub-user per end customer, plus one sticky session ID per account: `-session-acct42-ttl-600`, refreshed on use.	Accounts get flagged when they hop IPs. A stable session ID per account plus per-customer credential isolation keeps one customer's problems out of everyone else's.
AI / ML training data collection	Rotating, high concurrency, generous client timeouts. Watch GB with `GET /summary` before each crawl.	The proxy imposes no timeout — your client controls it, so large document and media fetches are safe. Volume, not latency, is the constraint.
Email & SMTP validation	`-port25` on a mail-enabled account. Ask support to enable the entitlement.	Port 25 only works on the mail pool. Without the entitlement the request is rejected — this cannot be bypassed by naming the pool directly.
Lead generation & enrichment	Scraper API for LinkedIn records; rotating proxies for everything else. Cache aggressively.	Structured records with no parsing or IP management on your side. Each scrape costs 1 request, so caching is money.
White-label resale	A sub-user per customer, one API key per environment, nightly reconciliation, `label` set to your internal customer ID.	Suspend, top up and invoice per customer without touching anyone else. `label` is your join key back to your own billing system.

How to structure your account

Resellers & agencies

One sub-user per customer

The default, and what the API is designed around. Each customer gets isolated credentials, their own GB balance, their own dashboard, and their own usage history.

Suspend one customer for non-payment with a single PATCH, and nobody else notices. Put your CRM's customer ID in label so reconciliation is a lookup, not a guess.

In-house teams

One sub-user per project

Split a single package across crawler-prod, crawler-staging and analytics. You get per-project GB attribution for free and a runaway staging job can only burn its own allocation.

Allocate small and top up on demand — reclaiming unused GB is instant and lossless.

High volume

One sub-user per worker fleet

Give each fleet its own credentials so a misbehaving deployment is visible in /logs immediately and containable without redeploying everything.

Keep concurrency on the client side; the proxy does not queue for you.

Do this, not that

✓ Works well

Allocate small, top up often. Unused GB stays in your pool and is reclaimable at any time.
Reconcile on a schedule — once a night, not on every page load. You have 60 requests per minute per key.
Retry only 429 and 503, with exponential backoff and jitter.
Cache GET /summary for a minute; it changes slowly.
Set generous client timeouts (60s+). Residential exits are slower than datacenter, and the proxy will not cut a request off for you.
Store the dashboard_password you generate at create time — it is never returned again.

✕ Causes problems

Sharing one credential across all customers. No per-customer accounting, and no way to cut off just one.
Sticky sessions for bulk scraping. It defeats rotation and gets that IP blocked.
Retrying 402 or 409. Both mean the server state disagrees with your request; retries will never succeed.
Polling /subusers in a loop to detect changes. You will hit 429; schedule instead.
Assuming instant revocation on live traffic. Proxy auth is edge-cached for up to 30 minutes.
Putting an API key in a browser, mobile app or public repo. It carries full authority over your sub-users.

Pacing rule of thumb

60 requests per minute per key means a full nightly reconciliation of 200 sub-users needs roughly 4 minutes if you touch each one — one list call plus one write per sub-user that needs it, spaced ~1s apart. Only write to the ones that actually changed and it finishes in seconds. See Recipes for a working implementation.

Recipes

Complete, runnable programs for the things resellers actually build.

Onboard a customer in one function

Creates the sub-user, then hands back everything the customer needs: dashboard login and a ready-to-use proxy URL.

Nightly reconciliation of every sub-user

Pull the pool, top up anyone below a threshold, and suspend anyone who is out of GB. Note the pacing — you have 60 requests per minute per key.

Retry correctly around rate limits and billing

The only statuses worth retrying are 429 and 503. A 402 means top up; a 409 means your inputs conflict with server state and will never succeed on retry.

Error reference

Every error is JSON with at least error and message. Validation failures add a details array.

{ "error": "Conflict", "message": "Not enough free GB on parent package (free: 0.80 GB)" }

Status	Meaning	What to do
`400`	Validation failure — see the `details` array	Fix the payload. Do not retry unchanged.
`401`	Authentication failed	Check the header, the key, and that it is not revoked.
`402`	Returned by the proxy, not this API: the package is empty or expired	Allocate GB or extend the package.
`403`	200 sub-user cap reached, missing entitlement, or a reseller-only endpoint	Delete an unused sub-user, or contact support.
`404`	Sub-user not found or not yours; or a charged "not found" scrape	Re-list to confirm the ID.
`409`	Conflict — duplicate email, expired parent package, over-allocation	Reconcile against `GET /summary`. Retrying is futile.
`429`	Your key exceeded 60 req/min. From the proxy, it means too many concurrent connections.	Back off and retry with jitter; for the proxy, lower concurrency.
`500`	Internal error	Retry once; if it persists, contact support.
`502`	Returned by the proxy: upstream network failure. See `X-Upstream-Status`.	Retry with backoff. Never a statement about your balance.

FAQ

Can my sub-users use this API?

No. Sub-users get a dashboard login and proxy credentials, but no API key. Only resellers manage sub-users. A sub-user calling a reseller endpoint gets 403.

Can I hold several API keys at once?

Yes, and you should — one per environment or service. Each key gets its own rate-limit bucket and its own last_used_at audit trail, so revoking one never disturbs the others.

Do dashboard changes and API changes stay in sync?

Yes. Both read and write the same database. Anything you do over the API is visible in the dashboard immediately, and vice versa. The one exception is live proxy authentication, which is edge-cached for up to 30 minutes.

Is there an official SDK?

Not yet. The surface is small enough that any HTTP client — curl, requests, axios, fetch — is a few lines, as the examples on this page show.

What happens to usage history when I delete a sub-user?

DELETE is a soft delete: the dashboard login is blocked, proxy credentials are deactivated, unused GB returns to your parent pool, and the row disappears from list views. Usage records are retained for audit and billing reconciliation.

How does versioning work?

This is v1. We will not make breaking changes to v1 without 30 days' notice and a parallel v2. New optional response fields are not breaking changes — parse defensively.

Are there IP restrictions on API keys?

Not on the keys. Sub-user packages carry an ip_allowlist field for proxy traffic which you can set over the API today; enforcement at the proxy edge ships in a later release.