# Error Handling (/docs/api-reference/error-handling)
When using the Geonode Proxy API, you may encounter various HTTP status codes. Understanding these codes helps you handle errors gracefully and implement robust error handling in your applications.
## HTTP Status Codes
| Status Code | Description | Expanded Description |
| ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 403 | Invalid request configuration. . | This error occurs when the request contains invalid or improperly formatted parameters. The placeholder will include details about which field caused the issue. Common causes include incorrect formatting or unsupported values for fields like country, city, state, or ISP. Please verify that all parameters follow the expected structure and use values listed in the API documentation or supported geo-targeting options. |
| 407 | Authentication error. Please check your authentication settings. | This error indicates that authentication with the proxy server failed. Authentication is required, but the credentials provided were missing, invalid, or insufficient. Common causes include incorrect or missing proxy username/password, misconfigured authentication headers, or using an IP address that hasn't been whitelisted. Please verify that your credentials are correct and that your IP address is authorized to access the proxy if applicable. Refer to the authentication section of the API documentation for setup instructions and troubleshooting tips. |
| 411 | Your account has been blocked. If you think it is a mistake, please contact customer support. | This error means that the user's account has been manually blocked by the system or an administrator. This action is typically taken due to violations of the terms of service, suspicious activity, billing issues, or abuse prevention measures. If you believe this is an error, please contact customer support to review your account status and resolve the issue. |
| 464 | Connection to the specified target is not permitted due to security policies. | This error occurs when the requested connection to a specific host, IP address, or port is blocked due to security or access control policies. Common reasons include attempting to connect to restricted destinations, using unsupported ports, or using protocols that are not allowed (e.g., FTP or SMTP). Ensure that the target address, port, and protocol are supported and comply with the platform's usage policies. If you're unsure or believe the restriction is incorrect, please contact support for clarification. |
| 465 | No proxies available in the selected location. Please choose a different targeting configuration or try again later. | This error indicates that the proxy server was unable to find any available IP addresses that meet the specific geo-targeting requirements (e.g., country, city, ISP) specified in the request. This can occur when demand exceeds supply in a particular region or when targeting criteria are too narrow. To resolve this issue, try adjusting your targeting configuration to be less restrictive or retry your request later. If consistent access to specific regions is critical, please contact support to explore custom proxy allocations or availability options. |
| 466 | You've reached your bandwidth limit. Buy more data or upgrade your plan to continue. | This error indicates that the user has consumed all of the bandwidth allocated in their current plan. When the bandwidth limit is reached, no further requests can be processed until more data is added. To resume usage, you can upgrade your plan or purchase an add-on directly in the user dashboard. |
| 467 | You have reached your session bandwidth limit. | Specified bandwidth limit for this session has been reached. Limit is defined by -limit- parameter of the first session request and can not be changed until session is expired or released. |
| 500 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 517 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 518 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 560 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 561 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 562 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 563 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 564 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 565 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 566 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 567 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
| 569 | Internal error. Please try again. | This error indicates that something went wrong on the server while processing the request. It is not caused by user input or configuration. Please try again. If the issue persists, contact support with your request details so we can investigate. |
## Best Practices
1. **Always Implement Error Handling**
* Never assume requests will succeed
* Handle both expected and unexpected errors
2. **Use Retry Logic**
* Implement exponential backoff for 5xx errors
* Respect rate limits and Retry-After headers
3. **Log Errors Appropriately**
* Include relevant request details
* Don't log sensitive information
4. **User Feedback**
* Provide clear error messages to end users
* Include actionable steps for resolution
## Support
If you encounter persistent errors or need assistance, contact our support team at [Support](https://geonode.com/contact).
***
# Introduction (/docs/api-reference)
Welcome to the Geonode Proxy API! This API allows you to:
* Target specific geolocations (countries, states, cities, and even ISPs).
* Manage sticky sessions to keep a consistent IP across multiple requests.
* Track usage statistics (e.g., bandwidth, session counts).
* Filter proxy types (residential, data center, mobile).
This guide will help you make your first calls, retrieve essential information, and move on to more advanced features—without overwhelming you.
## Prerequisites:
* API Credentials: **Our API uses Basic Authentication, requiring a proxy username and password for access. You must include these credentials in every request using the Authorization header.** *(Base64-encoded string)*
* Service Name: Indicate which specific service plan or tier you're using.
> Note: *Some sections provide a static cURL example rather than a live, testable endpoint—so you won't be able to send requests directly from this page. If you want to try it out, simply copy the cURL command into your terminal (or HTTP client) and insert your real credentials or parameters.*
Please refer to our [user dashboard](https://app.geonode.com/) to find the information mentioned above.
## Basic Workflow:
* Authenticate: Include your proxy username and password in each request using Basic Authentication (via the Authorization header).
* Specify Your Service: Use the appropriate service name in each call so the API applies the correct proxy settings.
* Send Requests: Interact using standard HTTP methods (GET, POST, PUT, etc.).
* Parse JSON Responses: You'll generally receive JSON objects containing the requested data or error details.
For detailed information about handling API errors and implementing robust error handling, please refer to our [Error Handling Guide](/docs/api-reference/error-handling).
***
## Next Steps:
* Explore the Full Reference: Dive deeper to learn how to configure proxy sessions, target specific regions, or gather usage insights.
* Check Plan Limits: Monitor bandwidth and session counts to stay within your plan's capacity.
* Stay Informed: Check our Changelog for updates & and new features. Share your opinion on feature requests.
* Contact Support: If you have any questions or run into issues, reach out to our support team at [hello@geonode.com](mailto:hello@geonode.com).
***
# Change Log (/docs/changelog)
After months of work, we’re excited to introduce our **updated dashboard** — a major release focused on simplicity, speed, and flexibility.\
Below is an overview of the key improvements.
***
## Redesigned Dashboard
The dashboard has been completely reworked for better usability and performance.
* Clean, minimal layout
* Faster navigation
* Intuitive access to essential tools
Everything is now more accessible and built with your feedback in mind.
***
## Proxy Membership
We’ve replaced the old **Proxy Residential Membership** with the new **Proxy Membership** — a unified and flexible way to manage all your proxies.
* Manage both **Residential** and **Datacenter** IPs
* Filter or combine IP types effortlessly
* Simplified structure for all users
For API integration details, see the [API documentation](https://docs.geonode.com/).
***
## Endpoint Generator
Our most requested tool is here — the **Endpoint Generator**.
### Create endpoints in multiple formats
Multiple formats are supported for easy integration.
### Copy or export instantly
Copy endpoints or export them to your preferred format in one click.
### Integrate with your favorite tools
No manual setup — just plug it in and start using it.
***
## Updated Host URL
We’ve updated our host structure to improve consistency.
**Old host:** `premium-residential.geonode.com`
**New host:**
`proxy.geonode.io`
The old hostname will continue to function, but only the new one will appear in the dashboard moving forward.
***
## Feature Request System
Your feedback drives our development.\
With the new **Feature Request Tool**, you can:
* Submit new feature ideas directly from your dashboard
* Vote for the improvements you want most
You’ll find it under **Profile → Feature Request**.
***
## Changelog Access
You’re reading it!\
From now on, every platform update and feature release will appear here, so you can always stay informed.
***
## Revamped API Documentation
The [API documentation](https://docs.geonode.com/) has been fully updated for better clarity and ease of use.
* Improved structure and examples
* Updated endpoints
* More guides coming soon
***
## Under-the-Hood Improvements
We’ve made significant backend enhancements to boost speed, reliability, and stability.
| Area | Improvement |
| --------------- | --------------------------------------------- |
| **Speed** | Faster performance across dashboard and APIs |
| **Latency** | Reduced response times for smoother operation |
| **Reliability** | Higher success rates for proxy connections |
| **Stability** | Optimized infrastructure and bug fixes |
These upgrades work silently to ensure your experience is faster and more dependable.
***
## Try It Out
[Log in now →](https://app.geonode.com/residential-proxies)\
Explore the new dashboard and let us know what you think.
***
*Thank you for being part of our journey — more great updates are on the way!*
# May 2025 (/docs/changelog/may2025)
After months of hard work, we're thrilled to introduce our **updated dashboard** and a major platform upgrade.\
This release focuses on speed, reliability, and a smoother user experience.
***
## New Website & Branding
The new **Geonode website and visual identity** mark a major milestone in our journey.\
This redesign reflects our growth and focuses on developers — with a cleaner layout, faster load times, and improved accessibility.
***
## Proxy Infrastructure 2.0
We’ve launched **Proxy Infrastructure 2.0** — a full rebuild of our global proxy network.
* Significantly reduced latency
* 99 % + success rate across all regions
* Major speed boost for **SOCKS5** users
* Expanded IP pool in key markets like the United States
This upgrade delivers faster, more stable connections and improved reliability worldwide.
***
## Upgraded SOCKS5 Infrastructure
Our SOCKS5 network has been completely re-engineered for improved throughput and connection stability.\
You’ll notice faster response times and fewer dropped sessions across all endpoints.
***
## New Pricing Plans
We’ve introduced three new plans to better fit different use cases:
| Plan | Monthly Price | Included GB | Rate per GB |
| ------------ | ------------- | ----------- | ----------- |
| **Starter** | $50 / month | 50 GB | $1.00 |
| **Growth** | $200 / month | 267 GB | $0.75 |
| **Business** | $500 / month | 1000 GB | $0.50 |
***
## 1 TB Free Trial in Dashboard
Qualified business users can now apply for the **1 TB free trial** directly inside the dashboard — no sales call required.\
Get access, test at scale, and start evaluating performance in minutes.
***
## User-Friendly Billing & Grace Period
Billing and subscription handling have been redesigned for flexibility:
* Failed payment? You now have **5 days** to resolve it before cancellation.
* Cancelled subscription? You can reactivate anytime before the billing period ends.
* Finished plan? You still have **5 days** to restore it and keep unused bandwidth.
***
## Improved Usage Graphs
Usage analytics now include:
* Bandwidth by **hour, day, week, or month**
* Look-back period of up to 31 days
* Clearer trend visualization and comparison
These updates make monitoring and optimization much easier.
***
## Error Handling and Service Codes
Error handling has been simplified and clarified:
* Cleaner error messages
* Fewer, more actionable error codes
See the [updated Error Handling Guide](https://docs.geonode.com/api-reference/error-handling).
***
## Geonode SDK Program Launch
We’ve officially launched the **Geonode SDK Program** — enabling developers to monetize apps across iOS, Android, desktop, smart TVs, and more.\
[Learn more and apply here](https://geonode.com/sdk).
***
## Expanded Event-Based Email Notifications
You’ll now receive clear, event-based notifications for:
* Purchases and upgrades
* Downgrades and usage warnings
* Trial updates and billing issues
Stay informed about every important account event.
***
## Shape the Future of Geonode
Want to help define what comes next?\
[Vote on and suggest new features](https://feedback.geonode.com/) directly through our feedback portal.
# Feature Requests (/docs/guides/feature-request)
Have an idea for a new Geonode feature or an improvement to an existing one?\
You can easily submit your request and explore what other users are suggesting.
***
## Submit Your Feature Request
To request a new feature or enhancement, visit:\
➡️ [Geonode Feature Requests](https://feedback.geonode.com/)
Provide as much detail as possible about the feature, including what problem it solves and how it would improve your workflow.
***
## Why Submit a Feature Request?
* 🧠 **Influence future updates** – Help shape Geonode’s roadmap based on real user needs.
* ⚙️ **Improve functionality** – Suggest enhancements that boost performance, security, or usability.
* 💬 **Collaborate with the community** – Upvote and comment on ideas from other users.
***
## How It Works
1. **Browse existing requests**\
Someone may have already suggested your idea — check first before creating a new one.
2. **Submit a new request**\
Provide a clear title, description, and (if possible) your use case or expected benefit.
3. **Vote and comment**\
Upvote ideas you support and share feedback to help prioritize development.
4. **Track progress**\
Follow the status of your requests as the Geonode team reviews and implements new features.
***
## Final Notes
Geonode values community input — every feature request helps make the platform better.\
Your ideas directly contribute to improving **performance, reliability, and user experience** for everyone.
# Quick Start Guide (/docs/guides)
import BrowsersFaqs from "../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../snippets/support-paragraph.mdx";
***
## 1. Access the User Dashboard
Start by accessing your user dashboard — this is where you manage all proxy settings.
* Open your Dashboard.
* Scroll down to Proxy Configuration.
***
## 2. Get Proxy Credentials from Geonode
Obtain your authentication credentials directly from the dashboard.
* **Username:** Copy your unique API username.
* **Password:** Copy your API password.
***
## 3. Configure Proxy Parameters
Within the Proxy Configuration section, adjust the parameters as needed.
| Parameter | Example | Description |
| ------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| **Endpoint Format** | `hostname:port:username:password` | Connection string format |
| **IP Type** | `-type-datacenter` | Choose between Datacenter or Residential |
| **Gateway** | `192.155.103.209` | Proxy gateway |
| **Geo-Targeting** | `-country-jp`, `-state-tokyo`,
`-as-2501` | Specify region or ASN (state and city cannot be combined) |
| **Protocol** | HTTP / HTTPS | Default port 9000 |
| **Session Type** | — | Rotate or Sticky sessions |
| **Output Format** | — | Customize response format |
See the full guide:\
[How to use the Endpoint Generator to configure proxy parameters](/docs/guides/proxy-service-guide/geo-targeting)
***
## 4. Make Your First API Call
Once your endpoint is configured, generate your first API request.
1. Go to **API Code Generator** in the dashboard.
2. Select your configuration settings.
3. Copy the generated code snippet.
***
## 5. Configure Proxy in Different Browsers or OS
To integrate your proxy on specific platforms, follow one of the setup guides below.
### Desktop Operating Systems
* [Windows 10/11](/docs/guides/desktop-OS/windows)
* [macOS](/docs/guides/desktop-OS/macOS)
### Mobile Operating Systems
* [Android](/docs/guides/mobile-OS/android)
* [iOS](/docs/guides/mobile-OS/ios)
### Browsers
* [Chrome](/docs/guides/browsers/chrome)
* [Edge](/docs/guides/browsers/edge)
* [Brave](/docs/guides/browsers/brave)
* [Firefox](/docs/guides/browsers/firefox)
* [Safari](/docs/guides/browsers/safari)
* [Incognito Mode](/docs/guides/browsers/incognito-mode)
* [Incogniton](/docs/guides/browsers/incogniton)
* [AdsPower](/docs/guides/browsers/adspower)
* [Ghost Browser](/docs/guides/browsers/ghost)
* [GoLogin](/docs/guides/browsers/gologin)
* [Dolphin Anty](/docs/guides/browsers/dolphin-anty)
* [ClonBrowser](/docs/guides/browsers/clonbrowser)
* [MoreLogin](/docs/guides/browsers/morelogin)
* [MultiLogin](/docs/guides/browsers/multilogin)
### Extensions
* [FoxyProxy](/docs/guides/extensions/foxyproxy)
* [Geonode Proxy Manager](/docs/guides/extensions/geonode-proxy-manager)
***
## Conclusion
You’re all set!\
Your Geonode proxy is now configured and ready for use across browsers, operating systems, and API integrations.
***
***
# Service Status (/docs/guides/service-status)
Stay informed about the current operational status of **Geonode services**, including proxy availability, system uptime, and scheduled maintenance.
***
## Service Status Overview
🟢 **Coming Soon**\
A real-time **Service Status Dashboard** is in development.\
It will let you:
* Monitor **system health** in real time
* View **proxy uptime and latency metrics**
* Track **maintenance windows and past incidents**
* Subscribe to **status updates and alerts**
***
## Need Help Right Now?
If you’re currently experiencing connection issues or service interruptions, please reach out to our support team:
➡️ [Contact Geonode Support](https://geonode.com/contact)
Our team is available to help diagnose and resolve issues as quickly as possible.
***
## Stay Updated
Check back soon for the live **status.geonode.com** page —\
your one-stop hub for Geonode uptime, maintenance, and performance insights.
# Subscription, Cancellations, Reactivation and Grace Period (/docs/guides/subscription-cancellations-reactivation-and-grace-period)
This guide explains what happens when you **cancel your Geonode subscription**, how you can **reactivate it**, and what **grace periods** apply.\
Understanding these timelines helps prevent loss of access or unused bandwidth.
***
## Canceling During Your Billing Period
When you cancel your subscription, it remains active until the **end of your current billing cycle**.
* You can continue using the service (including proxy access and any remaining bandwidth) until the period ends.
* You can **reactivate anytime before the billing cycle ends** — this cancels your cancellation and keeps your subscription active without interruption.
***
## After Your Billing Period Ends
Once your billing cycle ends and the subscription is fully canceled:
* You automatically enter a **5-day grace period**.
* During this time, you can **reactivate your subscription** without losing data.
### If you reactivate within the grace period:
* Your subscription is **restored immediately**.
* Any **unused bandwidth** is reinstated.
* Proxy access resumes without delay.
### If you do **not** reactivate within 5 days:
* The subscription remains permanently canceled.
* Any **unused bandwidth is lost** and cannot be recovered.
***
## Failed Payments
If your payment fails:
* Access to proxies is **temporarily paused**.
* You have **5 days** to update your payment method and fix the issue.
* If resolved within 5 days, your subscription continues as normal.
* If not resolved, your subscription may be **canceled** and remaining bandwidth **forfeited**.
***
## Summary
| Scenario | Grace Period | Can Reactivate? | Bandwidth Restored? | Access Status |
| ------------------------------- | ------------ | --------------- | ------------------- | ------------------ |
| **Manual Cancellation** | ✅ 5 days | ✅ Yes | ✅ Yes | Temporarily Paused |
| **End of Billing Period** | ✅ 5 days | ✅ Yes | ✅ Yes | Inactive |
| **Failed Payment (Unresolved)** | ❌ | ❌ No | ❌ No | Canceled |
***
If you need help managing your subscription or reactivating access, please contact:\
➡️ [Geonode Support](https://geonode.com/contact)
# Support (/docs/guides/support)
## Geonode Community and Support
Join the Geonode Community to learn, share, and connect with proxy users at all experience levels.\
Get access to helpful guides, expert tips, and support from the Geonode team.
💬 [Join us on Discord](https://discord.com/invite/32RXgzgeAf) to get started, meet other users, and stay up to date with the latest in proxy services.
***
## Contact Methods
If you need help or want to reach our support team, you can contact us using one of the methods below.
### Email
Reach out to us directly at [hello@geonode.com](mailto:hello@geonode.com).\
Use this for general inquiries, technical issues, or billing questions.
***
### Contact Form
Submit your request using our [Contact Form](https://geonode.com/contact).\
Recommended for non-urgent questions, suggestions, or feedback.
***
### Book a Call
Schedule a 30-minute support call with our team through [Calendly](https://calendly.com/maria-geonode/30min).\
Perfect for detailed troubleshooting or guided onboarding.
***
Our support team is available around the clock to help with technical issues,
billing, or account management.
# Useful Links (/docs/guides/useful-links)
This page provides a quick overview of key Geonode resources — manage your proxies, stay updated, and get support whenever needed.
***
## Geonode Dashboard
Your main control panel for managing proxies, monitoring usage, and configuring account settings.\
➡️ [Access the Geonode Dashboard](https://app.geonode.com/proxies)
***
## Discord Community
Join the Geonode community to connect with other users, get real-time help, and receive product updates.\
➡️ [Join the Geonode Discord](https://discord.com/invite/32RXgzgeAf)
***
## Geonode Blog
Read articles, tutorials, and insights from the Geonode team to enhance your proxy experience.\
➡️ [Visit the Blog](https://geonode.com/blog)
***
## Contact Support
Need help? Reach out to the Geonode support team for personalized assistance.\
➡️ [Contact Support](https://geonode.com/contact)
***
## Subscription Plans
Compare available proxy plans and find the best option for your needs.\
➡️ [View Subscription Plans](https://geonode.com/1TB-program)
***
> \[!NOTE]\
> Keep this page bookmarked for quick access to key Geonode resources.\
> Our support team is available 24/7 to help with any questions or issues.
# Verify Proxy Connection (/docs/guides/verify-proxy-connection)
import ProxyOs from "../../snippets/proxy-os.mdx";
import BrowsersFaqs from "../../snippets/browsers-faqs.mdx";
import SupportParagraph from "../../snippets/support-paragraph.mdx";
You can verify your proxy connection in two ways:
* Using an online verification tool
* Using the command line (cURL)
***
## Method 1: Using an Online Tool
### Step 1: Check Your Current IP Address
Before enabling your proxy, check your current IP address.
1. Visit [IP API](https://ip-api.com/).
2. Note your IP address for reference.
### Step 2: Connect to Your Proxy
Set up and configure your proxy based on your device or browser.\
Follow the setup guides for your platform below:
### Step 3: Verify Your New IP Address
Once connected to the proxy:
1. Go back to [IP API](https://ip-api.com/).
2. Verify if the displayed IP address matches your proxy location.
3. If the IP has changed, your proxy connection is active.
***
## Method 2: Using the Command Line (cURL)
You can also verify the proxy connection through the command line using `curl`.
```bash
curl -x proxy.geonode.io:9000 http://ip-api.com
```
# Code Examples (/docs/scraper-api/code-examples)
These examples call `POST /v1/extract` in synchronous mode and print the extracted Markdown. Before running them, set your Scraper API base URL and API key.
```bash
export SCRAPER_API_BASE_URL="https://scraper.geonode.io"
export GEONODE_SCRAPER_API_KEY="YOUR_API_KEY"
```
## cURL
Use this example when you want to test the API from a terminal before writing application code.
```bash
curl -X POST "$SCRAPER_API_BASE_URL/v1/extract" \
-H "X-Api-Key: $GEONODE_SCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["markdown"],
"render_js": false,
"processing_mode": "sync"
}'
```
## Python
This example uses Python's standard library so you do not have to install any extra packages.
```python
import json
import os
from urllib import request, error
base_url = os.environ["SCRAPER_API_BASE_URL"]
api_key = os.environ["GEONODE_SCRAPER_API_KEY"]
payload = {
"url": "https://example.com",
"formats": ["markdown"],
"render_js": False,
"processing_mode": "sync",
}
req = request.Request(
f"{base_url}/v1/extract",
data=json.dumps(payload).encode("utf-8"),
headers={
"X-Api-Key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
try:
with request.urlopen(req, timeout=60) as response:
result = json.loads(response.read().decode("utf-8"))
print(result["data"]["markdown"])
except error.HTTPError as exc:
body = exc.read().decode("utf-8")
print(f"Request failed with HTTP {exc.code}: {body}")
```
## Node.js
This example uses the built-in `fetch` API available in current Node.js versions.
```javascript
const baseUrl = process.env.SCRAPER_API_BASE_URL;
const apiKey = process.env.GEONODE_SCRAPER_API_KEY;
const response = await fetch(`${baseUrl}/v1/extract`, {
method: "POST",
headers: {
"X-Api-Key": apiKey,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com",
formats: ["markdown"],
render_js: false,
processing_mode: "sync",
}),
});
const result = await response.json();
if (!response.ok) {
throw new Error(`Request failed with HTTP ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result.data.markdown);
```
# Error Handling (/docs/scraper-api/error-handling)
The Scraper API returns standard HTTP status codes and JSON error bodies. Handle both validation errors and extraction errors in your client, because a request can fail before extraction starts or after the API tries to process the target page.
## HTTP Status Codes
| HTTP status | Meaning | Returned by |
| ----------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `200` | Synchronous extraction, map request, job lookup, statistics request, webhook lookup, or health check succeeded. | Extract (sync), map, get job, get batch/crawl status, list jobs, statistics, webhook get/list, health |
| `201` | Webhook subscription was created. | Create webhook |
| `202` | Async extraction, batch, or crawl job was accepted, or a running job cancellation was accepted. | Extract (async), create batch, create crawl, cancel batch, cancel crawl |
| `204` | Webhook subscription was deleted. | Delete webhook |
| `400` | Invalid request. | Extract, map |
| `401` | API key is missing or invalid. | All authenticated endpoints |
| `402` | Payment required or insufficient request balance. | Extract, map, crawl |
| `404` | Job, webhook, or other requested resource was not found. | Get job, get batch/crawl status, cancel batch/crawl, webhook get/update/delete/deliveries |
| `408` | Map request timed out during URL discovery. | Map |
| `409` | Batch or crawl job cannot be cancelled in its current state. | Cancel batch, cancel crawl |
| `422` | Validation error or extraction failed. | Extract (body validation and extraction errors), create batch, create crawl, create/update webhook |
| `429` | Request throttled or work concurrency limit reached. | Extract, create batch, create crawl, map |
| `500` | Internal server error. | Extract, map, webhook create/get/update/delete/list/deliveries |
| `502` | Billing service returned an upstream error. Retryable depends on the billing error. | Extract, map, create crawl |
| `503` | Service or billing service temporarily unavailable. | Extract, map, create batch, create crawl |
| `504` | Synchronous extraction timed out waiting for the browser worker. Retryable. | Extract (sync) |
## Validation Error
Validation errors can return a `detail` array. This usually means the request body does not match the expected schema, such as an invalid URL or unsupported value.
```json
{
"detail": [
{
"type": "value_error",
"loc": ["body", "url"],
"msg": "Value error, URL must contain a valid hostname.",
"input": "not-a-url"
}
]
}
```
## Extraction Error
Extraction failures return an `error` object and `tokens_charged`.
```json
{
"error": {
"code": "UNPROCESSABLE_CONTENT",
"message": "The target page could not be extracted.",
"retryable": false,
"details": null
},
"tokens_charged": 0
}
```
The response field is currently named `tokens_charged` in the API schema. In Scraper API docs and billing language, treat this value as the number of requests charged.
## Extraction Error Codes
Extraction error codes include:
* `RATE_LIMITED`
* `WORK_CONCURRENCY_LIMITED`
* `WORK_CONCURRENCY_LEASE_EXPIRED`
* `TEMPORARY_BLOCK`
* `NETWORK_ERROR`
* `CAPTCHA_CHALLENGE`
* `PERMANENT_BLOCK`
* `INVALID_URL`
* `UNPROCESSABLE_CONTENT`
* `AUTH_REQUIRED`
* `TIMEOUT`
* `PAYMENT_REQUIRED`
* `INTERNAL_ERROR`
* `PROXY_ERROR`
Use the `retryable` field to decide whether a retry may help. For retryable failures, use exponential backoff and avoid retrying in a tight loop.
The OpenAPI schema includes `429` responses, but no public numeric rate limit is specified in the current contract. If you receive `429`, slow down the client and retry after a delay.
# FAQs (/docs/scraper-api/faq)
## What is the Scraper API?
The Scraper API is a hosted extraction API. You send it a URL, and it returns clean Markdown or HTML from the target page. It also handles proxy routing, geo-targeting, JavaScript rendering, and anti-bot handling.
## What is one credit?
One credit means one Scraper API request. In these docs, you'll usually see the word request instead of credit because the dashboard and pricing model are request-based.
One successful page extraction uses one request. Batch jobs count each successfully extracted URL as one request, and crawl jobs count each successfully extracted page as one request.
There are no extra request multipliers for JavaScript rendering, proxy type, geo-targeting, or requesting both Markdown and HTML.
## What happens when I run out of free requests?
When you use all free requests for the billing month, new extraction requests stop working until you add paid requests, upgrade to a subscription, or wait for the next monthly renewal.
The API can return `402` when your account does not have enough available requests.
## Do free requests roll over?
No. Free tier requests renew every billing month and expire at the end of that month. Unused free requests do not roll over.
## Do subscription requests roll over?
Yes. Unused subscription requests roll over to the next month with no rollover cap while your subscription remains active.
## Do Pay as you Go requests expire?
No. Pay as you Go requests do not expire. They are a good fit when your scraping workload is occasional or bursty.
## Does JavaScript rendering cost more?
No. JavaScript rendering does not cost extra requests. A successful extraction with `render_js: true` still uses one request.
JavaScript rendering can take longer, so it is best to start with `render_js: false` and enable it only when the returned content is incomplete.
## How is this different from using proxies directly?
With proxies directly, you still have to write the scraper, manage retries, choose when to run a browser, parse HTML, handle noisy pages, and normalize output.
The Scraper API sits above that work. You send a URL and get extracted Markdown or HTML back. It is a better fit when you want page content quickly and do not want to maintain browser or proxy orchestration yourself.
Direct proxies are still useful when you need full control over the browser, request flow, cookies, sessions, or a custom scraper pipeline.
## What sites can I scrape?
You can use the Scraper API with public webpages that your account is allowed to access. It works well with static pages, documentation pages, articles, product pages, and many JavaScript-rendered pages.
Complex sites can still return noisy output. Some sites include large navigation menus, tracking links, ads, images, recommendations, cookie banners, or challenge pages in the extracted content. In those cases, inspect the returned Markdown or HTML and add post-processing if your workflow needs cleaner fields.
Always follow the target site's terms, applicable laws, and your own compliance requirements.
## Why is my result missing content?
The most common reason is that the page loads content with JavaScript after the initial HTML response. Try the same request with `render_js: true`.
```json
{
"url": "https://quotes.toscrape.com/js/",
"formats": ["markdown"],
"render_js": true
}
```
If the result is still incomplete, the site may require a user interaction, a longer wait condition, a login, or a site-specific scraping strategy.
## Why is the output noisy?
The API extracts raw page content. Many modern sites include navigation, filters, image data, tracking links, cookie banners, recommendations, and footer content in the page itself. The API may return some of that content because it exists in the source page.
For LLM, search, or analytics workflows, it is a good idea to test a few pages from the same target site and add your own cleanup step if needed.
## Can I choose the country used for scraping?
Yes. Pass `proxy.country` with a two-letter ISO country code.
```json
{
"proxy": {
"country": "US",
"type": "residential"
}
}
```
If you omit `proxy`, the API applies default residential proxy routing and tries to infer a useful country from the target URL when possible.
## Which proxy types are supported?
The extraction endpoint supports `residential`, `datacenter`, and `mix`.
```json
{
"proxy": {
"country": "US",
"type": "residential"
}
}
```
## Can I pass custom headers?
Yes. Use the `headers` object for headers that should be included in the target extraction request.
```json
{
"url": "https://example.com",
"formats": ["markdown"],
"headers": {
"Accept-Language": "en-US,en;q=0.9"
}
}
```
Do not send your Geonode API key inside this object. Your API key belongs in the `X-Api-Key` header sent to the Scraper API.
## Can I scrape pages that require login?
The public extraction schema supports custom headers, but it does not provide a full browser session management interface for logging in, clicking through flows, or maintaining user state across many pages. You can use the `headers` field to send authentication cookies or tokens with each extraction request.
If your use case requires authenticated scraping beyond what custom headers can provide, contact support so the team can recommend the right setup.
## Should I use sync or async mode?
Use `sync` mode for quick pages when you want the result in the same HTTP response.
Use `async` mode for slower pages, JavaScript-heavy pages, and workflows where you want to start the extraction and poll for the result later.
## What is the map endpoint for?
The map endpoint discovers URLs under a base URL by reading sitemaps and links from the seed page.
```json
{
"url": "https://quotes.toscrape.com/",
"search": "author",
"include_subdomains": false,
"ignore_query_parameters": true
}
```
The `search` field filters URLs the API already discovered. It does not run a Google search or query an external search engine.
## Where can I see my usage?
Open the Geonode dashboard and check your Scraper API request balance. Use the dashboard UI as the source of truth for your current balance and plan details.
## Where can I find the full API reference?
Read the full Scraper API reference here:
[Open the Scraper API Reference](/docs/scraper-api/reference)
# API Overview (/docs/scraper-api)
The Geonode Scraper API helps you extract, discover, and process web content without managing browsers, proxies, or scraping infrastructure.
Send a URL and receive structured content as Markdown or HTML. The API also supports JavaScript rendering, geo-targeting, batch processing, website crawling, and webhook notifications.
## What You Can Do
With the Scraper API, you can:
* Extract content from webpages
* Process multiple URLs in batch jobs
* Crawl websites and discover pages
* Receive webhook notifications when jobs complete
* Use geo-targeted proxy routing
* Extract content from JavaScript-powered websites
* Retrieve links found on webpages
## Available APIs
Choose the API that best matches your use case.
| API | Use When |
| ---------- | -------------------------------------------------------- |
| Extraction | You already know the URL and want to extract its content |
| Batch | You have multiple URLs that need to be processed |
| Crawl | You want to discover and extract pages across a website |
| Webhooks | You want to receive notifications when jobs complete |
## When to Use the Scraper API
Use the Scraper API when you need:
* Clean Markdown or HTML output
* JavaScript rendering
* Geo-targeted extraction
* Managed proxy infrastructure
* Batch processing
* Website crawling
* Asynchronous processing
* Webhook notifications
If you need complete control over browser automation, request handling, or custom scraping logic, consider using the Geonode Proxy API instead.
## Getting Started
If you're new to the Scraper API, start with the Quick Start Guide.
The Quick Start Guide covers:
1. Creating an API key
2. Sending your first request
3. Understanding responses
4. Exploring available APIs
## Next Steps
Continue to the **Quick Start Guide** to make your first request and explore the Scraper API.
# Pricing and Requests (/docs/scraper-api/pricing-and-requests)
Scraper API pricing is based on requests. One successfully extracted page uses one request from your balance. There are no request multipliers for JavaScript rendering, proxy type, geo-targeting, or output format.
## Request Counting
The request model is intentionally simple for page extraction work:
* One page extraction equals one request.
* A batch job counts each successfully extracted URL as one request.
* A crawl job counts each successfully extracted page as one request.
* JavaScript rendering does not cost extra requests.
* Requesting Markdown, HTML, or both does not cost extra requests.
* Geo-targeting does not cost extra requests.
* Failed extraction requests are not charged.
* Authentication errors, validation errors, and requests rejected before extraction are not charged.
Some dashboard, API, or billing surfaces may still use older token or credit naming, such as `tokens_charged`, `estimated_tokens`, `tokens_charged_total`, or `tokens_reserved`. For Scraper API billing, read those values as charged, estimated, or reserved requests.
## Endpoint Usage
Not every API endpoint extracts a page. Use this table to understand how each endpoint category relates to request balance.
| Endpoint category | Request balance behavior |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Single-page extraction | A successful `POST /v1/extract` extraction uses one request. |
| Async extraction | The completed extraction uses one request when the page is successfully extracted. |
| Batch extraction | Each successfully extracted URL in the batch uses one request. |
| Crawl jobs | Each successfully extracted crawled page uses one request. |
| Map | Discovers URLs only. The response does not include `tokens_charged`; use the dashboard to confirm overall balance changes. |
| Statistics, webhooks, job lookup, and health checks | These endpoints do not extract page content. They are used to manage, inspect, or monitor Scraper API work. |
## Free Tier
The free tier includes 1,500 requests every month. You do not need a credit card to start using the free tier.
Free tier requests:
* Renew every billing month.
* Expire at the end of the billing month.
* Do not roll over to the next month.
* Stop working when the monthly free allowance runs out, unless you upgrade or add paid requests.
## Subscription Plans
Subscription plans include a monthly request allowance. Unused subscription requests roll over to the next month with no rollover cap while your subscription remains active.
Use the Geonode dashboard to see the currently available subscription tiers, included monthly requests, and current prices. The dashboard is the source of truth for plan availability and billing details.
Subscription requests:
* Renew every billing month.
* Roll over when unused.
* Stay available while the subscription remains active.
* Can be combined with Pay as you Go requests if your account has both balances.
## Pay as you Go
Pay as you Go lets you buy request top-ups without committing to a subscription. Pay as you Go requests are prepaid and do not expire.
Use the Geonode dashboard to see the available top-up sizes and current prices for your account.
Pay as you Go requests:
* Are prepaid.
* Do not expire.
* Can be used for bursty workloads.
* Remain available even if you do not use the API every month.
## What Happens When You Run Out
If you run out of available requests, the API returns `402`. Add more requests from the dashboard, buy a Pay as you Go top-up, or upgrade to a subscription plan.
```json
{
"code": "PAYMENT_REQUIRED",
"message": "Insufficient request balance.",
"correlation_id": "req_...",
"retryable": false
}
```
The exact message may vary, but the response tells you that the request could not be processed because the account does not have enough available requests.
## Checking Usage
You can check remaining requests in the Geonode dashboard. Use the dashboard when you need to confirm:
* Remaining free requests for the current billing month.
* Current subscription allowance and rollover balance.
* Pay as you Go balance.
## Billing Examples
If you extract one static page as Markdown, it uses one request.
```json
{
"url": "https://example.com",
"formats": ["markdown"],
"render_js": false
}
```
If you extract the same page as Markdown and HTML, it still uses one request.
```json
{
"url": "https://example.com",
"formats": ["markdown", "html"],
"render_js": false
}
```
If you render a JavaScript-heavy page before extracting it, it still uses one request.
```json
{
"url": "https://quotes.toscrape.com/js/",
"formats": ["markdown"],
"render_js": true
}
```
If the extraction fails, the failed extraction is not charged.
For batch and crawl jobs, check `token_summary.tokens_charged_total` on the job status response to see how many requests have been charged so far. `token_summary.tokens_reserved` shows the amount still reserved for queued or processing items.
# Quick Start Guide (/docs/scraper-api/quick-start)
This guide helps you get started with the Geonode Scraper API in a few minutes.
## Get Your API Key
1. Sign in to your Geonode account.
2. Open the Dashboard.
3. Navigate to the API Keys section.
4. Create or copy an existing API key.
## Authentication
All Scraper API requests require the `X-Api-Key` header.
```bash title="request.sh"
curl -H "X-Api-Key: YOUR_API_KEY"
```
Replace `YOUR_API_KEY` with your actual API key.
## Choose an API
| API | Use When |
| ---------- | ------------------------------------------------------- |
| Extraction | You want to extract content from one or more webpages |
| Batch | You have multiple URLs to process in a single job |
| Crawl | You want to discover and extract pages across a website |
| Webhooks | You want notifications when jobs complete |
## Next Steps
Choose the API that matches your use case and follow the guides in that section.
# Reference (/docs/scraper-api/reference)
Use the API Reference when you already know what you want to build and need the exact endpoint for a specific operation.
If you're new to the Scraper API, start with the Quick Start Guide.
## Base URL
All API requests use the following base URL:
```text
https://scraper.geonode.io
```
You can store it as an environment variable:
```bash title="request.sh"
export SCRAPER_API_BASE_URL="https://scraper.geonode.io"
```
## Authentication
All Scraper API requests require an API key.
Send your API key using the `X-Api-Key` request header.
```http
X-Api-Key: YOUR_API_KEY
```
You can store the API key as an environment variable:
```bash title="request.sh"
export GEONODE_SCRAPER_API_KEY="YOUR_API_KEY"
```
Keep your API key private and never expose it in frontend applications, public repositories, screenshots, or logs.
## API Categories
The Scraper API is organized into the following categories.
| Category | Purpose |
| ---------- | ------------------------------------------- |
| Extraction | Extract content from webpages |
| Batch | Process multiple URLs in a single job |
| Crawl | Discover and extract pages across a website |
| Map | Discover URLs from a website |
| Statistics | Retrieve usage statistics |
| Webhooks | Receive notifications when jobs complete |
| System | Service health and status |
## Endpoints
### System
| Method | Endpoint | Description |
| ------ | --------- | ----------------------- |
| `GET` | `/health` | Check API health status |
### Extraction
| Method | Endpoint | Description |
| ------ | ---------------------- | ------------------------------ |
| `POST` | `/v1/extract` | Extract content from a webpage |
| `GET` | `/v1/extract/{job_id}` | Retrieve an extraction job |
| `GET` | `/v1/extract/jobs` | List extraction jobs |
### Batch
| Method | Endpoint | Description |
| -------- | -------------------- | -------------------- |
| `POST` | `/v1/batch` | Start a batch job |
| `GET` | `/v1/batch/{job_id}` | Retrieve a batch job |
| `DELETE` | `/v1/batch/{job_id}` | Cancel a batch job |
### Map
| Method | Endpoint | Description |
| ------ | --------- | ---------------------------- |
| `POST` | `/v1/map` | Discover URLs from a website |
### Crawl
| Method | Endpoint | Description |
| -------- | -------------------- | -------------------- |
| `POST` | `/v1/crawl` | Start a crawl job |
| `GET` | `/v1/crawl/{job_id}` | Retrieve a crawl job |
| `DELETE` | `/v1/crawl/{job_id}` | Cancel a crawl job |
### Statistics
| Method | Endpoint | Description |
| ------ | ---------------- | ------------------------- |
| `GET` | `/v1/statistics` | Retrieve usage statistics |
### Webhooks
| Method | Endpoint | Description |
| -------- | ----------------------------------------- | ----------------------- |
| `POST` | `/v1/webhooks` | Create a webhook |
| `GET` | `/v1/webhooks` | List webhooks |
| `GET` | `/v1/webhooks/{webhook_id}` | Retrieve a webhook |
| `PATCH` | `/v1/webhooks/{webhook_id}` | Update a webhook |
| `DELETE` | `/v1/webhooks/{webhook_id}` | Delete a webhook |
| `POST` | `/v1/webhooks/{webhook_id}/rotate-secret` | Rotate a webhook secret |
| `GET` | `/v1/webhooks/{webhook_id}/deliveries` | List webhook deliveries |
## Next Steps
Choose the endpoint category that matches your use case and open its guides or endpoint reference pages.
# Retrieve Available Geo-locations (/docs/api-reference/available-geo-locations/get)
Retrieve a comprehensive list of all available geo-locations, including countries, cities, states, and ASNs that you can use for geo-targeting your proxy requests.
## Request
```bash
curl -X GET "https://monitor.geonode.com/services/RESIDENTIAL-PREMIUM/targeting-options" \
-u geonode_username:password
```
## Response
### 200 Success
List of available geo-locations retrieved successfully.
#### Response Structure
The response is an array of country objects, each containing:
| Field | Type | Description |
| ---------------- | ------ | --------------------------------------------------- |
| `code` | string | ISO 3166-1 alpha-2 country code |
| `name` | string | Full country name |
| `cities` | object | City-level targeting options |
| `cities.prefix` | string | Prefix to use for city targeting (e.g., "-city-") |
| `cities.options` | array | List of available cities |
| `states` | object | State-level targeting options |
| `states.prefix` | string | Prefix to use for state targeting (e.g., "-state-") |
| `states.options` | array | List of available states |
| `asns` | object | ASN-level targeting options |
| `asns.prefix` | string | Prefix to use for ASN targeting (e.g., "-asn-") |
| `asns.options` | array | List of available ASNs |
#### Example Response
```json
[
{
"code": "AF",
"name": "Afghanistan",
"cities": {
"prefix": "-city-",
"options": [
{
"code": "kabul",
"name": "Kabul"
}
]
},
"states": {
"prefix": "-state-",
"options": [
{
"code": "kabul",
"name": "Kabul"
}
]
},
"asns": {
"prefix": "-asn-",
"options": [
{
"code": "131284",
"name": "AS131284 Etisalat Afghan"
}
]
}
}
]
```
# Overview (/docs/api-reference/geo-targeting/geo-targeting-options)
Geo-targeting is one of the most powerful features of the Geonode Proxy API. It allows you to route your proxy requests through specific geographic locations, giving you precise control over where your traffic appears to originate from. This is essential for location-specific testing, content access, market research, and compliance with regional requirements.
## What is Geo-Targeting?
Geo-targeting enables you to specify the geographic location of the IP address that will be used for your proxy requests. Instead of getting a random IP from anywhere in the world, you can target:
* **Countries**: Route traffic through specific countries (e.g., United States, United Kingdom, Germany)
* **States/Regions**: Narrow down to specific states or provinces within a country
* **Cities**: Target specific cities for even more precise location control
* **ISPs/ASNs**: Route through specific Internet Service Providers or Autonomous System Numbers
## Why Use Geo-Targeting?
Geo-targeting allows you to route your proxy requests through specific geographic locations, giving you control over where your traffic appears to originate from.
## Targeting Levels
Geonode supports multiple levels of geo-targeting, from broad to highly specific:
### Country-Level Targeting
The broadest level of targeting. Simply append `-country-` to your username to route traffic through a specific country. This is ideal when you need traffic from a particular country but don't need more specific location control.
**Example**: `username-country-US` routes traffic through the United States.
### State-Level Targeting
For countries with states or provinces, you can target specific regions. This is useful when you need traffic from a particular state but don't need city-level precision.
**Example**: `username-country-US-state-california` routes traffic through California.
You cannot target both state and city at the same time. Choose either
state-level or city-level targeting for your requests.
### City-Level Targeting
The most precise geographic targeting option. Target specific cities within a country for maximum location accuracy.
**Example**: `username-country-US-city-newyork` routes traffic through New York City.
### ISP/ASN-Level Targeting
For advanced use cases, you can target specific Internet Service Providers or Autonomous System Numbers. This is useful when you need traffic from a particular ISP or network infrastructure.
**Example**: `username-type-residential-country-US-asn-12345` routes traffic through a specific ASN in the United States.
## Available Endpoints
This section provides endpoints for different geo-targeting options:
* **[Perform Country Targeting](/docs/api-reference/geo-targeting/get-country/get)**: Route traffic through specific countries
* **[Perform State Targeting](/docs/api-reference/geo-targeting/get-state/get)**: Target specific states or regions
* **[Perform City Targeting](/docs/api-reference/geo-targeting/get-city/get)**: Target specific cities
* **[Perform ISP/ASN Targeting](/docs/api-reference/geo-targeting/get-isp/get)**: Route through specific ISPs or ASNs
## Finding Available Locations
Before you can target a location, you need to know what locations are available. Use the [Retrieve Available Geo-locations](/docs/api-reference/available-geo-locations/get) endpoint to get a comprehensive list of:
* Available countries and their codes
* Cities within each country
* States/regions within each country
* ISPs and ASNs available in each location
## Best Practices
Before targeting a location, verify that it's available using the available geo-locations endpoint. Choose the appropriate level of targeting for your needs—use country-level if you don't need more specific location control.
Use ISO 3166-1 alpha-2 country codes (e.g., `US`, `GB`, `DE`) for country
targeting. City and state names should match the exact format provided in the
available locations list.
# Perform strict matching (/docs/api-reference/geo-targeting/perform-strict-matching)
### Overview
Previously, when you requested an IP address from a specific geolocation and none were available, the system would silently fall back to a similar location in the same country. We are changing this behavior to make it explicit and give you more control:
1. **Strict Matching (Default)**
* By default, if your requested geolocation is unavailable, you will receive an error indicating that no IP address is available (`proxy-error`).
* This means the system will **not** automatically provide an alternative IP from another location.
2. **Fallback with Flag**
* If you **want** to allow fallback (i.e., you want an IP from another location in the same country when your exact requested location is unavailable), you must explicitly enable it by setting the flag `-strict-off`.
### URL Flag Usage
You can now include one of the following flags in your username string:
* `-strict-on`
* Forces strict matching. If there are no available IPs for the specified location, the system returns a `proxy-error`.
* This is the **default** if you do **not** specify any strict flag.
* `-strict-off`
* Allows fallback. If the exact location is unavailable, the system will return another IP from the same country (if available).
#### Syntax
```
geonode_-type--country--asn--strict-on:
```
or
```
geonode_-type--country--asn--strict-off:
```
> **Note:**
>
> * You can apply `-strict-on` or `-strict-off` to any combination of geo-targeting flags (e.g., `country`, `city`, `state`, `asn`), but we recommend always including a `-country-` in your query.
> * The `asn` flag must be used **with** the `country` flag; otherwise, you will receive an error.
### Example Usage
#### 1. Fallback Enabled (`-strict-off`)
If you want to **allow** fallback to a different location in the same country when your requested location is unavailable:
```bash
curl -x : \
-U "geonode_username-type-residential-country-fr-asn-3215-strict-off:your_password" \
--url "http://ip-api.com"
```
* Here, you requested a French (`country-fr`) IP that belongs to ASN `3215`.
* With `-strict-off`, if no IP is available exactly for ASN 3215 in France, the system will return a **different** IP from France.
#### 2. Strict Matching (`-strict-on`)
If you want **strict** matching for the exact country/ASN combination:
```bash
curl -x : \
-U "geonode_username-type-residential-country-fr-asn-3215-strict-on:your_password" \
--url "http://ip-api.com"
```
* If no IP is available that exactly matches France + ASN 3215, the system will return:
```json
{ "proxy-error": "country-fr-asn-3215 target was not found" }
```
### Error Cases
1. **No Exact Location Found (Strict Matching)**
* **Error**: `{"proxy-error":"country-fr-asn-3215 target was not found"}`
* Occurs when using `-strict-on` (or default strict matching) and the system cannot find an IP for that location.
2. **`asn` Without `country`**
* **Error**: `{"proxy-error":"ASN should be used with country."}`
* The `asn` flag must be paired with a specific country code.
3. **`-strict-on` or `-strict-off` Without Any Geo-Targeting Flag**
* **Error**: If you use `-strict-on` or `-strict-off` **without** specifying any location or ASN.
* You must include at least one geo-targeting parameter (e.g. `-country-xx`, `-asn-xxxxx`, etc.) for the request to make sense.
### Summary
* **Default**: Strict matching is enforced (the system does **not** fall back to another location).
* **Use `-strict-off`**: to allow fallback to a similar location within the same country.
* **Always Pair `asn` With `country`**: `-asn-50543` must be accompanied by `-country-xx`.
* **Error Handling**: You will receive JSON error responses if no IP is found under strict conditions or if flags are incorrectly combined.
By explicitly controlling strict matching via `-strict-on` or `-strict-off`, you can now decide whether to **always** require a specific location or to **allow** fallback within the same country in case your requested location is unavailable.
# IP Type Filtering (/docs/api-reference/ip-filter/get)
Filter proxy IPs by type to match your specific requirements. You can choose between residential IPs, datacenter IPs, or a mix of both.
You can filter IPs by type using the `-type-` parameter in your username:
* **Residential**: Real IPs from home users
* **Datacenter**: IPs from data centers
* **Mixed**: Combination of both types
## Request
```bash
curl -x "http://proxy.geonode.io:" \
--user "-type--country-:" \
--url "http://ip-api.com/json" \
--header "Accept: application/json"
```
## Response
### 200 Success
Successfully filtered IPs based on type.
#### Response Fields
| Field | Type | Description |
| --------------- | ------- | ------------------------------------------------------ |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The continent where the IP is located |
| `continentCode` | string | The continent code |
| `country` | string | The country where the IP is registered |
| `countryCode` | string | The country code in ISO 3166-1 alpha-2 format |
| `region` | string | The regional subdivision (state/province) |
| `regionName` | string | The full name of the region |
| `city` | string | The city associated with the IP address |
| `district` | string | The district or subdivision of the city |
| `zip` | string | The postal or ZIP code of the location |
| `lat` | number | Latitude coordinate of the location |
| `lon` | number | Longitude coordinate of the location |
| `timezone` | string | Time zone in which the IP is located |
| `offset` | integer | Time offset from UTC in seconds |
| `currency` | string | Local currency used in the country |
| `isp` | string | The name of the Internet Service Provider (ISP) |
| `org` | string | The name of the organization associated with the IP |
| `as` | string | The Autonomous System (AS) number and name |
| `asname` | string | The full Autonomous System (AS) name |
| `mobile` | boolean | Indicates whether the IP is from a mobile network |
| `proxy` | boolean | Indicates whether the IP is being used as a proxy |
| `hosting` | boolean | Indicates whether the IP belongs to a hosting provider |
| `query` | string | The IP address queried in the request |
# Retrieve Usage Statistics (/docs/api-reference/usage-statistics/get)
Retrieve bandwidth usage statistics for your Geonode proxy service account. This endpoint provides detailed information about your data consumption.
## Request
```bash
curl -X GET "https://monitor.geonode.com/monitor-light/proxies" \
-H "Authorization: Basic base64(username:password)"
```
## Response
### 200 Success
Usage statistics retrieved successfully.
#### Response Fields
| Field | Type | Description |
| ------------------------------------------ | ------- | ------------------------------------------------------ |
| `data` | object | Container for usage statistics |
| `data.bandwidth` | object | Bandwidth usage information |
| `data.bandwidth.data` | object | Detailed bandwidth data |
| `data.bandwidth.data.default` | integer | Total bandwidth used in bytes |
| `data.bandwidth.data.currentFastBandwidth` | integer | Current fast bandwidth usage (unlimited services only) |
| `data.bandwidth.data.totalBandwidthInGB` | integer | Total bandwidth used in gigabytes |
#### Example Response
```json
{
"data": {
"bandwidth": {
"data": {
"default": 17930356,
"currentFastBandwidth": 0,
"totalBandwidthInGB": 2
}
}
}
}
```
# Remove Whitelisted IPs (/docs/api-reference/whitelisting-ip/delete)
You can remove up to 10 IP addresses per request.
Remove IP addresses from your whitelist. Once removed, these IPs will no longer have automatic access to your proxy services.
## Request
```bash
curl -X DELETE "https://app-api.geonode.com/api/configuration/active/whitelisted-ips" \
-H "Authorization: Basic base64(username:password)" \
-H "Content-Type: application/json" \
-d '{"ips":[{"ip":"161.142.148.121"},{"ip":"161.142.148.147"}]}'
```
### Request Body Parameters
| Field | Type | Required | Description |
| ---------- | ------ | -------- | --------------------------------------- |
| `ips` | array | Yes | List of IP objects to remove |
| `ips[].ip` | string | Yes | The IP address to remove from whitelist |
### Example Request Body
```json
{
"ips": [
{
"ip": "161.142.148.121"
},
{
"ip": "161.142.148.147"
}
]
}
```
## Response
### 200 Success
The IP addresses have been successfully removed from your whitelist.
#### Response Fields
| Field | Type | Description |
| -------------------- | ------ | ------------------------------------------------------ |
| `data` | array | A list of whitelisted IPs that have been removed |
| `data[].ip` | string | The IP address that was removed from the whitelist |
| `data[].description` | string | The user-defined label for the removed IP |
| `data[]._id` | string | A unique identifier assigned to the removed IP |
| `message` | object | Provides status details about the removal operation |
| `message.title` | string | A short message indicating the status of the operation |
| `message.body` | string | A detailed message about the removal operation |
| `message.variant` | string | The status variant indicating success or failure |
#### Example Response
```json
{
"data": [
{
"ip": "161.142.148.141",
"description": "mac-m1",
"_id": "67a875f693afe58d40f2e93d"
}
],
"message": {
"title": "Updated",
"body": "Whitelisted IPs removed.",
"variant": "success"
}
}
```
### Error Responses
#### 400 Bad Request
Invalid input data provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Invalid input data."
}
```
#### 401 Unauthorized
Invalid API credentials provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Unauthorized - Invalid credentials."
}
```
# Retrieve Whitelisted IPs (/docs/api-reference/whitelisting-ip/get)
Retrieve all IP addresses currently on your whitelist.
## Request
```bash
curl -X GET "https://app-api.geonode.com/api/configuration/active/whitelisted-ips" -u "username:apiKey" \
-H "Authorization: Basic base64(username:password)"
```
## Response
### 200 Success
Returns a list of all active whitelisted IP addresses.
#### Response Fields
| Field | Type | Description |
| -------------------- | ------ | ---------------------------------------------- |
| `data` | array | List of whitelisted IP addresses |
| `data[].ip` | string | The IP address of the whitelisted entity |
| `data[].description` | string | A brief description associated with the IP |
| `data[]._id` | string | The unique identifier assigned to the IP entry |
#### Example Response
```json
{
"data": [
{
"ip": "161.142.148.150",
"description": "updated-description",
"_id": "67a0a5bbb412ddaf6f139b3b"
}
]
}
```
### Error Responses
#### 400 Bad Request
Invalid parameters provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Invalid parameters provided."
}
```
#### 401 Unauthorized
Invalid API credentials provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Unauthorized - Invalid API key or credentials."
}
```
#### 500 Internal Server Error
An internal server error occurred.
# Add Whitelisted IPs (/docs/api-reference/whitelisting-ip/post)
You can add up to 10 IP addresses per request.
Add IP addresses to your whitelist to allow them to access your Geonode proxy services without authentication.
## Request
```bash
curl -X POST "https://app-api.geonode.com/api/configuration/active/whitelisted-ips" \
-H "Authorization: Basic base64(username:password)" \
-H "Content-Type: application/json" \
-d '{"ips": [{"ip": "161.142.148.140", "description": "mac-m1"}]}'
```
### Request Body Parameters
| Field | Type | Required | Description |
| ------------------- | ------ | -------- | --------------------------------------------- |
| `ips` | array | Yes | List of IP objects to add to the whitelist |
| `ips[].ip` | string | Yes | The IP address being added to the whitelist |
| `ips[].description` | string | No | A user-defined label or identifier for the IP |
### Example Request Body
```json
{
"ips": [
{
"ip": "161.142.148.140",
"description": "mac-m1"
}
]
}
```
## Response
### 200 Success
The IP addresses have been successfully added to your whitelist.
#### Response Fields
| Field | Type | Description |
| -------------------- | ------ | -------------------------------------------------- |
| `data` | array | A list of successfully whitelisted IP addresses |
| `data[].ip` | string | The IP address that was whitelisted |
| `data[].description` | string | A user-defined label or identifier for the IP |
| `data[]._id` | string | A unique identifier assigned to the whitelisted IP |
| `message` | object | Details about the status of the whitelist update |
| `message.title` | string | A short title summarizing the update status |
| `message.body` | string | A message detailing the outcome of the operation |
| `message.variant` | string | The status variant indicating success or failure |
#### Example Response
```json
{
"data": [
{
"ip": "161.142.148.150",
"description": "updated-description",
"_id": "67a0a5bbb412ddaf6f139b3b"
}
],
"message": {
"title": "Updated",
"body": "Whitelisted IPs saved.",
"variant": "success"
}
}
```
### Error Responses
#### 400 Bad Request
Invalid input data provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Invalid input data."
}
```
#### 401 Unauthorized
Invalid API credentials provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Unauthorized - Invalid API key or credentials."
}
```
# Update Whitelisted IP Description (/docs/api-reference/whitelisting-ip/put)
Update the description or label associated with a whitelisted IP address.
## Request
```bash
curl -X PUT "https://app-api.geonode.com/api/configuration/active/whitelisted-ips" \
-H "Authorization: Basic base64(username:password)" \
-H "Content-Type: application/json" \
-d '{"ip":"161.142.148.150","description":"updated-description"}'
```
### Request Body Parameters
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------ |
| `ip` | string | Yes | The IP address to update |
| `description` | string | Yes | The new description for the whitelisted IP |
### Example Request Body
```json
{
"ip": "161.142.148.150",
"description": "updated-description"
}
```
## Response
### 200 Success
The IP description has been successfully updated.
#### Response Fields
| Field | Type | Description |
| -------------------- | ------ | --------------------------------------------------- |
| `data` | array | A list of updated whitelisted IPs |
| `data[].ip` | string | The IP address that was updated |
| `data[].description` | string | The updated description for the whitelisted IP |
| `data[]._id` | string | A unique identifier assigned to the whitelisted IP |
| `message` | object | Provides status details about the update operation |
| `message.title` | string | A short message indicating the status of the update |
| `message.body` | string | A detailed message about the update operation |
| `message.variant` | string | The status variant indicating success or failure |
#### Example Response
```json
{
"data": [
{
"ip": "161.142.148.150",
"description": "just update",
"_id": "67a0a5bbb412ddaf6f139b3b"
}
],
"message": {
"title": "Updated",
"body": "Whitelisted IPs updated.",
"variant": "success"
}
}
```
### Error Responses
#### 400 Bad Request
Invalid input data provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Invalid input data."
}
```
#### 401 Unauthorized
Invalid API credentials provided.
| Field | Type | Description |
| ------- | ------ | ------------- |
| `error` | string | Error message |
```json
{
"error": "Unauthorized - Invalid API key or credentials."
}
```
# Overview (/docs/api-reference/whitelisting-ip/whitelisting-ips)
IP whitelisting is a security feature that allows you to control which IP addresses can access your Geonode proxy services without requiring authentication. This is particularly useful for securing your proxy infrastructure and ensuring that only authorized IPs can connect to your account.
## What is IP Whitelisting?
When you whitelist an IP address, you're essentially creating a trusted list of IPs that can bypass the standard authentication process. This is ideal for scenarios where:
* You have a fixed server or application that always connects from the same IP
* You want to enhance security by restricting access to specific IP addresses
* You need to simplify authentication for automated systems
* You want to prevent unauthorized access from unknown locations
## Key Features
You can manage up to 10 IP addresses per request, making it easy to bulk
update your whitelist.
* **Add IPs**: Add up to 10 IP addresses at once with optional descriptions for easy identification
* **List IPs**: Retrieve all currently whitelisted IP addresses for your account
* **Update Descriptions**: Modify the labels associated with whitelisted IPs for better organization
* **Remove IPs**: Remove IP addresses from your whitelist when they're no longer needed
## Use Cases
IP whitelisting is useful when you need to allow specific IP addresses to access your proxy services without authentication. Common scenarios include automated scripts, server applications, and controlled access environments.
## Getting Started
To start using IP whitelisting, you'll need to:
1. **Add IPs to your whitelist** using the [Add Whitelisted IPs](/docs/api-reference/whitelisting-ip/post) endpoint
2. **View your current whitelist** with the [Retrieve Whitelisted IPs](/docs/api-reference/whitelisting-ip/get) endpoint
3. **Update IP descriptions** as needed using the [Update Whitelisted IP Description](/docs/api-reference/whitelisting-ip/put) endpoint
4. **Remove IPs** when they're no longer needed via the [Remove Whitelisted IPs](/docs/api-reference/whitelisting-ip/delete) endpoint
Once an IP is whitelisted, it can access your proxy services without
authentication. Make sure to only whitelist trusted IP addresses and regularly
review your whitelist to remove any IPs that are no longer needed.
# Billing & Payments (/docs/guides/FAQs/billing-and-payments)
***
{" "}
All invoices are in USD, we are unable to offer other currencies.
{" "}
If you fail to update your payment information before the next billing cycle,
you may encounter service interruptions.
{" "}
After completing the payment update process, your next billing cycle will be
automatically processed.
{" "}
To view your billing history and invoices: 1. Click on the **Profile** tab. 2.
Navigate to **Account Settings**. 3. Go to the **Payment and Wallet** section.
4\. You will find your **billing history** and invoices listed there.
{" "}
Yes, you can add your credit card details through the Billing tab.
{" "}
Yes, but you must ensure that your credit card is not set as the default card.
If you need extra support, our team is always available to help.
# General FAQs (/docs/guides/FAQs/general-faqs)
***
{" "}
We do not currently offer static IPs. We are planning to release this service
in the coming months!
{" "}
No. Any hacking/cracking or illegal activity is strictly forbidden on our
platform.
{" "}
We do not recommend our current services for streaming, you are welcome to try
and use them for this purpose.
{" "}
We do not block any websites, including survey sites.
# Proxy Related Queries (/docs/guides/FAQs/proxy-usage-queries)
***
{" "}
Sticky proxies have a maximum timeout of 60 minutes. Static proxies are the
type of proxies that do not expire, which we do not currently offer. We
recommend setting auto-replace to true and choosing a lengthy enough rotating
interval for sticky connections when clients bring up the offline issue.
{" "}
We do not recommend our current services for streaming, but you are welcome to
try.
{" "}
We do not block any websites, including survey sites.
You will see popups everywhere asking for your proxy username and password.
{" "}
You can whitelist **up to 150 IP addresses**.
{" "}
A proxy might slightly affect speed, but Geonode's high-speed servers minimize
this impact.
{" "}
Yes, but you must configure it separately for each network type.
{" "}
There are no restrictions on the number of simultaneous connections.
# Subscriptions & Cancellations (/docs/guides/FAQs/subscriptions-and-cancellations)
***
{" "}
Yes, you can cancel anytime. You can still use our service until the end of
the billing period if you have unused bandwidth.
{" "}
Unfortunately, we can't extend subscriptions as we will encounter a break in
the system. However, we will find the right solution for you to compensate for
the downtime, so please reach out to our support team for manual assistance.
{" "}
Yes, you can add multiple cards, but only one will be set as the default card.
{" "}
You can easily re-activate your subscription through your dashboard or reach
out to our support team for help.
# Technical Issues & Support (/docs/guides/FAQs/technical-issues-and-support)
***
{" "}
Our team is working on resolving any occurring issues as soon as possible. We
will inform our users once everything is functioning normally.
{" "}
If your issue is not listed or you need further assistance, please [contact
our support team](https://geonode.com/contact). We are available 24/7 to help
you with any issues.
# Active Subscriptions (/docs/guides/account-setting-and-billing/active-subscriptions)
## Step 1 — Open Profile Settings
1. Log in to your Geonode account.
2. Go to **Profile Settings** in the left-hand sidebar.
***
## Step 2 — View your active subscription
1. In the Profile Settings page, select **Active Subscriptions**.
2. You’ll see details of your current plan, including billing cycle and renewal date.
***
## Tips
* Keep your subscription active to maintain uninterrupted access.
* Review renewal dates regularly to avoid service pauses.
* To upgrade or cancel, use the **Billing** section in your dashboard.
* For any payment or renewal issues, contact [Geonode Support](https://geonode.com/contact).
Managing subscriptions in Geonode is quick and transparent — everything you need is in your profile settings.
# Payment Methods (/docs/guides/account-setting-and-billing/payments-method)
Geonode lets you add, update, and manage your payment methods for smooth and secure billing.
## Step 1 — Access the Payments section
1. Log in to your Geonode account.
2. From the left sidebar, open **Payments**.
***
## Step 2 — Add a new payment method
1. Click **Add Payment Method**.
2. A pop-up window will appear for card details.
### Required information
* **Card Number** (Visa, Mastercard, or AMEX)
* **Expiration Date** (MM/YY)
* **Security Code (CVC)** — 3-digit code on the back of your card
* **Billing Country**
3. Click **Add** to save your payment method.
***
## Step 3 — Update billing information
1. In the **Billing Information** section, click **Update Information**.
2. Update fields such as:
* Name
* Company (optional)
* Billing address
* Phone number
3. Click **Save Changes** to confirm updates.
***
## Step 4 — View payment history
In the **Payment History** section, you can track:
* Transaction date
* Transaction details
* Amount charged
* Invoice records
If no payments have been made, you’ll see *No Data Yet*.
***
## Tips
* Keep billing details accurate to avoid failed payments.
* Supported payment types: **Visa**, **Mastercard**, **AMEX**.
* For payment or billing issues, contact [Geonode Support](https://geonode.com/contact).
Managing payment methods in Geonode ensures secure and uninterrupted service access.
# Profile Settings (/docs/guides/account-setting-and-billing/profile-setting)
Your profile settings let you manage personal information, change passwords, and, if needed, delete your account.
## Step 1 — Access profile settings
1. Log in to your Geonode account.
2. Open **Profile** from the left-hand sidebar.
3. View detailed profile information.
***
## Step 2 — Update personal details
In **Personal Details**, you can:
* Edit your first and last name.
* Update your phone number.
* Note: your email address cannot be changed.
Click **Save changes** after updating.
***
## Step 3 — Change your password
1. Scroll to the **Password** section.
2. Enter and confirm a new password.
3. Click **Update password**.
***
## Step 4 — Delete your account
If you wish to permanently remove your account:
1. Scroll to **Delete Account**.
2. Click **Delete**.
3. Confirm the action — all data will be removed.
Deleting your account does **not** automatically cancel any active services.
Cancel subscriptions or contact Geonode Support before deletion to stop future
charges.
***
## Final tips
* Keep profile information current to avoid issues.
* Use a strong password for better security.
* Account deletion is irreversible.
* For billing or payment concerns, contact [Geonode Support](https://geonode.com/contact).
Managing your profile properly helps maintain a smooth, secure experience in Geonode.
# Referral Program (/docs/guides/account-setting-and-billing/referral-program)
The Geonode Referral Program lets you earn a 10% commission every time a new user signs up and makes a purchase through your unique affiliate link.
## How to get your referral link
Follow these steps to access and start sharing your link.
### Step 1 — Open Profile Settings
1. Log in to your Geonode account.
2. Go to **Profile Settings** in the left sidebar.
***
### Step 2 — Copy your referral link
1. In the **Profile Settings** page, find the **Referral Program** section.
2. Copy your unique affiliate link.
***
## How the referral program works
* Share your referral link anywhere: social media, websites, or direct messages.
* When a user registers and makes a purchase using your link, you earn **10% commission**.
* Commissions are tracked and displayed in your referral dashboard.
***
## Tips
* Share your link across different platforms for better reach.
* More referrals mean higher earnings.
* Monitor your performance and payouts in the referral dashboard.
* For any payment or tracking issues, contact [Geonode Support](https://geonode.com/contact).
Start earning today with Geonode’s Referral Program.
# Reset API Password (/docs/guides/account-setting-and-billing/reset-api-password)
If you need to reset your API password, follow these steps to generate a new one securely.\
Resetting your API password immediately deactivates the old one — don’t forget to update your integrations afterward.
## Step 1 — Access API credentials
1. Log in to your Geonode account.
2. Open the **Proxy Configuration** tab in the dashboard.
3. Locate the **API Credentials** section.
***
## Step 2 — Generate a new API password
1. Click the **reset icon** next to your current API password.
2. A confirmation prompt will appear.
3. Click **Confirm** to generate a new password.
***
## Tips
* Resetting your API password deactivates the old one instantly.
* Update all connected tools, scripts, and automations with the new password.
* You can reset it anytime if you forget or lose access.
* For any billing or payment issues, contact [Geonode Support](https://geonode.com/contact).
Managing your API credentials properly ensures secure and uninterrupted access to Geonode services.
# Wallet (/docs/guides/account-setting-and-billing/wallet-ocerview)
The Geonode Wallet lets you view your balance, review transactions, and add funds for seamless proxy usage.
## Step 1 — Access the Wallet
1. Log in to your Geonode account.
2. Open **Wallet** from the left sidebar.
***
## Step 2 — Check your balance
* Your current wallet balance appears at the top.
* Previous transactions are shown under **Transactions from wallet**.
If you haven’t made any payments yet, the transaction list will be empty.
***
## Step 3 — Add funds
1. In the **Add Funds** section, enter the desired amount.
2. Click **Top Up Wallet** to start the payment process.
3. Once the payment is confirmed, the amount will appear in your wallet balance.
***
## Tips
* Keep your wallet funded to prevent service interruptions.
* Review your transaction history regularly for clarity and tracking.
* For any billing or payment issues, contact [Geonode Support](https://geonode.com/contact).
Using the Geonode Wallet makes managing payments simple and ensures uninterrupted access to all services.
# Port Configuration (/docs/guides/advance-configuration/port-configuration)
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
The **Port Configuration** section in your Geonode dashboard lets you set up and manage proxy ports with precise geo-targeting and connection options.
***
## Step 1 — Open the Port Configuration page
1. Log in to your Geonode dashboard.
2. Select **Port Configuration** from the top navigation bar.
You’ll see configuration options on the right and a list of added locations in the center.
***
## Step 2 — Configure your port settings
### 1. Country targeting (required)
* Open the **Countries** dropdown.
* Select the country you want to target — this field is required for geo-targeting.
### 2. State targeting (optional)
* Once a country is selected, the **States** dropdown becomes active.
* Choose a specific state if needed.
### 3. City targeting (optional)
* After choosing a state, the **Cities** dropdown will be enabled.
* Select a city for more precise targeting.
### 4. Protocol selection
* Click the **HTTP/HTTPS** dropdown.
* Choose a protocol:
* **HTTP/HTTPS** — standard web traffic.
* **SOCKS5** — advanced, more flexible option (if available).
→ [Understanding Protocol Type for Proxy Configuration](https://docs.google.com/document/d/1rjZHN-Fj6UYewLB5HbWaF22AX3VyvraabF5PEWqdSMs/edit?usp=sharing)
### 5. Session type
* Select a session mode:
* **Rotating** — IP changes periodically (best for scraping/automation).
* **Sticky** — one IP per session (best for login or persistent tasks).
→ [Understanding Session Type for Proxy Configuration](https://docs.google.com/document/d/1udGgGDQrqsNW78Rdulv_OtW2Ox2lu6xhdSxjlIPgjOY/edit?usp=sharing)
### 6. Port selection (required)
* Click **Select Port** to choose from available ports.
* This field is required to complete setup.
→ [Understanding Port Usage for Proxy Configuration](/docs/guides/proxy-service-guide/proxy-usage)
***
## Step 3 — Add the configuration
When all required fields are filled, the **Add** button becomes active.\
Click **Add** to save your configuration.
***
## Step 4 — Review added locations
After saving, all configured ports and locations appear in the list.\
You can view, edit, or delete configurations at any time.
***
## Port in use
When a port is assigned to a specific country, it can’t be reused elsewhere.
***
## Final result
You’re now ready to manage ports efficiently in Geonode.
* **Rotating Example**
* **Sticky Example**
***
## Troubleshooting
* **Add button disabled:** make sure Country and Port are selected.
* **State/City inactive:** these fields unlock only after a country is chosen.
* **Connection issues:** verify your protocol and session settings.
***
***
## FAQs
The button stays inactive until all required fields are selected. Choose both a country and a port before proceeding.
{" "}
No. Each port can only be assigned to one country.
{" "}
Rotating sessions periodically change your IP, ideal for scraping and
automation.
{" "}
Yes, you can select either protocol during configuration. SOCKS5 support
depends on your plan.
State and city fields are only active after selecting a country.
# Proxy Authorization in API Using Headers (/docs/guides/advance-configuration/proxy-authentication-in-api)
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
***
API authorization ensures secure access to Geonode’s proxy services.\
This guide explains how to authenticate requests using the `Authorization` header.
***
## Step 1 — Get your API credentials
Before setting up authentication, make sure you have your Geonode API credentials.
→ [How to access your Geonode API credentials](/docs/guides/prerequisites/access-credentials)
***
## Step 2 — Generate the Authorization header
Geonode’s API uses **Basic Authentication**, which requires your username and password encoded in **Base64**.
1. Open the API documentation for the endpoint you want to test (for example, *Retrieve Usage Statistics*).
2. Click **Try it** on the API page.
3. A popup will appear asking for your **username** and **password**. Enter them.
4. The system automatically generates the `Authorization` header for you — containing the Base64-encoded string.
5. Copy the generated header or the encoded string.\
You can use it directly in your API requests or store the Base64 value in your code securely.
***
## Step 3 — Follow best practices
* **Generate once, reuse:** Create your token once and reuse it for multiple requests.
* **Store securely:** Keep it in a `.env` file or secret manager.
* **Avoid hardcoding:** Never paste credentials directly into your source code.
* **Always use HTTPS:** This encrypts your traffic and protects sensitive data.
* **Rotate regularly:** Update your credentials periodically.\
When you do, generate a new token.
***
## Troubleshooting
* Check that your header is formatted correctly:
* Encode exactly `username:password` — no extra spaces or characters.
* Use HTTPS in all requests; avoid using insecure HTTP.
* Test your setup with tools like **Postman** or **cURL** to confirm it works.
* If your credentials are compromised, **change your password**, regenerate your API key, and update the token.
***
***
## FAQs
No. The Geonode API documentation automatically generates the Base64-encoded string for you.
Not at the moment — all proxy API requests require Basic Authorization.
Currently, Geonode only supports Basic Authorization. Check future API updates
for new methods.
No. Base64 is not encryption — it’s only encoding. Always use HTTPS to keep
credentials safe.
Rotate them regularly or immediately if you suspect compromise.
# Proxy Configuration (/docs/guides/advance-configuration/proxy-configuration)
***
## What is the Endpoint Generator
The Endpoint Generator helps you create customized proxy lists based on your preferences.\
You can select **IP type**, **host**, **location**, **protocol**, and **session type**, then export endpoints in `.txt` format.
***
## Step 1 — Access the Dashboard
1. Log in to your Geonode dashboard.
2. Scroll down to **Proxy Configuration**.
***
## Step 2 — Choose the Endpoint Format
There are **six formats** available for generating endpoints, depending on your authentication and connection preferences.
→ [Understanding Different Proxy Endpoint Formats and Their Uses](/docs/guides/proxy-service-guide/endpoint-formats)
***
## Step 3 — Set the Endpoint Count
Specify how many endpoints you want to generate.
***
## Step 4 — Configure Proxy Parameters
There are **seven options** available for customizing proxy endpoints.
***
### 1. IP Type
Select the type of IPs you need.\
Three types are available:
* **Residential**
* **Datacenter**
* **Mixed**
→ [Learn about Residential, Datacenter, and Mixed IPs and their best use cases](/docs/guides/proxy-service-guide/ip-type)
***
### 2. Gateway (Host)
Choose the appropriate host for your location.\
Three options are available:
| Location | Host Address |
| ------------- | ------------------------------------ |
| France | `proxy.geonode.io` |
| United States | `us.premium-residential.geonode.com` |
| Singapore | `sg.premium-residential.geonode.com` |
Selecting a host automatically updates the corresponding address.
→ [Learn about Geonode’s proxy gateways and how they work](/docs/guides/proxy-service-guide/gateway)
***
### 3. Geo-Targeting (Country, State, City)
Select your desired **country**, **state**, or **city**.\
By default, the system uses **Any**, meaning proxies can come from any location.
**Example:**
* **Host:** Singapore
* **Target Country:** China
This setup provides faster connectivity to nearby Chinese servers.
→ [What is Geo-Targeting](/docs/guides/proxy-service-guide/geo-targeting)
***
### 4. Protocol
Choose how your proxy handles connections:
1. **HTTP/HTTPS** — standard web traffic.
2. **SOCKS5** — flexible and secure (if supported).
→ [Understanding Protocol Type for Proxy Configuration](/docs/guides/proxy-service-guide/protocol-type)
When you change the protocol, port numbers in generated endpoints update automatically.
→ [Learn how ports work in Geonode’s proxy configuration](/docs/guides/proxy-service-guide/proxy-usage)
***
### 5. Session Type
Define how IPs are handled within a session:
1. **Rotating Session** — IP changes periodically (best for scraping and automation).
2. **Sticky Session** — IP stays the same for the entire session (best for logins or persistent tasks).
→ [A Guide to Rotating and Sticky Sessions](/docs/guides/proxy-service-guide/session-type)
***
### 6. Rotating Interval (Sticky Sessions Only)
If you use Sticky Sessions, you can set a rotation interval to control how often IPs refresh — in minutes or hours.
This keeps your connection stable while maintaining periodic IP rotation for security and reliability.
***
## Step 5 — Select the Output Format
After completing the configuration, you can:
* **Copy** endpoints directly for immediate use, or
* **Download** them as a `.txt` file for later.
***
✅ **You’re all set!**\
You’ve successfully created a ready-to-use list of proxy endpoints.\
Your setup is now fully configured and ready to integrate into your applications.
# Whitelist IP (/docs/guides/advance-configuration/whitelist-ip)
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
Whitelisting your IP lets you access proxy services without re-entering credentials each time.
## Key limits and requirements
* Authentication: Basic Auth (username:password encoded in Base64).
* IP limit: up to 150 whitelisted IPs per user.
* Batch size: up to 10 IPs per request (add/remove).
* Validation: the API rejects invalid or duplicate IPs.
* Rate limit: up to 100 requests per minute.
## Add an IP to the whitelist
You can use either the dashboard (recommended for non-developers) or the API.
### Using the dashboard
#### Add IP addresses
1. Open **Whitelisted IPs** in settings.
2. Enter the IP to whitelist. For a quick setup, click **Detect My IP**.\
Optionally add a description (e.g., Home, Office, Server). Click **Add**.
3. Verify that the IP appears in the table with correct details.
#### Remove an IP
1. Find the IP in the whitelist table.
2. Click **Delete** next to the IP.
3. Confirm the deletion and check the notification.
### Using the API
Available endpoints:
* [Retrieve whitelisted IPs](/docs/api-reference/whitelisting-ip/get) `GET`
* [Add whitelisted IPs](/docs/api-reference/whitelisting-ip/post) `POST`
* [Update IP description](/docs/api-reference/whitelisting-ip/put) `PUT`
* [Remove whitelisted IPs](/docs/api-reference/whitelisting-ip/delete) `DELETE`
For request/response formats and examples, see the Geonode API docs:\
[Geonode API Documentation](/docs/api-reference/whitelisting-ip/whitelisting-ips)
***
***
## FAQs
Basic Authentication ensures only authorized users can modify the whitelist.
Encode your username and password in Base64 and include it in the request.
Yes. Use the Geonode API to add, update, and remove IPs programmatically.
Requests that push the total over 150 IPs are rejected. Remove unused entries
first.
Delete the incorrect IP from the dashboard or via the API, then add the
correct one.
Whitelisting lets trusted devices connect without re-entering credentials,
simplifying access for known locations.
***
# Selenium (/docs/guides/automation-frameworks/selenium)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
***
This guide will help you integrate the Geonode API with Selenium to manage proxies effectively while running headless browsers.
**We will be using Python for this guide.**
***
***
## Prerequisites
* Python installed on your system
* Geonode API credentials (username and password)
* ChromeDriver installed (compatible with your Chrome version)
## Steps: Setting Up a Proxy in Brave
Follow these steps to configure a proxy in Selenium:
### Step 1: Set Up a Virtual Environment
Creating a virtual environment helps isolate dependencies and avoid conflicts.
```
# Install virtualenv if not already installed
pip install virtualenv
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
## On Windows
.venv\Scripts\activate
## On macOS/Linux
source .venv/bin/activate
```
### Step 2: Install Required Libraries
```
pip install selenium python-dotenv selenium-wire
```
* **Selenium:** For browser automation
* **python-dotenv:** For managing environment variables
* **selenium-wire:** To handle proxy authentication, as Selenium doesn't provide it natively
### Step 3: Configure Geonode Proxy Endpoint
With the help of the **Endpoint Generator**, you can easily generate the proxy with specific configurations such as:
* Target country
* Port
* Session persistence
* And many more
Refer to the guide **[How to Use the Endpoint Generator](https://docs.google.com/document/d/11YaEtmKbMP9d5lclO4vjySjtwmuW8i-m-l1qN5lNsXY/edit?usp=sharing)** to generate your endpoints.
### Step 4: Setting up environment variables
1. Create a `.env` file in your project directory.
2. Add your credentials:
```
GEONODE_USERNAME=your_geonode_username
GEONODE_PASSWORD=your_geonode_password
GEONODE_HOST=proxy.geonode.io
GEONODE_PORT=9000
GEONODE_DNS=your_geonode_dns
```
Never upload your
`.env`
file to the internet.
## Code Implementation
### I. Import
```
import os
from dotenv import load_dotenv
from seleniumwire import webdriver
from selenium.webdriver.chrome.options import Options
```
### ii. Load environment variables
```
load_dotenv()
proxy_host = os.getenv('GEONODE_HOST')
proxy_port = os.getenv('GEONODE_PORT')
username = os.getenv('GEONODE_USERNAME')
password = os.getenv('GEONODE_PASSWORD')
GEONODE_DNS = os.getenv('GEONODE_PROXY')
```
### iii. Configure Proxy options
```
proxy_options = {
'proxy': {
'http': f'http://{username}:{password}@{proxy_host}:{proxy_port}',
'https': f'https://{username}:{password}@{proxy_host}:{proxy_port}',
}
}
```
### iv. Configure Browser Options
```
chrome_options = Options()
chrome_options.add_argument('--disable-gpu')
chrome_options.add_argument('--start-maximized')
chrome_options.add_argument('--ignore-certificate-errors')
```
### v. Initialize Browser
```
browser = webdriver.Chrome(seleniumwire_options=proxy_options, options=chrome_options)
```
### vi. Open IP address website to check
```
urlToGet = "https://ip-api.com/"
browser.get(urlToGet)
```
**Output:**
### vii. Keep the browser open
```
input("Press Enter to close the browser...")
```
### viii. Quit the browser
```
browser.quit()
```
### xi. Full Code
```
import os
from dotenv import load_dotenv
from seleniumwire import webdriver
from selenium.webdriver.chrome.options import Options
load_dotenv()
proxy_host = os.getenv('GEONODE_HOST')
proxy_port = os.getenv('GEONODE_PORT')
username = os.getenv('GEONODE_USERNAME')
password = os.getenv('GEONODE_PASSWORD')
GEONODE_DNS = os.getenv('GEONODE_PROXY')
proxy_options = {
'proxy': {
'http': f'http://{username}:{password}@{proxy_host}:{proxy_port}',
'https': f'https://{username}:{password}@{proxy_host}:{proxy_port}',
}
}
chrome_options = Options()
chrome_options.add_argument('--disable-gpu')
chrome_options.add_argument('--start-maximized')
chrome_options.add_argument('--ignore-certificate-errors')
browser = webdriver.Chrome(seleniumwire_options=proxy_options, options=chrome_options)
urlToGet = "https://ip-api.com/"
browser.get(urlToGet)
input("Press Enter to close the browser...")
browser.quit()
```
### x. Folder Stucture
```
Project Root
├── .venv/
├── .env
└── app.py
```
## Source Code
You can find the full source code for this script on GitHub at the following link:
[https://github.com/geonodecom/proxy-testing-toolkit/tree/automation-framework/selenium](https://github.com/geonodecom/proxy-testing-toolkit/tree/automation-framework/selenium)
***
## Use Cases of Integrating Geonode with Selenium
Integrating Geonode with Selenium can be beneficial for a wide range of applications, including:
1. **Web Scraping:** Collect data from websites while maintaining anonymity to avoid IP bans.
2. **Ad Verification:** Test and verify advertisements across different geographies to ensure proper delivery.
3. **Price Monitoring:** Track pricing changes on e-commerce platforms without getting blocked.
4. **SEO Monitoring:** Monitor search engine results and competitor websites without affecting personalized search results.
5. **Market Research:** Gather data from various sources to analyze trends and competitor performance.
6. **Social Media Automation:** Manage multiple social media accounts while avoiding detection.
7. **Fraud Detection:** Simulate real-world traffic for security testing and fraud detection systems.
Explore more use cases here *[https://geonode.com/use-cases](https://geonode.com/use-cases)*
***
## Troubleshooting Tips
* **Timeout Errors:** Check if the proxy is active or switch to another proxy.
* **Authentication Issues:** Double-check your Geonode API credentials.
* **Incompatible ChromeDriver:** Ensure ChromeDriver matches your Chrome version.
***
## FAQs
The authentication details are embedded in the proxy URL, so no pop-up should appear.
{" "}
Yes, but you need to adjust the proxy settings using Firefox profiles.
Verify the proxy server details and ensure Geonode proxies are correctly configured.
# AdsPower (/docs/guides/browsers/adspower)
import { Steps } from "fumadocs-ui/components/steps";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
This guide explains how to configure a Geonode proxy in the **AdsPower** browser.
## Setting Up a Proxy in AdsPower
### Step 1: Install AdsPower
1. Go to the [AdsPower Download Page](https://www.adspower.com/download).
2. Download the version for your operating system.
3. Install AdsPower and create an account.
***
### Step 2: Create a New Profile
1. Open AdsPower and click **New Profile**.\
2. Fill in the required details:
* Profile name
* Operating system
* Browser version
3. (Optional) Randomize the fingerprint for extra security.
4. Review your browser details on the right side.\
***
### Step 3: Add a Proxy
1. Go to the **Proxy** tab.\
2. Select the connection type — for this guide, choose **HTTPS**.\
3. Enter your proxy details:
* Proxy (IP:Port)
* Username
* Password
4. Set **Geonode** as the main proxy provider.
***
### Step 4: Create and Launch the Profile
1. Click **Create Profile** to save your settings.
2. Once created, the profile will appear in the list.
* If a location appears, the proxy is active.\
3. Click **Start** to launch the browser with your configured proxy.\
Your **Geonode** proxy is now successfully configured in AdsPower.
# Brave (/docs/guides/browsers/brave)
import ProxyOs from "../../../snippets/proxy-os.mdx";
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the Brave browser.
## Setting Up a Proxy in Brave
### Open Brave Settings
1. Click the three-dot menu in the top-right corner of Brave.
2. Select **Settings** from the dropdown menu.
***
### Access System Proxy Settings
1. In the sidebar, click **System**.
2. Then click **Open your computer’s proxy settings**.
***
### Configure the Proxy on Your Operating System
Brave will now open your system proxy configuration window.\
Follow the appropriate setup guide for your OS below:
Once configured, Brave will automatically route its traffic through the assigned proxy.
# Chrome (/docs/guides/browsers/chrome)
import ProxyOs from "../../../snippets/proxy-os.mdx";
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in Chrome using two methods:
* **Using the Geonode Proxy Manager Extension (recommended)**
* **Manual setup through Chrome system settings**
## Method 1: Using the Geonode Proxy Manager Extension
The easiest and most flexible way to configure a proxy in Chrome is by using the **Geonode Proxy Manager** extension.\
It lets you switch proxies quickly without changing system-wide settings.
### Install and Configure the Extension
1. Install **Geonode Proxy Manager** from the [Chrome Web Store](https://chromewebstore.google.com/detail/geonode-proxy-manager/ippioaknloonmaibmmepkemhmhinohge).
2. Follow this guide to complete the setup:\
[How to Use the Geonode Chrome Extension for Proxy Management](/docs/guides/extensions/geonode-proxy-manager).
Once installed, Chrome will route all traffic through the selected proxy.
## Method 2: Manual Proxy Setup in Chrome
If you prefer to configure the proxy manually, follow these steps:
### Open Chrome Settings
1. Click the three-dot menu in the top-right corner of Chrome.
2. Select **Settings** from the dropdown menu.
***
### Access System Proxy Settings
1. In the left sidebar, click **System**.
2. Then click **Open your computer’s proxy settings**.
***
### Configure the Proxy on Your Operating System
Chrome will now open your system proxy configuration window.\
Follow the appropriate guide for your OS below:
Once configured, Chrome will automatically route its traffic through the assigned proxy.
# ClonBrowser (/docs/guides/browsers/clonbrowser)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in ClonBrowser.
## Setting Up a Proxy in ClonBrowser
### Install ClonBrowser
1. Go to the [ClonBrowser Download Page](https://www.clonbrowser.com/download).
2. Download the version for your operating system.
3. Install the browser and create an account.
***
### Create a New Profile
1. Open ClonBrowser and click **Add Profile**.\
2. Fill in the required details:
* Profile name
* Operating system
3. (Optional) Randomize the fingerprint for extra security.
4. Review your browser details on the right panel.\
***
### Add Proxy Details
1. Open the **Proxy** tab.
2. Choose a connection type — for this guide, select **HTTP**.
3. Enter your proxy information:
* Proxy (IP:Port)
* Username
* Password
4. Click **Create Profile** to save your configuration.
***
### Test the Proxy Connection
1. Click **Connect Test** to verify the connection.
2. If successful, the proxy will appear as active.
***
### Launch the Profile
1. Once the profile is created, it will appear in your list.
* If the proxy shows a location, it means it’s active.\
2. Click **Start** to open the browser with your configured proxy.\
Your Geonode proxy is now successfully configured in ClonBrowser.
# Dolphin Anty (/docs/guides/browsers/dolphin-anty)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the Dolphin Anty browser.
## Setting Up a Proxy in Dolphin Anty
### Install Dolphin Anty
1. Go to the [Dolphin Anty Download Page](https://dolphin-anty.com/download-started/).
2. Download the version for your operating system.
3. Install the browser and create an account.
***
### Create a New Profile
1. Open Dolphin Anty and click **Add Profile**.\
2. Fill in the required details:
* Profile name
* Operating system
3. (Optional) Randomize the fingerprint for extra security.
4. Review your browser details on the right.\
***
### Add Proxy Details
1. Open the **Proxy** tab.
2. Choose a connection type — for this guide, select **HTTP**.
3. Enter your proxy information:
* Proxy (IP:Port)
* Username
* Password
4. Click **Create Profile** to save the configuration.
5. A green check mark indicates the proxy is connected.
***
### Launch and Verify the Profile
1. Once created, your profile will appear in the list.
* If the proxy shows a location, it’s active.\
2. Click **Start** to launch the browser with the configured proxy.
3. Visit [`http://ip-api.com/json`](http://ip-api.com/json) to confirm your IP.
Your Geonode proxy is now successfully configured in Dolphin Anty.
# Edge (/docs/guides/browsers/edge)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import ProxyOs from "../../../snippets/proxy-os.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the Microsoft Edge browser.
## Setting Up a Proxy in Edge
### Open Edge Settings
1. Click the three-dot menu in the top-right corner of Edge.
2. Select **Settings** from the dropdown menu.
***
### Access System Proxy Settings
1. In the left sidebar, click **System**.
2. Then click **Open your computer’s proxy settings**.
***
### Configure the Proxy on Your Operating System
Edge will now open your system proxy configuration window.\
Follow the appropriate setup guide for your OS below:
Once configured, Edge will automatically route its traffic through the assigned proxy.
# Firefox (/docs/guides/browsers/firefox)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in Firefox for secure and anonymous browsing.
## Setting Up a Proxy in Firefox
### Open Firefox Settings
1. Click the **three-line menu (☰)** in the top-right corner of Firefox.
2. Select **Settings** from the dropdown menu.
***
### Access Network Settings
1. Scroll down to **Network Settings**.
2. Click **Settings** to open the proxy configuration panel.
***
### Configure Proxy Settings
1. In the **Connection Settings** popup, enter the following details:
* **Manual proxy configuration**: select this option.
* **HTTP Proxy**: enter your proxy IP.
* **Port**: enter your proxy port.
* **SOCKS Proxy** (optional): use SOCKS5 if applicable.
2. Click **OK** to save changes.
Firefox will now route all traffic through the configured proxy.
# GeeLark (/docs/guides/browsers/geelark)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the GeeLark browser for both **mobile** and **desktop** profiles.
You’ll learn how to:
* Add and manage Geonode proxies in GeeLark
* Create mobile and desktop profiles
* Set up device environments
* Launch virtual profiles and test proxy connections
## Setting Up a Proxy in GeeLark
### Install GeeLark
1. Go to the [GeeLark Download Page](https://www.geelark.com/).
2. Download the version for your operating system.
3. Install the software and create an account.
***
### For Mobile Profiles
#### Create a New Profile
1. Open GeeLark and click **New Profile**.\
2. Enter the required details:
* Profile name
* Operating system
3. Review your browser details on the right side.\
***
#### Add a Proxy
You can add proxies in two ways:
##### Option A: Add Proxies First (Recommended)
1. Go to the **Proxies** tab from the sidebar.\
2. Click **Add Proxy**.\
3. Enter your proxy in one of the following formats:
```
proxy.geonode.io:9000:geonode_username:password
```
You can also use:
```
username:password@host:port
```
Or
```
http://username:password@proxy.geonode.io:9000
```
4. Select:
* **Type:** HTTP
* **Proxy group:** e.g., “Geonode Proxies”
* **IP Query Channel:** use `ip-api` for geolocation checks
5. Add one proxy per line (up to 100).
6. Test them using **Proxy Tests** to confirm connectivity — green icons indicate success.\
##### Option B: Add Proxy During Profile Creation
1. While creating a profile, go to the **Proxy** tab.
2. Choose the connection type (e.g., HTTP).
3. Enter:
* Proxy (IP:Port)
* Username
* Password
4. Set IP Query Channel (e.g., `ip-api`) and click **Check Proxy**.\
***
#### Configure Profile Settings
1. Under **Profile Settings**, set:
* Profile name
* Operating system (Android or iOS)
* Group, tags, remark (optional)\
2. Add the proxy:
* **Custom Proxy:** enter host, port, username, password
* **Saved Proxy:** choose from a pre-added list\
***
#### Configure Device Information
Under **Device Information**, you can simulate mobile hardware and network behavior:
* Charging Method: pay per minute or monthly
* Android version: e.g., 12–15
* Network: Wi-Fi or Cellular
* Phone number: auto or custom
* Area, Device Brand, Language: auto or manual
***
#### Create and Launch the Profile
1. Click **Create** to save the profile.
2. The profile appears in your list — showing OS, proxy region, tags, etc.
3. Click the **Action (▶️)** button to launch.
4. A new window opens — visit [ip-api.com](https://ip-api.com) to verify your IP and proxy location.\
***
### For Desktop Profiles
#### Create a New Desktop Profile
1. In GeeLark, click **New Profile**, then switch to the desktop icon (🖥️).
2. Under **Profile Settings**, configure:
* Profile name
* Group / tags / remark
* Operating system (Windows or macOS)
* Browser (e.g., Kiwi)
* User-Agent (auto or custom)
* Optional cookies for session import\
***
#### Set Proxy for Desktop Profile
You can either:
* Use a **Custom Proxy**, or
* Select a **Saved Proxy** (from the “Geonode Proxies” group).
***
#### Optional: Account Settings
Configure:
* Platform credentials (if needed)
* Startup behavior (e.g., reopen tabs, open custom page)\
***
#### Optional: Advanced Settings
Fine-tune fingerprinting and device behavior:
* Time zone, language, geolocation
* WebRTC, Canvas, WebGL, AudioContext
* Resolution, fonts, storage, noise controls
* Device hardware and network simulation\
***
#### Review Device Information
The right-hand panel summarizes fingerprint and environment settings:
* Browser, OS, User-Agent
* Time zone, WebRTC, language, Canvas, WebGL
* Fonts, resolution, and more
You can click **Generate New Fingerprint** to randomize your identity.\
***
#### Launch the Desktop Profile
1. Click **Create** to save.
2. The new profile appears in your list.
3. Click the **Action (▶️)** button to launch.
4. Visit [ip-api.com](https://ip-api.com) to confirm your Geonode proxy is active.\
# Ghost Browser (/docs/guides/browsers/ghost)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyOs from "../../../snippets/proxy-os.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in Ghost Browser.
## Setting Up a Proxy in Ghost Browser
### Install Ghost Browser
1. Go to the [Ghost Browser Download Page](https://ghostbrowser.com/download/).
2. Download the version for your operating system.
3. Install the software.
***
### Add a Proxy
1. Open **Proxy Control** and click **Add/Edit Proxies**.\
2. In the new window, select **Add a Single Proxy**.\
3. Enter your proxy details:
* Proxy (IP:Port)
* Username
* Password\
***
### Test the Proxy Connection
1. Confirm that your proxy appears in the **Proxy Management Table**.\
2. Click the **Test Proxy** tab.
3. Enter a website to verify your connection.\
4. If successful, a confirmation popup will appear.\
Your Geonode proxy is now successfully configured in Ghost Browser.
# GoLogin (/docs/guides/browsers/gologin)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the GoLogin browser.
## Setting Up a Proxy in GoLogin
### Install GoLogin
1. Go to the [GoLogin Download Page](https://gologin.com/download-started/).
2. Download the version for your operating system.
3. Install the software and create an account.
***
### Create a New Profile
1. Open GoLogin and click **Add Profile**.\
2. Enter the required details:
* Profile name
* Operating system
3. (Optional) Randomize the fingerprint for extra security.
4. Review your browser details on the right.\
***
### Add Proxy Details
1. Go to the **Proxy** tab.
2. Choose the connection type — for this guide, select **HTTP**.
3. Enter your proxy credentials:
* Proxy (IP:Port)
* Username
* Password
4. Click **Create Profile** to save the settings.\
***
### Test the Proxy Connection
1. Click **Check Proxy** to verify the connection.
2. If successful, the proxy will show as active.\
***
### Launch the Profile
1. Once created, the profile will appear in your list.
* If the proxy displays a location, it means it’s active.\
2. Click **Start** to launch the browser with your configured proxy.
3. Visit [`http://ip-api.com/json`](http://ip-api.com/json) to verify your IP and proxy location.\
Your Geonode proxy is now successfully configured in GoLogin.
# Incognito Mode (/docs/guides/browsers/incognito-mode)
import ProxyOs from "../../../snippets/proxy-os.mdx";
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in **Chrome’s Incognito Mode**.
## Setting Up a Proxy in Incognito Mode
### Open Chrome Settings
1. Click the **three-dot menu** in the top-right corner of Chrome.
2. Select **Settings** from the dropdown menu.
***
### Access System Proxy Settings
1. In the left sidebar, click **System**.
2. Then click **Open your computer’s proxy settings**.
***
### Configure the Proxy on Your Operating System
Chrome will now open your system’s proxy configuration window.\
Follow the appropriate setup guide for your OS below:
Once configured, Chrome will automatically route all traffic—including Incognito Mode—through the assigned proxy.
# Incogniton (/docs/guides/browsers/incogniton)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the Incogniton browser.
## Setting Up a Proxy in Incogniton
### Install Incogniton
1. Go to the [Incogniton Download Page](https://incogniton.com/download-incogniton/).
2. Download the version for your operating system.
3. Install the software and create an account.
***
### Create a New Profile
1. Open Incogniton and click **New Profile**.\
2. Fill in the required details:
* Profile name
* Operating system
* Browser version
3. (Optional) Randomize the fingerprint for added security.
4. Review your browser details on the right panel.\
***
### Add Proxy Settings
1. Go to the **Proxy Management** page.\
2. Choose the connection type — for this guide, select **HTTP**.\
3. Enter your proxy credentials:
* Proxy (IP:Port)
* Username
* Password\
***
### Check the Proxy Connection
1. Click **Check Proxy** to verify the connection.\
2. If successful, the proxy will show as active.
***
### Create and Launch the Profile
1. Click **Create Profile** to save your settings.\
2. Once created, you’ll see the profile in your list.
* If the proxy shows a green tick, it means it’s active.\
3. Click **Start** to launch the browser with your configured proxy.\
Your Geonode proxy is now successfully configured in Incogniton.
# MoreLogin (/docs/guides/browsers/morelogin)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the MoreLogin browser.
## Setting Up a Proxy in MoreLogin
### Install MoreLogin
1. Go to the [MoreLogin Download Page](https://www.morelogin.com/).
2. Download the version for your operating system.
3. Install the software and create an account.
***
### Create a New Profile
1. Open MoreLogin and click **Add Profile**.\
2. Enter the required details:
* Profile name
* Operating system
3. (Optional) Randomize the fingerprint for added security.
4. Review your browser details on the right side.\
***
### Add Proxy Details
1. Go to the **Proxy** tab.
2. Choose the connection type — for this guide, select **HTTP**.
3. Enter your proxy credentials:
* Proxy (IP:Port)
* Username
* Password
4. Click **Create Profile** to save the configuration.\
***
### Test the Proxy Connection
1. Click **Proxy Detection** to verify the connection.
2. If successful, the proxy will show as active.\
***
### Launch the Profile
1. Click **Create Profile** to save your settings.
2. Once created, your profile will appear in the list.
* If the proxy shows a location, it means it’s active.\
3. Click **Start** to launch the browser with your configured proxy.\
Your Geonode proxy is now successfully configured in MoreLogin.
# MultiLogin (/docs/guides/browsers/multilogin)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the MultiLogin browser.
## Setting Up a Proxy in MultiLogin
### Install MultiLogin
1. Go to the [MultiLogin Download Page](https://www.multilogin.com/).
2. Download the version for your operating system.
3. Install the software and create an account.
***
### Create a New Profile
1. Open MultiLogin and click **Add Profile**.\
2. Enter the required details:
* Profile name
* Operating system
3. (Optional) Randomize the fingerprint for extra security.
4. Review your browser details on the right side.\
***
### Add Proxy Details
1. Open the **Proxy** tab.
2. Choose the connection type — for this guide, select **HTTP**.
3. Enter your proxy credentials:
* Proxy (IP:Port)
* Username
* Password
4. Click **Create Profile** to save the configuration.\
***
### Test the Proxy Connection
1. Click **Proxy Detection** to verify the connection.
2. If successful, the proxy will show as active.\
***
### Launch the Profile
1. Click **Create Profile** to save your settings.
2. Once created, your profile will appear in the list.
* If the proxy shows a location, it means it’s active.\
3. Click **Start** to launch the browser with your configured proxy.\
Your Geonode proxy is now successfully configured in MultiLogin.
# Octo Browser (/docs/guides/browsers/octo)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in the Octo Browser.
## Setting Up a Proxy in Octo Browser
### Install Octo Browser
1. Go to the [Octo Browser Download Page](https://octobrowser.net/download/).
2. Download the version for your operating system.
3. Install the software and create an account.
***
### Create a New Profile
1. Open Octo Browser and click **Add Profile**.\
2. Enter the required details:
* Profile name
* Operating system
3. (Optional) Randomize the fingerprint for extra security.
4. Review your browser details.\
***
### Add Proxy Details
1. Click the **Proxy** button.\
2. Choose a connection type — for this guide, select **HTTP**.
3. Enter your proxy credentials:
* Proxy (IP:Port)
* Username
* Password\
4. Click **Check Proxy Connection** to test it.
5. Click **Confirm** to save your proxy settings.
***
### Launch the Profile
1. Once created, the profile will appear in your list.
* If the proxy shows a location, it means it’s active.\
2. Click **Start** to launch the browser with your configured proxy.
3. Visit [`http://ip-api.com`](http://ip-api.com) to verify your IP and proxy location.\
Your Geonode proxy is now successfully configured in Octo Browser.
# Safari (/docs/guides/browsers/safari)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide will help you configure a Geonode proxy in Safari.
## Setting Up a Proxy in Safari
### Open Safari Settings
1. In the top menu bar, click **Safari → Settings** (or **Preferences** on older macOS versions).
2. Select the **Advanced** tab.
3. Click **Change Settings** next to **Proxies**.
***
### Configure the Proxy on macOS
1. The **Network** window will open in System Preferences.
2. Select your active network connection (Wi-Fi or Ethernet).
3. Click **Advanced → Proxies**.
4. Choose the protocol you want to configure (e.g., HTTP or HTTPS).
5. Enter your Geonode proxy credentials:
* **Proxy server:** IP and Port
* **Username / Password** if required
6. Click **OK**, then **Apply** to save your settings.
***
### Verify the Proxy Connection
Once configured, Safari will automatically route traffic through your Geonode proxy.\
You can verify that it’s working correctly below.
# macOS (/docs/guides/desktop-OS/macOS)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import PopupAuth from "../../../snippets/popup-auth.mdx";
***
***
## Step-by-step setup for macOS
Follow these steps to configure your proxy manually.
### Step 1 — Open System Preferences
1. Click the **Apple menu** icon in the top-left corner.
2. Select **System Preferences** from the dropdown.
***
### Step 2 — Open Network Settings
1. In **System Preferences**, click **Network**.
2. Choose your active Wi-Fi network and click **Details** (or the “i” icon).
***
### Step 3 — Select Your Active Network
Make sure the selected network is the one you’re currently connected to.
***
### Step 4 — Open the Proxies Tab
1. Click **Advanced** in the Network window.
2. Open the **Proxies** tab.
***
### Step 5 — Configure Proxy Settings
1. In the **Proxies** tab, you’ll see several proxy types:
* Web Proxy (HTTP)
* Secure Web Proxy (HTTPS)
* SOCKS Proxy
2. Check the box next to the proxy type you’re setting up (for example, **Web Proxy (HTTP)**).
3. Enter your **Proxy Server** address and **Port** — both can be copied from your Geonode Dashboard (click the copy icon next to *Host*).
***
### Step 6 — Apply and Save Changes
1. Click **OK** to close Advanced settings.
2. Click **Apply** in the main Network window to save your configuration.
***
***
***
# Windows (/docs/guides/desktop-OS/windows)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import PopupAuth from "../../../snippets/popup-auth.mdx";
***
***
## Step-by-step setup for Windows 10/11
Follow these steps to configure your proxy manually:
### Step 1 — Open Proxy Settings
1. Click the **Windows Search Bar** and type:\
`"Change proxy settings"`
2. In the settings window, scroll to **Manual Proxy Setup**.
***
### Step 2 — Enter Proxy Details
1. A configuration window will open:
2. Enter the **Proxy IP** and **Port** you copied from your Geonode Dashboard.
3. Click **Save** to apply the settings.
***
***
***
# FoxyProxy (/docs/guides/extensions/foxyproxy)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import ExtensionFAQs from "../../../snippets/extensions-faqs.mdx";
This guide explains how to install, configure, and use **Geonode proxies** in the **FoxyProxy** browser extension.
***
## What Is FoxyProxy
FoxyProxy is a browser extension that lets you easily manage and switch between multiple proxy configurations.\
Instead of manually entering proxy details each time, you can save and control proxies directly within your browser.
***
***
## Steps to Set Up Geonode Proxy in FoxyProxy
Follow these steps to configure your Geonode proxy using the FoxyProxy extension.
***
### Step 1: Install the FoxyProxy Extension
1. Open the [FoxyProxy extension page](https://chromewebstore.google.com/detail/foxyproxy/gcknhkkoolaabfmlnjonogaaifnjlfnp) in the Chrome Web Store.
2. Click **Add to Chrome** to install the extension.
3. Confirm the installation by clicking **Add Extension** when prompted.
***
### Step 2: Pin the Extension for Quick Access
After installation, pin the extension to your Chrome toolbar for faster access.
1. Click the **Extensions** icon (puzzle piece) in Chrome.
2. Find **FoxyProxy** and click the **Pin** icon.
***
### Step 3: Open FoxyProxy Settings
1. Click the **FoxyProxy** icon in your Chrome toolbar.
2. Select **Options** to open the settings panel.
3. You’ll be redirected to the **Proxy Manager** page.\
Click on the **Proxies** tab.
***
### Step 4: Add a New Proxy
1. Click **Add New Proxy**.
2. Fill in your proxy details in the popup window:
* **Name**: Any label for easy identification
* **Host**: Your proxy server (e.g., `proxy.geonode.io`)
* **Port**: Usually `9000`
* **Username** and **Password**: Your Geonode credentials
3. Click **Add Proxy** to save the configuration.
4. Return to the **Proxy Manager** to confirm that your new proxy appears in the list.
***
### Step 5: Connect to the Proxy
1. Click the **FoxyProxy** icon in the Chrome toolbar.
2. Select the proxy you added from the list.
3. Click **Connect** to activate the proxy.\
Once connected, all your browser traffic will route through the selected proxy.
***
***
***
# Geonode Proxy Manager (/docs/guides/extensions/geonode-proxy-manager)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide explains how to install, configure, and use the **Geonode Proxy Manager** Chrome extension.
***
## What Is Geonode Proxy Manager
Geonode Proxy Manager is a Chrome extension that simplifies proxy management.\
You can add, save, and switch between multiple proxies directly from your browser without manually entering details each time.
***
***
## Setting Up a Proxy in Geonode Proxy Manager
Follow these steps to configure your proxy using the Geonode Proxy Manager extension.
***
### Step 1: Install the Geonode Proxy Manager Extension
1. Open the [Geonode Proxy Manager extension page](https://chromewebstore.google.com/detail/geonode-proxy-manager/ippioaknloonmaibmmepkemhmhinohge).
2. Click **Add to Chrome** to install the extension.
3. Confirm installation by selecting **Add Extension** when prompted.
***
### Step 2: Pin the Extension for Quick Access
After installation, pin the extension to your Chrome toolbar for easy access.
1. Click the **Extensions** icon (puzzle piece) in Chrome.
2. Find **Geonode Proxy Manager** and click the **Pin** icon.
***
### Step 3: Open the Extension
1. Click the **Geonode Proxy Manager** icon in your Chrome toolbar.
2. If no proxies have been added yet, click **Add New Proxy**.
3. You’ll be redirected to the Proxy Manager page.
***
### Step 4: Add a New Proxy
1. Click **Add New Proxy**.
2. Enter your proxy details in the popup:
* **Name** — any recognizable label for this proxy
* **Host** — e.g., `proxy.geonode.io`
* **Port** — usually `9000`
* **Username** and **Password** — your Geonode credentials
3. Click **Add Proxy** to save your configuration.
4. Once saved, go back to the Proxy Manager to confirm that your new proxy appears in the list.
***
### Step 5: Connect to the Proxy
1. Click the **Geonode Proxy Manager** icon again in your Chrome toolbar.
2. Select the proxy you want to use from the list.
3. Click **Connect** to activate the proxy.\
Once connected, all browser traffic will be routed through the selected proxy.
***
***
***
## FAQs
Yes, you can add multiple proxies and switch between them by selecting the
desired one from the list and clicking **Connect**.
It saves time by storing proxy details for quick switching, enhances privacy
by routing browser traffic through different servers, and supports multiple
proxies for varied use cases.
Check your IP address using an online tool like [IP API](https://ip-api.com/)
or follow this guide: [Verify Proxy
Connection](/proxy-setup/verify-proxy-connection).
Make sure you entered the correct proxy details (host, port, username,
password), try reconnecting, and check that your proxy plan is active in the
Geonode Dashboard.
Yes, but some sites may block proxies. If that happens, switch to a different
server or location.
Yes, but using a VPN and a proxy simultaneously may cause slower speeds or
connection conflicts.
Yes, it’s free to install, but you’ll need an active Geonode Proxy Plan to use
proxy services.
# Some Apps Are Not Using the Proxy (/docs/guides/fixing-common-issues/apps-bypassing-proxy)
Some applications may bypass proxy configurations, causing inconsistent behavior or incorrect IP routing.\
This guide explains why that happens and how to fix it.
***
## Common Symptoms
| Issue | Description |
| --------------------------- | -------------------------------------------------------------------------------- |
| **App ignores proxy** | The app connects directly to the internet instead of routing through your proxy. |
| **Inconsistent IP results** | IP changes work in the browser but not in the app. |
| **Authentication errors** | The app doesn’t support proxy login credentials. |
***
## Steps to Fix
### 1. Use a Proxy-Compatible Browser
Some built-in browsers (like Edge WebView or internal app browsers) ignore system proxy settings.\
✅ Try using **Google Chrome**, **Mozilla Firefox**, or **Brave**, which fully support proxies.
***
### 2. Check App Proxy Settings
Certain apps have their **own proxy configuration** separate from the system.\
🛠 Open the app’s **Network** or **Connection** settings and enter your proxy details manually.
***
### 3. Confirm Proxy Authentication Type
If your proxy requires **username/password authentication**, make sure the app supports it.\
Some mobile or desktop apps only support IP whitelisting instead.
***
### 4. Use a VPN as an Alternative
If the app completely ignores proxy settings, use a **VPN** service instead.\
VPNs tunnel all traffic system-wide, ensuring every app is routed through the same network path.
***
## FAQs
Some apps do not support proxy connections or require manual configuration.
{" "}
Only by using a VPN or a system-level proxy manager that intercepts all
connections.
Usually no — browsers like Chrome and Firefox respect system or manual proxy settings.
***
## Summary
* Some apps ignore system proxy settings by design.
* Always check if the app has its own proxy configuration field.
* Use Chrome or Firefox for consistent proxy testing.
* If nothing works, switch to a VPN or a proxy manager for full traffic control.
# Frequent Authentication Pop-Ups (/docs/guides/fixing-common-issues/authentication-popups)
If you keep getting authentication pop-ups while using a proxy — like this:
— it usually means there’s an issue with authentication or IP whitelisting.\
Follow these steps to fix it.
***
## Troubleshooting Steps
### 1. Whitelist Your IP Address
If your IP is not whitelisted, the proxy will repeatedly ask for credentials.\
👉 [How to Whitelist My IP](/docs/guides/advance-configuration/whitelist-ip)
***
### 2. Check Your Login Credentials
Ensure that you’re using the correct **username** and **password** for your Geonode proxy.\
Incorrect or expired credentials will trigger the authentication window every time.
***
### 3. Use an Authentication-Supported App
Some browsers or apps do not handle proxy authentication correctly.\
✅ Try using **Google Chrome**, **Mozilla Firefox**, or another modern browser that supports proxy logins.
***
## FAQs
Your IP may not be whitelisted, or you might be using an incompatible browser.
No, authentication is required for secure proxy usage.\
To avoid pop-ups, whitelist your IP so the proxy doesn’t ask for credentials.
***
## Summary
* Repeated pop-ups usually mean your IP isn’t whitelisted.
* Double-check your proxy username and password.
* Use a browser that supports proxy authentication.
* Whitelisting your IP eliminates most repeated login prompts.
# Proxy Connection Keeps Dropping (/docs/guides/fixing-common-issues/connection-dropping)
If your proxy connection keeps disconnecting or timing out, this guide will help you identify the cause and fix it quickly.
***
## Troubleshooting Steps
### 1. Ensure Your Internet Connection Is Stable
Unstable or weak internet can cause frequent proxy disconnections.\
✅ Try switching to a wired connection or move closer to your Wi-Fi router.
***
### 2. Reconfigure Proxy Settings
Incorrect or outdated proxy settings may cause the connection to drop.\
🛠 Go to your **Network or Wi-Fi Settings**, remove the existing proxy configuration, and re-enter your **Geonode proxy details**.
***
### 3. Restart Your Router
If you’re on a home or shared Wi-Fi network, restart your router.\
This helps clear temporary network conflicts that might interrupt proxy communication.
***
### 4. Test With Another App or Browser
Try connecting your proxy in a different browser or app.\
If the issue doesn’t repeat, it may be caused by the original app’s network configuration.
***
## FAQs
The most common causes are unstable internet connections or incorrect proxy configuration.
{" "}
Sometimes — switching to a different port can bypass temporary routing issues.
Not necessarily. Check if your connection is stable and test the same proxy on another device before assuming downtime.
***
## Summary
* Check and stabilize your internet connection.
* Re-enter your proxy credentials and configuration.
* Restart your router to clear temporary issues.
* Test on a different app or browser to isolate the problem.
# Proxy Not Changing My IP (/docs/guides/fixing-common-issues/ip-not-changing)
If your IP address doesn’t change after setting up a proxy, it’s usually due to app configuration or proxy setup issues.\
Follow these steps to verify and fix the problem.
***
## Troubleshooting Steps
### 1. Check Your IP on a Verification Site
Visit [ShowMyIP](https://www.showmyip.com/) or [ip-api.com](https://ip-api.com/) to confirm whether your IP has actually changed.\
Sometimes, caching or DNS delays can make it look like your IP is the same.
***
### 2. Restart Your Browser or App
After updating proxy settings, restart your browser or app to apply the configuration.\
⚙️ Some apps only load proxy settings at startup — a restart ensures they take effect.
***
### 3. Ensure Your App Supports Proxies
Certain applications bypass system proxy settings entirely.\
✅ Try testing your proxy using **Google Chrome**, **Firefox**, or another proxy-compatible browser.
***
### 4. Confirm Manual Configuration
Double-check that your proxy details were entered correctly under **Manual Proxy Setup** (IP, Port, Username, and Password).\
A missing field or typo can prevent the proxy from activating.
***
### 5. Test Another Proxy Type
If your IP still doesn’t change, switch between **HTTP** and **SOCKS5** proxies to see if the app or service supports one better than the other.
***
## FAQs
Some apps bypass system proxy settings. Test using a proxy-compatible browser like Chrome or Firefox.
{" "}
Yes — some websites detect your previous session via cookies or cache, even
after the IP changes.
Yes. If a VPN is active, it overrides proxy routing. Disable VPNs before testing proxy connections.
***
## Summary
* Verify your IP with an external site like ShowMyIP or ip-api.com.
* Restart your app to apply new proxy settings.
* Ensure the proxy is configured correctly and supported by your application.
* Disable VPNs or conflicting network tools before testing.
# No Save Option in Proxy Settings (/docs/guides/fixing-common-issues/no-save-option)
If your device doesn’t show a **“Save”** button when setting up a proxy, don’t worry — some systems handle proxy saving automatically.\
Follow the steps below to confirm your settings are applied correctly.
***
## Troubleshooting Steps
### 1. Exit Settings After Configuration
On many devices, proxy changes are **auto-saved** as soon as you leave the settings page.\
Try exiting the menu normally — the configuration is likely already active.
***
### 2. Restart Your Device
If changes don’t take effect immediately, restart your device.\
A quick reboot often forces the system to apply pending network configurations.
***
### 3. Try Another Network
Some Wi-Fi networks or administrators **block proxy changes** for security reasons.\
Connect to a different network and try setting up the proxy again.
***
## FAQs
Some devices automatically save proxy configurations when you exit the settings menu.
{" "}
Usually no — but restarting can help apply the settings if the proxy doesn’t
activate immediately.
Yes. Most operating systems save proxy settings silently once you leave the configuration screen.
***
## Summary
* Many systems auto-save proxy settings when you close the menu.
* Restarting your device applies the new configuration if it doesn’t activate right away.
* If settings still don’t apply, try switching to a different Wi-Fi network.
# Pages Not Loading After Proxy Setup (/docs/guides/fixing-common-issues/pages-not-loading)
If web pages fail to load or load slowly after setting up a proxy, this guide will help you identify and fix the issue.
***
## Troubleshooting Steps
### 1. Check Proxy Server Status
Make sure your proxy is **active and running** on the [Geonode Dashboard](https://app.geonode.com/).\
If it’s inactive or expired, your connection requests won’t go through.
***
### 2. Disable and Re-enable the Proxy
Sometimes, reapplying the configuration helps.\
Go to your **Wi-Fi or Network Settings**, disable the proxy, save changes, and then enable it again.
***
### 3. Clear Browser Cache
Cached or outdated data can conflict with new proxy settings.\
🧹 Clear your browser cache and cookies, then restart the browser or app.
***
### 4. Try a Different Network
Some Wi-Fi networks — especially in offices or public places — block proxy connections via firewalls.\
✅ Test your proxy setup using a different Wi-Fi or mobile hotspot.
***
### 5. Test the Proxy
Visit [ShowMyIP](https://www.showmyip.com/) or [ip-api.com](https://ip-api.com/) to confirm whether your proxy is active and your IP address has changed.
***
## FAQs
Some websites block certain proxy servers or IP ranges. Try switching to another proxy location or type (HTTP/SOCKS5).
{" "}
Visit [ShowMyIP](https://www.showmyip.com/) or
[ip-api.com](https://ip-api.com/) to confirm your proxy IP and location.
Yes. Cached DNS and cookies can store old network data that conflicts with new proxy settings.
***
## Summary
* Verify your proxy is active and properly configured.
* Reapply proxy settings if pages aren’t loading.
* Clear your browser cache and restart the app.
* Test with another network or proxy location if the issue persists.
# Proxy Not Working (/docs/guides/fixing-common-issues/proxy-not-working)
If your proxy isn’t working or failing to connect, follow these steps to diagnose and fix the issue.
***
## Troubleshooting Steps
### 1. Check Proxy Details
Make sure you’ve entered the **correct Proxy IP and Port** from your [Geonode Dashboard](https://app.geonode.com/).\
⚠️ A small typo in the IP or port number can prevent the connection entirely.
***
### 2. Restart Your Device
After configuring the proxy, **restart your device** to ensure the settings are properly applied.
***
### 3. Switch Networks
Try switching between **Wi-Fi and mobile data**.\
Some networks — especially corporate or public ones — block proxy traffic for security reasons.
***
### 4. Verify Proxy Compatibility
Not all applications support proxies equally.\
✅ Test your proxy with a browser like **Google Chrome** or **Firefox** to confirm it works as expected.\
If it does, the issue might be app-specific.
***
### 5. Check Proxy Authentication
If your proxy requires credentials, double-check your **username** and **password**.\
Incorrect authentication can prevent the proxy from connecting.
***
## FAQs
Ensure that you entered the correct Proxy IP, Port, Username, and Password. Also, confirm that the proxy is active in your Geonode Dashboard.
{" "}
Yes. In most cases, you’ll need to manually enter proxy details in your
device’s or browser’s network settings.
Some apps bypass system proxy settings. Try using a proxy-compatible browser or configure the proxy directly within the app.
***
## Summary
* Double-check Proxy IP, Port, and authentication credentials.
* Restart your device to apply settings.
* Try a different network or browser to test compatibility.
* If the proxy works elsewhere, the issue is likely app-specific.
# Troubleshooting Proxy Issues on Android (/docs/guides/fixing-common-issues/troubleshooting-common-issue)
Setting up a proxy on Android can surface the same issues covered in other troubleshooting guides (no connection, pages not loading, repeated auth prompts, etc.). To avoid duplication, this page highlights only Android-specific checks and points you to the detailed articles for each issue.
***
## Quick Android Checks
* Ensure the proxy is set under **Wi‑Fi → Advanced → Proxy → Manual** for the network you’re using.
* Some Android apps bypass system proxies; test with **Chrome** or **Firefox** first.
* Toggle Wi‑Fi off/on or reboot the device after changing proxy settings.
* If using IP whitelist, confirm your current IP is added in the dashboard.
***
## Issue Index (Android)
* **Proxy not working** — follow the main guide and re-check Wi‑Fi manual proxy config on Android: [Proxy Not Working](/docs/guides/fixing-common-issues/proxy-not-working)
* **Pages not loading** — see the primary steps for slow/no load; on Android also re-apply the proxy on the current Wi‑Fi: [Pages Not Loading](/docs/guides/fixing-common-issues/pages-not-loading)
* **Frequent authentication pop-ups** — confirm IP whitelist or credentials, and use a browser that supports auth prompts: [Authentication Popups](/docs/guides/fixing-common-issues/authentication-popups)
* **IP not changing** — verify the active network has the proxy set and test with a browser: [IP Not Changing](/docs/guides/fixing-common-issues/ip-not-changing)
* **No Save option in proxy settings** — many Android builds auto-save when you back out of settings: [No Save Option](/docs/guides/fixing-common-issues/no-save-option)
* **Connection keeps dropping** — apply the general stability steps and re-enter proxy details on your Wi‑Fi: [Connection Dropping](/docs/guides/fixing-common-issues/connection-dropping)
* **Apps bypassing proxy** — some apps ignore system proxies; use proxy-aware browsers or app-level proxy fields: [Apps Bypassing Proxy](/docs/guides/fixing-common-issues/apps-bypassing-proxy)
***
## Conclusion
Most Android proxy issues are resolved by confirming Wi‑Fi manual proxy settings, using a proxy-aware app, and applying the detailed steps in the linked articles above. If problems persist, visit the [Geonode Documentation](/) or contact **Geonode Support**.
# API Code Generator (/docs/guides/general-proxy-usage/api-code-generator)
The API Code Generator allows you to instantly create code snippets for different programming languages based on your configured proxy parameters.\
This helps you test, integrate, and automate API calls quickly and efficiently.
***
## Step 1: Configure Your Proxy
Before generating code, set up your proxy endpoint.
Follow the guide:\
➡️ [How to Use the Endpoint Generator to Configure a Proxy](/docs/guides/advance-configuration/proxy-configuration)
This ensures you have the correct proxy details ready for code generation.
***
## Step 2: Access the API Code Generator
Once your endpoint is created:
1. Scroll down to the **API Code Generator** section in your dashboard.
2. You will see code automatically generated based on your proxy configuration.
3. The code is available in multiple programming languages, including:
* Python
* Node.js
* Go
* And others
***
## Step 3: Copy and Paste the Code
1. Choose your preferred language.
2. Copy the generated code snippet.
3. Paste it into your development environment or editor (e.g., VS Code, PyCharm, GoLand).
***
## Step 4: Run the Code
Example: Running the Python code in **VS Code**.
If your snippet uses Python’s `requests` package, install it first:
```bash
pip install requests
```
Then run your file:
`python app.py`
***
## Step 5: Verify the Output
After running the script, check the console or terminal.
The output should display the expected data from your API call, confirming that your proxy and code are properly configured.
You’re now ready to generate, customize, and run API code seamlessly with Geonode.
# Usage Stats & Analytics (/docs/guides/general-proxy-usage/usage-stats-analytics)
This guide explains how to track, analyze, and optimize your proxy usage using the Geonode dashboard.\
Monitoring usage statistics helps you manage bandwidth efficiently, improve performance, and troubleshoot issues early.
***
## Step 1: Access the Geonode Dashboard
1. Log in to your **Geonode account**.
2. Open the **Dashboard** to see an overview of your key information:
* Available bandwidth
* Billing cycle and renewal dates
***
## Step 2: View Usage Statistics
In the **Statistics** section, you can explore detailed proxy performance metrics.
### Request Metrics
A visual overview of your request activity, including:
* **Successful Requests** – Proxies that connected successfully.
* **Failed Requests** – Requests that encountered errors or blocks.
* **Total Requests Sent** – The complete count of requests made through your proxies.
***
### Data Usage Monitoring
Keep track of your bandwidth and usage trends:
* **Daily Bandwidth Consumption** – See how much data is used each day.
* **Hourly Usage Trends** – Identify peak usage hours to optimize resources and balance workloads.
This information helps you spot inefficiencies and adjust configurations for better proxy performance.
***
## Final Tips
* Check usage regularly to ensure efficient proxy operation.
* Review failed requests to identify network or configuration issues.
* Use hourly and daily analytics to optimize your bandwidth strategy.
By leveraging Geonode’s analytics tools, you can maintain stable connections, reduce errors, and optimize your proxy performance.
# How to Set Proxy Session Lifetime (/docs/guides/how-to/identifying-session-lifetime)
This guide explains how to configure session lifetime in Geonode to control how long each proxy session stays active.
***
## What Is Session Lifetime
Session lifetime defines how long a proxy connection remains active before resetting.\
Setting the right duration helps to:
* Maintain session consistency for account management.
* Optimize proxy usage for scraping, automation, and security.
* Prevent detection by avoiding overly frequent IP changes.
***
## Ways to Configure Session Lifetime
You can set session lifetime in two ways:
1. Through the Geonode Dashboard (covered in this guide).
2. Via an API request → [Set Session Lifetime via API](/docs/api-reference/sticky-session/get-create/get).
***
## Step 1: Select a Service or Product
Make sure you have an active **Residential Proxies** plan in your Geonode account.\
From the sidebar, open **Proxy Configuration** to start setting up your proxies.
***
## Step 2: Configure Your Proxy
1. In **Proxy Configuration**, select the **Sticky** proxy type.
2. Choose a proxy protocol: **HTTP/HTTPS** or **SOCKS5**.
* Changing session lifetime automatically updates the generated proxy list.
* The new duration will apply to all selected sessions.
***
## Step 3: Set the Session Lifetime
By default, session lifetime is **10 minutes**, but you can adjust it as needed.
* **Minimum:** 3 minutes
* **Maximum:** 24 hours (1440 minutes)
You can enter the value in either minutes or hours, depending on your preference.
You can change this setting directly in the Dashboard or through the API.
***
* Use shorter sessions for frequent IP changes (for example, scraping). -
Choose longer sessions for stability in login or account-based workflows. -
Adjust settings as needed to balance performance and anonymity.
# How to Release Sticky Sessions (/docs/guides/how-to/release-a-sticky-session)
This guide explains how to release sticky sessions in Geonode to refresh your proxy connection, switch to a new IP, or free up resources.
***
## Why Release a Sticky Session
Releasing a sticky session ends your current connection and starts a new one.\
This helps when you need to:
* Switch to a different proxy IP.
* Free up resources such as ports or threads.
* Improve security by refreshing your active session.
***
## How to Release Selected Sticky Sessions
Follow these steps to release specific sticky sessions from your Geonode Dashboard.
### Step 1: Select the Sessions to Release
1. Go to the **Active Sticky Sessions** section in your Geonode Dashboard.
2. Select the sessions you want to release — you can select multiple at once.
***
### Step 2: Release Selected Sessions
1. After selecting sessions, click **Release Selected**.
2. Confirm by clicking **Release Sessions**.
3. A success notification will appear once the sessions are released.
***
## How to Release All Sticky Sessions
To disconnect all active sessions at once:
1. Click **Release All Sessions** in the Dashboard.
2. Confirm by selecting **Release All**.
3. All active connections will be immediately terminated.
***
* If a sticky session shows slow performance or fails to connect, release it
to get a new IP. - Use **Release Selected** for specific sessions and
**Release All** for bulk actions. - Refresh sticky sessions periodically to
maintain security and performance.
# How to Use the Secure EU Gateway (France – Whitelisted IP Only) (/docs/guides/how-to/use-the-secure-eu-gateway)
To ensure maximum uptime and performance, Geonode provides a secure EU gateway available only to paying users.\
This gateway offers enhanced reliability and protection through IP whitelisting.
***
## Gateway Details
* **IP Address:** 92.204.164.13
* **Hostname:** prod-proxy.geonode.io
* **Location:** France
* **Name:** France (Whitelisted IP Only)
* **Access Type:** IP-whitelisted access for paid users only
***
## How to Use
1. Log in to your **Geonode Dashboard**.
2. Go to the **IP Whitelist** section.
3. Add your current IP address.
4. In your proxy configuration, select the gateway location: *France (Whitelisted IP Only)*.
5. Save your configuration and connect through the new gateway.
***
Access will be denied for any requests coming from non-whitelisted IP
addresses.
This gateway is recommended for users who need higher reliability and tighter access control.
# Android (/docs/guides/mobile-OS/android)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import PopupAuth from "../../../snippets/popup-auth.mdx";
Android settings may look slightly different depending on the device model and
Android version, but the overall process remains the same.
***
***
## Step-by-step setup for Android
### Step 1 — Open Settings
1. Tap the **Settings** app (gear icon).
***
### Step 2 — Go to Wi-Fi Settings
1. Scroll down and tap **Network & Internet** or **Wi-Fi**, depending on your device.
2. Tap and hold the Wi-Fi network you’re connected to.
3. Select **Modify network** or tap the gear (⚙) or “i” icon next to the Wi-Fi name.
Ensure Wi-Fi is turned on and connected to the network you want to configure
the proxy for.
***
### Step 3 — Access Wi-Fi List
You will now see a list of available Wi-Fi networks.
***
### Step 4 — Find Proxy Settings
1. Scroll down until you find **Proxy settings**.
2. Tap **Proxy** to expand available options.
You’ll also see your current IP address — write it down for future reference.
***
### Step 5 — Choose Manual Configuration
Select **Manual** from the proxy settings.
***
### Step 6 — Enter Proxy Details
1. Enter the **Proxy IP Address** and **Port** from your Geonode Dashboard.
***
### Step 7 — Save and Exit
1. Scroll down and tap **Save** to apply the settings.
2. If your device doesn’t have a Save button, simply exit — the configuration will be applied automatically.
***
***
***
# iOS (/docs/guides/mobile-OS/ios)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import PopupAuth from "../../../snippets/popup-auth.mdx";
***
***
## Step-by-step setup for iOS
Follow these steps to configure your proxy manually:
### Step 1 — Open iPhone Settings
1. Open the **Settings** app.
2. Tap **Wi-Fi** to view available networks.
***
### Step 2 — Access Wi-Fi Network Settings
1. Connect to the Wi-Fi network you want to configure.
2. Tap the **“i” icon** next to the connected network.
***
### Step 3 — Navigate to Proxy Settings
1. Scroll down to the **HTTP Proxy** section.
2. You will see three options:
* **Off** — disables proxy
* **Manual** — enter proxy details manually
* **Automatic** — configure using a PAC file
Select **Manual** for your Geonode proxy setup.
***
### Step 4 — Enter Proxy Details
1. Under **Manual Proxy Configuration**, fill in:
* **Server:** Proxy IP address
* **Port:** Port number from your Geonode Dashboard
2. If authentication is required, enable **Authentication** and enter your **username** and **password**.
3. Tap **Save** to apply the settings.
***
***
***
# Access Credentials (/docs/guides/prerequisites/access-credentials)
***
To use Geonode's proxy services or API, you need authentication credentials. These credentials include a **username** and **password**, which allow you to securely connect to the service.
This guide will help you:\
✔️ Access your credentials from the Geonode dashboard.\
✔️ Secure them properly to prevent unauthorized access.\
✔️ Use them for authentication in API requests.
### Access Your Dashboard
* **Login to Geonode Dashboard:**
Visit [Geonode Dashboard](https://app.geonode.com/) and log in using your credentials.
* **Navigate to Proxy Section:**
Go to the **Proxies** section in the dashboard.
* **Get Your User Credentials:**
* **Username:** Copy your unique API username.
* **Password:** Copy your API password.
* **Secure Your Credentials:**
Keep your API credentials safe and never share them publicly
Once you've obtained your API credentials, you're ready to make your first API request or configure your proxy.
# Proxy Server Information (/docs/guides/prerequisites/proxy-server-information)
***
To connect to Geonode's proxy network, you need the **Proxy IP** and **Port**.
These details allow you to configure your applications, scripts, or browser to route traffic through Geonode's servers.
## Steps: Get Proxy Credentials from Geonode
1. Login to the Geonode Dashboard
Visit [Geonode Dashboard](https://app.geonode.com/) and sign in.
2. Go to the Proxy Section\
Navigate to the Proxies section to access your assigned proxy details.
3. Select the proxy format as: `hostname:port:username:password`
4. Copy the proxy details from the Geonode dashboard.
* Proxy IP: This is the server address you will use.
* Port: The port number required to establish a connection.
OR
Copy Your Proxy dns and Port
5. **Save These Details Securely**\
Do not share your proxy details publicly to avoid unauthorized usage.
## Next Steps
Once you have your proxy IP and port, you can:\
✔️ Use them in API requests.\
✔️ Configure them in your browser, terminal, or scripts.
# Rotating Proxies (/docs/guides/proxy-api-management/rotating-proxies)
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
import ExtensionFAQs from "../../../snippets/extensions-faqs.mdx";
This guide walks you through how to use Rotating Proxies in Geonode.
***
## What Are Rotating Proxies
Rotating proxies automatically change your IP address with every request.\
This feature helps maintain anonymity, prevent detection, and ensure smoother automation.
➡️ For a detailed explanation, see [What Are Rotating Proxies](/docs/guides/proxy-service-guide/rotating-proxies)
***
## Geonode's Rotating Proxies Range
Geonode provides rotating proxies via HTTP and SOCKS5 protocols, with the following ports:
* **HTTP:** 9000–9010
* **SOCKS5:** 11000–11010
Each request you send will use a new IP address from a different location, helping to avoid IP-based blocking.
***
## How to Use Rotating Proxies with the Geonode API
### Step 1: Configure Your Proxy Settings
In your Geonode dashboard:
1. Open **Proxy Configuration**.
2. Select:
* IP Type: *Residential*
* Gateway: *France* (or your preferred location)
* Protocol: *HTTP/HTTPS* or *SOCKS5*
* Session Type: *Rotating*
Example configuration:
***
### Step 2: Generate Proxy Endpoints
Once configured, generate your proxy endpoints.\
They will typically look like this:
```
92.204.164.15:9000:geonode_demouser-type-residential:demopass
```
Each endpoint includes your IP, port, and authentication credentials (username and password).
***
### Step 3: Make API Calls Using Rotating Proxies
Here’s a Python example using the `requests` library:
```python
import requests
username = "geonode_demouser-type-residential"
password = "demopass"
GEONODE_DNS = "92.204.164.15:9000"
url = "http://ip-api.com"
proxy = {
"http": f"http://{username}:{password}@{GEONODE_DNS}"
}
response = requests.get(url, proxies=proxy)
print("Response:\n", response.text)
```
Each request will use a different IP address from Geonode’s proxy pool.
***
***
***
## FAQs
{" "}
{" "}
Yes. You can add multiple proxies and switch between them by selecting the desired
one and clicking **Connect**.{" "}
{" "}
Rotating proxies: - Maintain anonymity by changing IPs per request. - Prevent
blocks tied to a single IP. - Work perfectly for scraping, SEO, and geo-restricted
access.{" "}
{" "}
* **HTTP:** Best for browsing, scraping, and API requests (HTTP/HTTPS traffic).
* **SOCKS5:** More flexible, supporting FTP, VoIP, and P2P connections.{" "}
{" "}
Yes, you can configure rotating proxies to target countries, cities, or ISPs
to get region-specific IPs.{" "}
{" "}
If one proxy IP is blocked, Geonode automatically rotates to a new IP from the
pool on the next request.{" "}
{" "}
Absolutely. They’re ideal for scraping since each request uses a new IP, reducing
the risk of detection.{" "}
{" "}
You can track requests, performance, and errors directly from your Geonode dashboard.{" "}
{" "}
Usually, yes. Rotating proxies provide better anonymity and resistance to bans,
while static proxies are easier to track and block.{" "}
{" "}
# ASN/ISP Targeting (/docs/guides/proxy-service-guide/asn-isp-targeting)
This guide explains what ASN/ISP targeting is and how to use it in Geonode for precise proxy control and optimized network performance.
## What Is ASN/ISP Targeting?
**ASN/ISP targeting** allows you to filter proxy connections based on an Internet Service Provider (ISP) or **Autonomous System Number (ASN)**.\
This helps you choose proxies from specific ISPs to improve reliability, compliance, and performance for targeted use cases.
## How ASN/ISP Targeting Works
* Every ISP is assigned a unique ASN (Autonomous System Number).
* Geonode enables users to select proxies by **country** and **ASN**.
* This is especially useful for:
* Accessing geo-restricted content
* Market research
* Increasing connection consistency and anonymity
### Example: Targeting a Specific ASN
To target a specific ISP, include both the country code and the ASN in your request:
```text
country-us-asn-7018
```
# Proxy Endpoint Formats (/docs/guides/proxy-service-guide/endpoint-formats)
This guide explains what proxy endpoints are, the types available in Geonode, and how to choose the most suitable format for your specific use case.
## What Is a Proxy Endpoint?
A **proxy endpoint** is the address used to connect to a proxy server.\
It defines how your requests are routed through Geonode’s network, ensuring secure, reliable, and efficient data transmission.
## DNS vs. IP-Based Endpoints
Geonode allows users to connect either via a **DNS-based hostname** or a **direct IP address**.
### 1. DNS-Based Endpoints (Recommended)
* Use a domain name such as `proxy.geonode.io`.
* Easier to maintain — DNS automatically updates IPs when servers change.
* Reduces connection issues caused by IP rotation.
### 2. IP-Based Endpoints
* Use a direct IP address, e.g. `123.45.67.89:9000`.
* Skips DNS resolution, which can be slightly faster in some setups.
* Ideal for apps or devices that **don’t support DNS hostnames**.
## Available Endpoint Formats
Geonode supports multiple endpoint formats to ensure compatibility with different systems and authentication methods.
### 1. `hostname:port`
* Example: `proxy.geonode.io:9000`
* Best for: Simple connections without authentication.
### 2. `hostname:port:username:password`
* Example: `proxy.geonode.io:9000:user:pass`
* Includes authentication credentials for secure access.
* Best for: APIs and applications requiring basic authentication.
### 3. `hostname:port@username:password`
* Example: `proxy.geonode.io:9000@user:pass`
* Alternative authentication format.
* Best for: Legacy or custom proxy clients.
### 4. `username:password@hostname:port`
* Example: `user:pass@proxy.geonode.io:9000`
* Credentials placed before the host for compatibility.
* Best for: Apps that authenticate before establishing a connection.
### 5. `http://username:password@server:port`
* Example: `http://user:pass@proxy.geonode.io:9000`
* Explicit HTTP/HTTPS proxy format.
* Best for: Secure browsing and authenticated API requests.
## Choosing the Right Proxy Endpoint Format
| Format | Best For |
| -------------------------------------- | --------------------------------------------- |
| `hostname:port` | Standard connections without authentication |
| `hostname:port:username:password` | Secure authentication for APIs & applications |
| `hostname:port@username:password` | Custom or legacy proxy configurations |
| `username:password@hostname:port` | Systems needing pre-authentication |
| `http://username:password@server:port` | Secure browsing, authenticated API access |
## Tips and Best Practices
* **Start simple:** Use `hostname:port` if no authentication is required.
* **Prefer DNS:** It’s more reliable and updates automatically.
* **Use IP endpoints** only for tools that can’t resolve hostnames.
* **Always use HTTPS** or encrypted channels when handling sensitive credentials.
* Test different formats — some apps accept only specific syntaxes.
## Summary
Proxy endpoints define how your connection routes through Geonode’s network.\
Choosing the correct format ensures:
* Smooth compatibility with your app or client,
* Secure authentication where required,
* Stable performance with minimal downtime.
# Gateways (/docs/guides/proxy-service-guide/gateway)
This guide explains what proxy gateways are and how Geonode uses them to optimize proxy routing, improve performance, and maintain anonymity.
## What Is a Proxy Gateway?
A **proxy gateway** is a server that routes your internet traffic through a specific geographic location.\
By selecting a gateway, you define the **entry point** for your proxy requests — controlling how and where your traffic appears to originate.
Geonode provides multiple gateway locations to:
* Access region-restricted content
* Improve browsing speed and stability
* Maintain privacy and network anonymity
## Geonode’s Available Gateways
Geonode currently offers the following gateway locations:
* **France**
* **United States**
* **Singapore**
Each gateway routes your traffic through a regional hub, providing faster speeds and greater accessibility for local or restricted online services.
## Why Use a Gateway?
### 1. Access Geo-Restricted Content
* Browse the internet as if you’re in another country
* Useful for streaming, e-commerce, and international research
### 2. Improve Connection Speed
* Routes traffic through optimized, low-latency locations
* Reduces delay and improves access to nearby content
### 3. Enhance Privacy and Security
* Masks your real IP and location
* Adds a layer of protection when using public or sensitive networks
## Choosing the Right Gateway
| Gateway | Best For |
| ----------------- | -------------------------------------------------------------- |
| **France** | EU-based content, GDPR-compliant data collection |
| **United States** | Streaming, U.S. market research, and e-commerce |
| **Singapore** | Low-latency connections in Asia, accessing region-locked sites |
## Tips and Best Practices
* **Use the closest gateway** to minimize latency and maximize performance.
* **Select gateways strategically** based on your target region or content source.
* **Switch gateways** if your connection feels slow — load balancing can vary by region.
## Summary
Proxy gateways determine where your connection enters Geonode’s network.\
By selecting the right gateway, you can:
* Improve connection speed,
* Access region-specific content,
* And enhance your overall privacy and anonymity online.
# Geo-Targeting (/docs/guides/proxy-service-guide/geo-targeting)
This guide explains what Geo-Targeting is and how Geonode allows you to choose proxies based on country, state, and city for precise connection control and regional flexibility.
## What Is Geo-Targeting?
**Geo-Targeting** lets you filter and select proxy locations by **country**, **state**, and **city**.\
It enables businesses, developers, and marketers to access content and services as if they were browsing directly from a specific geographic area.
## How Geo-Targeting Works in Geonode
Geonode supports **three levels of geo-targeting**, shown in the example below:
1. **Country Targeting** – Select a country for your proxy connection.
2. **State Targeting** – Choose a particular state or region within that country.
3. **City Targeting** – Narrow it down further by selecting a specific city, or set it to **Any** for broader access.
## Why Use Geo-Targeting?
### 1. Access Geo-Restricted Content
* Bypass region-based restrictions on websites, apps, and streaming services.
* View local search engine results, prices, and ads as a user from that area.
### 2. Improve Localized Testing and Marketing
* Run **ad verification** and A/B tests by region.
* Test **localized websites, apps, and payment systems** from multiple markets.
### 3. Ensure Compliance and Security
* Simulate user behavior from different regions for compliance testing.
* Avoid detection by using realistic, location-accurate IPs.
## Choosing the Right Geo-Targeting Option
| Geo-Targeting Level | Best For |
| --------------------- | --------------------------------------------------------------------- |
| **Country Targeting** | General browsing, international research, region-based content access |
| **State Targeting** | Regional services, ad verification, localized e-commerce |
| **City Targeting** | Precision testing, local SEO, hyper-targeted ad campaigns |
## Notes and Recommendations
* The availability of **state** and **city** targeting depends on the selected country.
* Some cities may have fewer proxy IPs — use **“Any”** for better coverage.
* For faster performance, select a location closer to your target audience or testing region.
## Best Practices
* Use **Country Targeting** for broad, region-specific access.
* Choose **State** or **City Targeting** for more precise, location-based control.
* Start with **Country Targeting** and refine your selection as needed for campaigns or tests.
## Summary
Geo-Targeting gives you granular control over your proxy location — from country down to city level.\
By choosing the right targeting depth, you can:
* Access localized content,
* Run accurate regional tests, and
* Optimize performance for specific markets.
# IP Address (/docs/guides/proxy-service-guide/ip-address)
This guide explains what an IP address is, how it functions, and why it’s important when using proxies.
## What Is an IP Address?
An **IP address (Internet Protocol Address)** is a unique identifier assigned to every device connected to the internet.\
Think of it as a mailing address for your device — without it, data wouldn’t know where to go.
When you visit a website, your IP address tells the site where to send the information you requested.\
It can also reveal your **approximate location**, **internet provider**, and **network type**.
## How IP Addresses Work
* Every device gets an IP address from its **Internet Service Provider (ISP)**.
* When you make a request (like opening a website), your IP acts as a return address.
* The server sends data back to that address — completing the connection.
## Types of IP Addresses
There are several types of IPs depending on their use, assignment method, and format.
### 1. Public vs. Private IP Addresses
| Type | Description |
| ---------------------- | --------------------------------------------------------------------------- |
| **Public IP Address** | Assigned by your ISP and used to communicate over the internet. |
| **Private IP Address** | Used within local networks (e.g., home Wi-Fi) to identify internal devices. |
### 2. Static vs. Dynamic IP Addresses
| Type | Description |
| ---------------------- | -------------------------------------------------------------------- |
| **Static IP Address** | Fixed and unchanging. Common for servers, businesses, and VPNs. |
| **Dynamic IP Address** | Changes periodically. Used by most home connections for flexibility. |
### 3. IPv4 vs. IPv6
| Type | Description |
| -------- | -------------------------------------------------------------------------------- |
| **IPv4** | Classic format with four number sets, e.g. `192.168.1.1`. Still the most common. |
| **IPv6** | Newer format supporting many more devices, e.g. `2001:db8::ff00:42:8329`. |
## Why IP Addresses Matter in Proxies
When using proxies, your **real IP** is replaced with another one — masking your location and identity.\
This provides privacy, allows region-based access, and reduces the risk of detection or blocking.
### 1. Residential vs. Datacenter IPs
| Type | Description |
| ------------------- | ------------------------------------------------------------------------------- |
| **Residential IPs** | Provided by ISPs to real devices. Highly trusted and less likely to be flagged. |
| **Datacenter IPs** | Generated by data centers or hosting services. Faster, but easier to detect. |
### 2. Rotating vs. Sticky IPs
| Type | Description |
| ---------------- | ------------------------------------------------------------------------------------ |
| **Rotating IPs** | Change with every request or at timed intervals — ideal for scraping and automation. |
| **Sticky IPs** | Remain constant for a session — best for logins, account management, or testing. |
## How to Check Your IP Address
You can easily find your public IP:
* Search **“What is my IP”** on Google.
* Visit [whatismyip.com](https://www.whatismyip.com).
* Check network details in your router or device settings.
## Tips and Best Practices
* Use proxies to protect your identity and location online.
* **Residential IPs** → more privacy and authenticity.
* **Datacenter IPs** → more speed and cost efficiency.
* **IPv6** is expanding, but **IPv4** remains dominant for most users.
* Choose a reliable provider like **Geonode** to balance **security, anonymity, and performance**.
## Summary
An IP address is your device’s online identifier — essential for routing internet traffic.\
Using a proxy lets you control or hide that identity, giving you:
* More **privacy**,
* Better **regional access**, and
* Stronger **protection** online.
# IP Types (/docs/guides/proxy-service-guide/ip-type)
This guide explains what IP types are and how Geonode provides them for different proxy use cases.
## What Are IP Types?
**IP types** define how an IP address is sourced and used within proxy networks.\
Geonode offers three main categories:
* **Residential IPs** – Real-user IPs assigned by Internet Service Providers (ISPs).
* **Datacenter IPs** – IPs generated by third-party data centers.
* **Mixed IPs** – A combination of Residential and Datacenter IPs for flexibility.
Each serves a unique purpose — from bypassing geo-restrictions to powering high-speed automation.
## 1. Residential IPs
### What Are Residential IPs?
Residential IPs come from **real user connections** provided by ISPs.\
Because they look like genuine home users, websites see them as legitimate traffic.
### Best For
* Web scraping with minimal detection risk
* Accessing geo-restricted content
* Managing e-commerce or social media accounts
* Secure streaming and gaming
### Pros
✔️ High trust level — less likely to be blocked\
✔️ Works on strict, detection-sensitive sites
### Cons
❌ Slower than datacenter IPs\
❌ More expensive due to limited availability
## 2. Datacenter IPs
### What Are Datacenter IPs?
Datacenter IPs are **server-based IPs** generated by hosting providers, not ISPs.\
They offer higher speed and lower cost but are easier to detect.
### Best For
* Bulk web scraping and data collection
* SEO monitoring and automation
* High-performance or bot-driven tasks
### Pros
✔️ Fast and reliable\
✔️ Cost-effective for large-scale operations
### Cons
❌ Easier to detect and block on strict websites\
❌ Limited success with region-locked or sensitive content
## 3. Mixed IPs
### What Are Mixed IPs?
Mixed IPs combine both **Residential** and **Datacenter** sources — balancing realism and performance.
### Best For
* Scalable web scraping and automation
* Testing and development environments
* Multi-purpose e-commerce or social media tasks
### Pros
✔️ Balanced speed, security, and price\
✔️ Greater flexibility across use cases
### Cons
❌ Not as anonymous as pure Residential IPs\
❌ Some tasks may require dedicated IP types
## Comparison: Residential vs Datacenter vs Mixed
| Feature | Residential IPs | Datacenter IPs | Mixed IPs |
| ------------- | ----------------------------------- | ------------------------------ | ------------------------------------------------ |
| **Speed** | Moderate | Fast | Balanced |
| **Anonymity** | High (real users) | Low (easily detected) | Moderate |
| **Cost** | Expensive | Affordable | Mid-range |
| **Best For** | Geo access, social media, streaming | Bulk scraping, SEO, automation | Versatile tasks needing both reliability & speed |
## How to Choose the Right IP Type
* **Residential IPs** → for high anonymity and geo-specific access.
* **Datacenter IPs** → for fast, large-scale automation.
* **Mixed IPs** → for a balanced approach between performance and stealth.
## Tips and Best Practices
* Start with **Mixed IPs** to test both speed and reliability.
* Use **Residential IPs** for sensitive or geo-restricted sites.
* Use **Datacenter IPs** for speed-critical automation or scraping.
* Always verify which type performs best for your target websites.
## Summary
Each IP type serves a distinct purpose:
* **Residential** for trust and authenticity,
* **Datacenter** for speed and scale,
* **Mixed** for flexibility.
Choosing the right type ensures stable, efficient, and secure proxy performance for your specific needs.
# IP Whitelisting (/docs/guides/proxy-service-guide/ip-whitelist)
**IP whitelisting** is a security feature that allows only approved IP addresses to connect to your network or service.\
It blocks unauthorized access and ensures safer connections.
When using proxies, **whitelisted IPs** let you connect without a password — making access both **simple** and **secure**.
## Benefits of IP Whitelisting
* **Better Security** – Only trusted IPs can connect.
* **More Control** – You decide who can access your system.
* **Easy Access** – No need for manual logins or credentials.
## Best Practices
To maximize security and efficiency, follow these recommendations:
* **Add Only Trusted IPs** – Whitelist secure, verified networks.
* **Use Clear Labels** – Name IPs (e.g., “Home,” “Office”) for easy identification.
* **Review Regularly** – Remove unused or outdated IPs.
* **Combine with Other Tools** – Use firewalls and authentication for layered protection.
## Troubleshooting Common Issues
Ensure your proxy IP is whitelisted — connections may fail if it isn’t.
Add your new IP address from your current location to regain access.
* Verify that you entered the correct **public IP address**.
* Check if your IP has changed and update it in the whitelist.
## Summary
**IP whitelisting** strengthens your proxy setup by restricting access to trusted sources only.\
It simplifies authentication and prevents unauthorized use — ideal for both personal and enterprise environments.
For a detailed setup guide, see:\
➡️ [How to Whitelist Your IP Address](/docs/guides/advance-configuration/whitelist-ip)
# Overview (/docs/guides/proxy-service-guide/overview)
Welcome to the **Proxy Service Guide** — your complete reference for understanding and configuring Geonode proxies.
This guide covers all the essential concepts for effective proxy usage, including:
* **IP Addresses** – Learn how IPs work and why they matter in proxy networks.
* **Proxy Types** – Understand the differences between residential, datacenter, and mixed IPs.
* **Authentication** – Explore IP whitelisting, username/password access, and security best practices.
* **Geo-Targeting** – Configure country, state, and city-level targeting.
* **Ports & Sessions** – Manage connections, rotation, and session persistence.
By mastering these topics, you’ll be able to:
* Optimize connection performance,
* Maintain high security and privacy,
* Avoid detection across different platforms and use cases.
Explore each section to gain a clear, practical understanding of how Geonode proxies work — and how to use them efficiently for your specific needs.
# Ports (/docs/guides/proxy-service-guide/port-type)
This guide explains what ports are, how they work, and why they play a key role in proxy connections.
## What Is a Port?
Imagine your device as an apartment building (your **IP address**) with many rooms inside — these rooms are **ports**.\
Each room serves a different purpose, helping data reach the right application.
* Every device connected to the internet has a unique IP address.
* **Ports** act as doorways that direct data traffic to the correct app or service.
* Each service (browsing, messaging, streaming, etc.) uses its own port number to avoid confusion.
Without ports, your device wouldn’t know which application incoming data belongs to — everything would arrive at the same “door.”
## How Ports Work in Practice
Let’s say you open several browser tabs at once:
* One tab has **WhatsApp Web**,
* Another shows **Facebook**,
* And the third streams **YouTube**.
When a WhatsApp message arrives, your computer needs to know which app it’s for.\
Ports make this possible:
* WhatsApp Web might use **port 5222**,
* Facebook might use **port 443**,
* YouTube might use another.
Your system reads the port number, matches it with the right app, and delivers the data correctly.\
When that session closes, the port becomes available again — these are called **ephemeral ports** (temporary ports for short-lived connections).
## Ports in Proxy Configuration
In proxy setups, ports function like **dedicated lanes** for your traffic.\
Different ports connect to different types of proxy behavior — such as rotating or sticky sessions.
### Common Proxy Ports in Geonode
| Proxy Type | Port Range |
| ------------------- | ----------- |
| **SOCKS5 Rotating** | 11000–11010 |
| **SOCKS5 Sticky** | 12000–12010 |
| **HTTP Rotating** | 9000–9010 |
| **HTTP Sticky** | 10000–10900 |
Each range corresponds to a specific connection type, giving you control over how often your proxy IP changes.
## How to Configure Proxy Ports
When setting up a proxy, choose a port according to your goal:
* **Rotating proxies** → Use ports from the *rotating* range to get a new IP for each request.
* **Sticky proxies** → Use ports from the *sticky* range to keep the same IP for a set duration.
➡️ For detailed setup steps, see:\
[Proxy Port Configuration](/docs/guides/advance-configuration/port-configuration)
## Best Practices
* Treat each **port** as a separate communication channel.
* Choose **rotating** or **sticky** ports depending on your use case.
* Once a port is assigned to a specific country, **remove the assignment** before reusing it.
* Understanding ports helps ensure a stable and efficient proxy connection.
## Summary
**Ports** are the internal “routes” that direct internet traffic where it needs to go.\
In proxy configurations, they define how your connection behaves — rotating for dynamic IPs, sticky for consistent sessions.\
Selecting the right port ensures smooth, secure, and optimized proxy performance.
# Protocol Type (/docs/guides/proxy-service-guide/protocol-type)
Choosing the right **protocol type** is essential for optimizing proxy performance, ensuring security, and maintaining reliable connections.
This guide explains what a protocol is in the context of proxies and helps you decide between **HTTP/HTTPS** and **SOCKS5** for your specific use case.
## What Is a Protocol in Proxy Usage?
A **protocol** is a set of rules that defines how data is transmitted between devices across a network.\
When you use a proxy, the protocol determines **how requests are sent, processed, and returned**.
## Types of Proxy Protocols
Geonode supports two main protocol types:
* **HTTP / HTTPS**
* **SOCKS5**
Let’s explore how they differ — and when to use each.
***
## 1. HTTP / HTTPS Proxies
**HTTP/HTTPS proxies** handle standard web traffic.\
They forward web requests between your browser (or app) and the destination website.\
The **HTTPS** variant encrypts the connection, providing extra privacy and protection.
### Ideal For
* General web browsing
* APIs and web services
* Web scraping and automation
* Managing multiple online accounts
### Key Features
* Easy to configure — compatible with most browsers and apps.
* HTTPS ensures encrypted data transmission.
* Works seamlessly with tools like **Postman**, **cURL**, and browser extensions.
### Port Range
* **Rotating Proxy:** `9000–9010`
* **Sticky Proxy:** `10000–10900`
### Common Use Cases
* **Web Scraping:** Automate data collection while reducing detection risk.
* **Account Management:** Maintain consistent login sessions.
* **API Requests:** Manage large volumes of secure, authenticated requests.
***
## 2. SOCKS5 Proxies
**SOCKS5** is a more flexible and powerful proxy protocol.\
Unlike HTTP, it works at a lower network level and doesn’t alter the transmitted data — making it ideal for **non-web traffic** and privacy-focused applications.
### Ideal For
* Privacy and anonymity
* P2P (peer-to-peer) connections
* Bypassing firewalls and geo-restrictions
* Streaming, gaming, and VoIP
### Key Features
* Supports **both TCP and UDP**, enabling real-time communication.
* Offers **higher anonymity** — does not inject identifying headers.
* Handles all types of traffic: HTTP, FTP, VoIP, gaming, etc.
### Port Range
* **Rotating Proxy:** `11000–11010`
* **Sticky Proxy:** `12000–12010`
### Common Use Cases
* **Bypassing Restrictions:** Access blocked content securely.
* **Torrenting:** Stable and fast peer-to-peer transfers.
* **VoIP & Streaming:** Lower latency and improved connection quality.
***
## How to Choose the Right Protocol
| Criteria | **HTTP / HTTPS** | **SOCKS5** |
| --------------- | ------------------------------ | ----------------------------------- |
| **Security** | HTTPS encryption protects data | High anonymity, supports encryption |
| **Speed** | Fast for web-based traffic | Faster for non-HTTP traffic |
| **Flexibility** | Limited to web requests | Supports all internet protocols |
| **Best For** | Websites, APIs, automation | P2P, VoIP, bypassing firewalls |
***
## Summary
* Use **HTTP/HTTPS** for simplicity, compatibility, and secure web requests.
* Choose **SOCKS5** for advanced use cases, full traffic support, and stronger anonymity.
* If you’re just getting started, start with HTTP/HTTPS — you can always switch to SOCKS5 later as your needs evolve.
# Protocols (/docs/guides/proxy-service-guide/protocols)
Geonode’s proxy network supports several protocols, each designed for different use cases and levels of security.\
Choosing the right protocol ensures compatibility, performance, and privacy when connecting through Geonode.
## Supported Protocols
Geonode currently supports the following proxy protocols:
1. **HTTP** — Hypertext Transfer Protocol
2. **HTTPS** — Hypertext Transfer Protocol Secure
3. **SOCKS5** — Socket Secure version 5
Each protocol serves a specific purpose — from standard web browsing to high-security, high-speed connections.
***
## Protocol Comparison
| Protocol | Security Level | Best For | Availability |
| ---------- | ------------------------- | ----------------------------------------- | ------------ |
| **HTTP** | ❌ No encryption | General web scraping, browsing, APIs | ✅ Supported |
| **HTTPS** | ✅ SSL/TLS encrypted | Secure websites, automation, transactions | ✅ Supported |
| **SOCKS5** | ✅ High anonymity & secure | Streaming, gaming, bypassing restrictions | ✅ Supported |
***
## Unsupported Protocols
The following protocols are **not supported** by Geonode proxies:
* **UDP** (User Datagram Protocol)
* **Email protocols** — such as SMTP, IMAP, and POP3
These protocols operate differently from HTTP/HTTPS and SOCKS5 and are not part of Geonode’s proxy infrastructure.
***
## Best Practices
* Use **HTTP** for general data scraping and standard web requests.
* Choose **HTTPS** for secure, encrypted communication and automated workflows.
* Select **SOCKS5** for streaming, gaming, or tasks requiring maximum privacy and flexibility.
Geonode focuses on stable, encrypted proxy connections — therefore, **UDP and email-related traffic are excluded** for security and performance reasons.
***
## Summary
Geonode supports the three most widely used proxy protocols — **HTTP**, **HTTPS**, and **SOCKS5** — giving users the flexibility to choose between speed, compatibility, and security.\
Pick the protocol that fits your use case and connection needs to ensure optimal performance and reliability.
# Proxy Authentication Methods (/docs/guides/proxy-service-guide/proxy-authentication)
***
This guide will help you understand what the Proxy Authentication method is and the different ways geonode provides to authenticate it.
## **What is Proxy Authentication?**
Proxy authentication is a way to verify your identity before accessing a proxy server. It helps keep your connection secure and ensures only authorized users can use the proxy.
Geonode provides two ways to authenticate:
1. Using a username and password **(Basic Authentication)**
2. Whitelisting your IP address **(IP Authentication)**
Each method has its advantages, depending on your use case.
***
## **1. Authenticating with Username and Password (Basic Authentication)**
This method requires you to send your Geonode proxy username and password with every request. Many applications, APIs, and automation tools support this authentication method.
### **How Basic Authentication Works**
1. Format your credentials as:
```
username:password
```
2. Convert this string to Base64 format (for security).
3. Add the encoded credentials to your request header like this:
```
Authorization: Basic BASE64_ENCODED_STRING
```
➡️ For a full setup guide, check: [Set Up Proxy Authentication in API](/docs/guides/advance-configuration/proxy-authentication-in-api)
***
## **2. Authenticating with IP Whitelisting**
IP whitelisting allows you to skip entering your username and password by authorizing a specific IP address to access the proxy.
➡️[What is IP Whitelisting?](/docs/guides/advance-configuration/whitelist-ip)
### **When to use IP Whitelisting**
* You have a static IP and want seamless authentication.
* You are automating tasks and don't want to include credentials in every request.
* You want better security by restricting access to trusted IPs.
➡️ [Learn How to Whitelist Your IP Address](/proxy-setup/advance-configuration/whitelist-ip)
***
## **Choosing the Right Authentication Method**
| Authentication Method | Best For | Requires Credentials? |
| ----------------------- | -------------------------------------------------------- | --------------------- |
| **Username & Password** | Most API calls, scripts, and browser extensions | ✅ Yes |
| **IP Whitelisting** | Trusted networks, automation, and security-focused users | ❌ No |
***
## **Final Tips**
* Use Username & Password for flexible authentication across different devices.
* Use IP Whitelisting if you have a static IP and want to avoid entering credentials.
* Always ensure your authentication details are kept secure and not exposed in scripts or public repositories.
# Port Usage (/docs/guides/proxy-service-guide/proxy-usage)
This guide explains how ports function when configuring **SOCKS5** and **HTTP** proxies in Geonode.\
Geonode provides **unlimited port ranges**, meaning you can generate as many proxies as needed — without performance limits.
## How Port Ranges Work
Geonode assigns specific port ranges to organize different proxy types and session behaviors:
| Proxy Type | Session Type | Port Range |
| ---------- | ------------ | ------------- |
| **HTTP** | Rotating | `9000–9010` |
| **HTTP** | Sticky | `10000–10900` |
| **SOCKS5** | Rotating | `11000–11010` |
| **SOCKS5** | Sticky | `12000–12010` |
These ranges act as **identifiers**, not limitations.\
You can reuse the same port as often as you like — each connection request automatically generates a **unique proxy IP**.
***
## Key Points to Remember
### Same Performance Across All Ports
* Whether you use port `9000` or `9010`, performance and stability remain identical.
* Reusing a port does **not** affect connection speed or session quality.
### Efficient Port Reuse
* You don’t need to change ports for every connection.
* Thousands of requests can run on the **same port** without issues or conflicts.
* Port selection mainly helps organize your setup (for example, by type or location).
***
## Common Use Cases
### Using Multiple Proxies
If you need multiple proxies for automation or scraping:
* You can assign **all requests to the same port** (e.g., `9000`).
* Each request will still produce a **unique IP address**, ensuring anonymity and diversity.
* There’s no impact on speed or reliability.
### Rotating vs. Sticky Sessions
* **Rotating Proxies** — Ports `9000–9010` (HTTP) and `11000–11010` (SOCKS5):\
Each request gets a **new IP address** automatically.
* **Sticky Proxies** — Ports `10000–10900` (HTTP) and `12000–12010` (SOCKS5):\
The same IP remains active for a set duration (useful for account logins, testing, etc.).
### Country-Specific Port Assignments
* When you assign a port to a specific **country**, it cannot be reused for another country until the previous assignment is **deleted**.
* This ensures accurate geo-routing and prevents proxy conflicts.
***
## Common Misconceptions
> “Fewer ports mean fewer proxies.”
❌ False.\
The **number of ports** has no effect on how many proxies you can use.\
Ports are simply **access points** — Geonode dynamically assigns IPs behind them.
***
## Summary
* You can reuse the same port indefinitely — performance stays the same.
* Rotating ports change IPs automatically; sticky ports keep the same IP for a set session.
* Assign ports carefully if you’re working with geo-targeted proxies.
* Geonode’s architecture allows **unlimited proxy generation** across all ports.
By understanding how port usage works, you’ll be able to manage proxy sessions efficiently — without worrying about limits or performance degradation.
# Proxy (/docs/guides/proxy-service-guide/proxy)
This guide explains what a proxy is, how it works, and why it’s essential for online security, privacy, and automation.
## What Is a Proxy?
A **proxy server** acts as a bridge between your device and the internet.\
Instead of connecting directly to a website, your request first passes through the proxy, which forwards it on your behalf.
### Analogy: A Proxy as a Messenger
Imagine you’re ordering food but don’t want the restaurant to know your home address.\
You ask a **friend (proxy)** to pick it up and deliver it. The restaurant only sees your friend’s address — not yours.
Likewise, when using a proxy:
* Your real IP is hidden.
* The proxy server communicates with websites for you.
* Websites see the proxy’s IP instead of yours.
***
## How a Proxy Works
When you connect through a proxy, your data follows four simple steps:
1. **Request Sent** — You request access to a website.\
The request goes to the proxy server first.
2. **IP Replaced** — The proxy swaps your IP with its own and sends the request onward.
3. **Response Received** — The target website sends data back to the proxy.
4. **Response Delivered** — The proxy forwards that data back to you, keeping your IP hidden.
***
## Types of Proxies
### 1. Forward vs. Reverse Proxies
| Type | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| **Forward Proxy** | Protects the user by hiding their IP when browsing or scraping the internet. |
| **Reverse Proxy** | Protects servers by managing inbound traffic, improving security and load balancing for hosted websites. |
***
### 2. Residential vs. Datacenter Proxies
| Type | Description |
| --------------------- | ----------------------------------------------------------------- |
| **Residential Proxy** | Uses real IPs from ISPs — highly trusted and difficult to detect. |
| **Datacenter Proxy** | Uses IPs from data centers — faster but easier to identify. |
***
### 3. Rotating vs. Sticky Proxies
| Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Rotating Proxy** | Changes IP for every request or after a set time — great for scraping and large-scale automation. |
| **Sticky Proxy** | Keeps the same IP for a session — best for logins, account management, and session-based tasks. |
***
## Why Use a Proxy?
### 1. Privacy & Anonymity
* Hides your real IP and online identity.
* Prevents tracking and profiling by websites.
### 2. Geo-Unblocking
* Access region-restricted content (streaming, marketplaces, apps).
* Simulate browsing from specific countries.
### 3. Security & Protection
* Avoid IP bans and throttling.
* Reduce exposure to threats by masking your origin.
### 4. Automation & Data Collection
* Collect public data at scale without detection.
* Power SEO, price-tracking, and analytics tools.
***
## How to Choose the Right Proxy
| Use Case | Recommended Proxy Type |
| ------------------------------- | ------------------------- |
| **Browsing & Privacy** | Residential Proxy |
| **Web Scraping & Automation** | Rotating Datacenter Proxy |
| **Geo-Blocked Content** | Residential Proxy |
| **Multiple Account Management** | Sticky Residential Proxy |
***
## Summary
* Proxies act as intermediaries that protect your identity online.
* Choose **rotating** proxies for scraping, **sticky** ones for stable sessions.
* Residential proxies offer trust and geo-access, while datacenter proxies focus on speed.
* Understanding proxy types helps you stay secure, anonymous, and efficient across all use cases.
# Rotating Proxies (/docs/guides/proxy-service-guide/rotating-proxies)
This guide explains what rotating proxies are, how they work, and how they help maintain anonymity and stability during high-volume requests.
## What Are Rotating Proxies?
A **rotating proxy** automatically assigns a new IP address after each request — or after a defined time interval.\
This rotation helps prevent detection and blocking by websites that monitor for repeated activity from a single IP.
***
## How Rotating Proxies Work
* Each outgoing request is assigned a **unique IP address** from a large proxy pool.
* The IP rotates **automatically** after every request or based on a timer (e.g., every few minutes).
* This makes requests appear as if they are coming from different users around the world.
Rotating proxies are ideal for maintaining anonymity and avoiding IP bans in automation and scraping tasks.
***
## Key Benefits
| Benefit | Description |
| ------------------------ | ------------------------------------------------------------- |
| **High Anonymity** | Constantly changing IPs prevent tracking and detection. |
| **Bypass Rate Limits** | Allows multiple requests without triggering anti-bot systems. |
| **Improved Scalability** | Enables large-scale web scraping and data collection. |
| **Global Coverage** | Access data from various geographic locations automatically. |
***
## Common Use Cases
| Use Case | Why It’s Useful |
| --------------------------- | ---------------------------------------------------------- |
| **Web Scraping** | Collects large datasets without detection or bans. |
| **Ad Verification** | Checks ad placements from multiple IPs and regions. |
| **Market Research** | Gathers pricing and trend data from competitor sites. |
| **SEO Monitoring** | Tracks rankings without triggering search engine security. |
| **Social Media Automation** | Manages multiple accounts without getting flagged. |
***
## Limitations
While rotating proxies offer flexibility and anonymity, they’re not ideal for all scenarios:
| Limitation | Impact |
| ---------------------------------------- | --------------------------------------------------------- |
| **Unstable Sessions** | Frequent IP changes break login-based activities. |
| **Detection by Strict Websites** | Some systems still recognize automated behavior. |
| **Potential for Inconsistent Responses** | Different IPs may yield varying localized or cached data. |
***
## Summary
* **Rotating proxies** provide high anonymity and scalability for automation and data collection.
* Use them for **web scraping**, **ad verification**, and **SEO monitoring**.
* For login-based or session-sensitive tasks, switch to **sticky proxies** to maintain consistency.
* Adjust rotation frequency to balance anonymity with connection stability.
# Session Type (/docs/guides/proxy-service-guide/session-type)
Choosing the right **session type** is key to optimizing proxy performance, maintaining stable connections, and avoiding detection.\
This guide explains what sessions are, how they work, and when to use **rotating** or **sticky** sessions.
## What Is a Session?
In proxy configuration, a **session** refers to the period during which you use the same IP address.\
The session type determines whether your IP remains constant (sticky) or changes frequently (rotating).
Geonode supports two main session types:
* **Rotating Sessions**
* **Sticky Sessions**
***
## Rotating Sessions
A **rotating session** assigns a new IP address for every request or after a defined time interval.\
This setup is designed for maximum anonymity and large-scale operations where detection risk is high.
### Key Features
| Feature | Description |
| ------------------------- | ----------------------------------------------------------- |
| **Automatic IP Rotation** | Changes IP after each request or at a set interval. |
| **High Anonymity** | Prevents blocks by cycling through multiple IPs. |
| **Scalable** | Ideal for bulk data collection and high-frequency requests. |
### Best For
* Web scraping and data aggregation
* Market or SEO research
* Ad verification and automation tasks
***
## Sticky Sessions
A **sticky session** maintains the same IP for a longer duration, creating a stable and continuous connection.\
This type is useful when session consistency or login persistence is required.
### Key Features
| Feature | Description |
| ---------------------------- | ------------------------------------------- |
| **Consistent IP Address** | Keeps the same IP throughout the session. |
| **Custom Duration** | Control how long the IP remains active. |
| **Reduced Reauthentication** | Avoids frequent logouts and session resets. |
### Best For
* Account management and login sessions
* E-commerce or transactional activities
* Application and website testing
***
## Comparison: Rotating vs. Sticky Sessions
| Criteria | Rotating Sessions | Sticky Sessions |
| --------------- | ----------------------------------------- | --------------------------------------- |
| **IP Behavior** | Changes with each request or set interval | Remains the same for a defined duration |
| **Anonymity** | High – ideal for stealth and scaling | Moderate – consistent IP for stability |
| **Performance** | Suited for high-volume tasks | Suited for persistent sessions |
| **Use Case** | Scraping, automation, data collection | Logins, transactions, testing |
***
## Summary
* **Rotating sessions** provide higher anonymity and flexibility for automation, scraping, and large-scale operations.
* **Sticky sessions** ensure reliability for logins, testing, and tasks that depend on stable IPs.
* Combine both session types when needed — for instance, rotating proxies for data gathering and sticky proxies for account-based operations.\
Understanding how sessions work helps you balance **anonymity, performance, and connection stability** for your specific goals.
# Sticky Session (/docs/guides/proxy-service-guide/sticky-session)
A **sticky session** maintains the same IP address for a fixed period instead of changing it with every request.\
This allows for stable, consistent sessions — ideal for activities like account logins, e-commerce transactions, and automation tasks that rely on persistent identity.
***
## How Sticky Sessions Work
* When you start a connection, a unique IP address is assigned to your session.
* The IP remains active for a defined duration (e.g., 10–30 minutes, or longer).
* Once the session expires, a new IP is automatically assigned on the next connection.
* You can manually release a session early if you need to refresh your IP before expiration.
Sticky sessions offer balance — they maintain stability without locking you to a single IP indefinitely.
***
## Key Benefits
| Benefit | Description |
| ----------------------------- | ---------------------------------------------------------------------- |
| **Stable Identity** | Keeps the same IP during the session, ideal for login-based workflows. |
| **Fewer CAPTCHA Challenges** | Reduces interruptions caused by frequent IP changes. |
| **Persistent Access** | Prevents session resets on e-commerce and social media platforms. |
| **Better Automation Control** | Ensures bots and tools operate smoothly across multi-step actions. |
***
## Common Use Cases
| Use Case | Why It’s Useful |
| ------------------------------ | ----------------------------------------------------- |
| **Account Management** | Maintains session stability and prevents logouts. |
| **E-Commerce & Checkout Bots** | Avoids disruptions during multi-step transactions. |
| **Web Scraping (Login Sites)** | Enables consistent access for authenticated scraping. |
| **Streaming Services** | Prevents interruptions or reauthentication requests. |
| **SEO Monitoring** | Keeps IP identity consistent for ongoing checks. |
***
## Limitations
| Limitation | Impact |
| ----------------------------- | ---------------------------------------------------------------------------- |
| **Overuse of One IP** | Extended use can make IPs easier to flag or block. |
| **Limited Parallel Requests** | Using the same IP across many tasks can reduce efficiency. |
| **Session Expiration** | Once the duration ends, the IP changes automatically, interrupting sessions. |
***
## Summary
* **Sticky sessions** provide reliable, consistent connections — perfect for logins, form submissions, and stable workflows.
* If an IP becomes blocked, you can **release the session** and instantly obtain a new one.
* For **high anonymity and frequent IP changes**, use **rotating sessions** instead.
* Choosing between sticky and rotating proxies depends on whether your task needs **stability or stealth**.
# Threads in Proxy Usage (/docs/guides/proxy-service-guide/thread)
Threads determine how many tasks can run at the same time when using proxies.\
Understanding how they work helps optimize performance, avoid bans, and make the most out of your proxy setup.
***
## What Are Threads?
A **thread** is a unit of execution within a program.\
In proxy usage, threads allow you to run multiple actions—such as web requests or scrapers—**simultaneously**, improving efficiency and speed.
### Analogy: Threads Are Like Checkout Counters
Imagine a supermarket with one cashier: everyone waits in line.\
Open 10 counters, and customers check out faster.
* **Single-threaded** → one cashier, one queue
* **Multi-threaded** → multiple cashiers, faster service
That’s exactly how threads improve proxy-based automation and scraping.
***
## How Threads Work in Proxies
Threads are used to send many requests at once, without waiting for each one to finish before starting the next.
### Without Threads (Single-Threaded)
* Only one request runs at a time.
* The next request waits for the previous one to finish.
* Very slow when dealing with large datasets.
### With Threads (Multi-Threaded)
* Many requests run at the same time.
* No waiting between requests.
* Data collection and automation happen much faster.
***
## Why Threads Matter in Proxy Usage
| Benefit | Explanation |
| ------------------------------- | ----------------------------------------------------------------- |
| **Faster Data Collection** | Executes multiple requests in parallel. |
| **Efficient Proxy Utilization** | Distributes requests across multiple proxies, reducing detection. |
| **Large-Scale Capability** | Ideal for scraping thousands of pages or bulk API requests. |
| **Lower Ban Risk** | Threads allow balanced load across IPs to minimize blocking. |
***
## Choosing the Right Number of Threads
The ideal number of threads depends on your **proxy type**, **hardware resources**, and **task intensity**.
| Scenario | Recommended Threads |
| ------------------------------------- | -------------------------------- |
| Small-scale scraping (few pages) | 5–10 threads |
| Medium-scale scraping (moderate data) | 20–50 threads |
| Large-scale scraping (massive data) | 100+ threads |
| Using residential proxies | Fewer threads (avoid bans) |
| Using datacenter proxies | More threads (faster processing) |
⚠️ **Too many threads** → may cause IP bans or overload your proxies.\
🐢 **Too few threads** → slows down operations.\
🎯 **Balance is key** — test and adjust based on performance.
***
## Threads vs. Concurrent Connections
Threads and concurrent connections are related but not identical.
| Feature | Threads | Concurrent Connections |
| -------------- | --------------------------------------- | ------------------------------------------------- |
| **Definition** | Execution units within a program | Multiple network connections happening at once |
| **Purpose** | Controls how many tasks run in parallel | Defines how many requests are sent simultaneously |
| **Example** | Running multiple scrapers in parallel | Opening 50 browser tabs at once |
***
## Summary
* Threads enable multitasking and speed up proxy workflows.
* Start with fewer threads and scale gradually.
* Match thread count to your proxy pool — more proxies can safely support more threads.
* Monitor CPU, RAM, and network limits to prevent system overload.
Understanding threading is crucial for stable, efficient, and scalable proxy performance.
# Unlimited Residential Proxies (/docs/guides/proxy-service-guide/unlimited-residential-proxies)
**Unlimited Residential Proxies** are speed-based plans (e.g., 200 Mbps) designed for high-usage customers. They are billed as a **monthly subscription**, not per-GB, and let you configure country targeting, protocol (SOCKS5 or HTTP), multiple endpoints for parallel use, and custom sticky sessions.
> **Gateway note:** Unlimited Residential currently supports **US gateway only**.\
> **Concurrency note:** There are no thread or concurrency limits enforced by the plan — performance depends on your setup and the plan speed cap.
***
## Overview
Unlimited Residential Proxies give you:
* **Speed-based billing** — Throughput limited by your plan’s speed cap (e.g., 200 Mbps), not by data volume.
* **No per-GB billing** — Predictable monthly cost for heavy usage.
* **Flexible configuration** — Country targeting, protocol choice, multiple endpoints, and sticky sessions.
***
## Access Your Credentials
1. Log in to the [Geonode Dashboard](https://app.geonode.com/).
2. Go to **Unlimited Residential Proxies → Proxy Configuration**.
3. You will find your **Username**, **Password**, **Host**, and **Port**.
### Endpoint Format
Use the following format for tools that accept a single string:
**Format:** `hostname:port:username:password`
**Example:**
`residential-unlimited-us-01-proxy.geonode.io:13003:USERNAME:PASSWORD`
Replace `USERNAME` and `PASSWORD` with your actual credentials from the dashboard.
***
## Basic Connection Examples
### HTTP
```bash
curl -x http://USERNAME:PASSWORD@residential-unlimited-us-01-proxy.geonode.io:13003 https://ipinfo.io
```
### SOCKS5
```bash
curl --proxy socks5://USERNAME:PASSWORD@residential-unlimited-us-01-proxy.geonode.io:13003 https://ipinfo.io
```
Replace `USERNAME` and `PASSWORD` with your credentials.
***
## Dashboard Options
In **Unlimited Residential Proxies → Proxy Configuration** you can set:
| Option | Description |
| --------------------- | ------------------------------------------------------------------------- |
| **Gateway** | United States (only available gateway for Unlimited plans) |
| **Country Targeting** | **Any** (default) or a specific country — specific country is recommended |
| **Protocol** | SOCKS5 or HTTP |
| **Endpoints Count** | Generate 1 or more endpoints for parallel usage (e.g., 10 endpoints) |
***
## Sticky Sessions
Sticky sessions keep the same IP for a period of time when enabled. You can view and manage active sessions under **Active Sticky Sessions** in the dashboard. Releasing a session frees the IP so that the next use of the same session ID gets a new IP.
### How to Enable Sticky Sessions
Append `-session-{sessionname}` to your username. This works for both HTTP and SOCKS5. Using the same session name keeps the same IP while it remains available.
**Format:** `USERNAME-session-{sessionname}`
**Example (HTTP):**
```bash
curl -x http://USERNAME-session-test123:PASSWORD@residential-unlimited-us-01-proxy.geonode.io:13003 https://ipinfo.io
```
**Example (SOCKS5):**
```bash
curl --proxy socks5://USERNAME-session-test123:PASSWORD@residential-unlimited-us-01-proxy.geonode.io:13003 https://ipinfo.io
```
### Release a Session / Get a New IP
* **Change the session name** — e.g. switch from `session-test123` to `session-test456` to get a new IP.
* Or **release sessions from the dashboard** under **Active Sticky Sessions** (this will assign anew IP automatically).
> **Note on Sessions:** The session ID should provided should be unique inorder to create multiple sessions in parallel. If the same session ID gets used, the same existing sticky session shall be used.
***
## Speed and Plan Model
Unlimited plans are limited by **speed**, not bandwidth:
Example:
* 200 Mbps plan (monthly)
* No per-GB billing
* Throughput limited by the plan speed cap
***
## Monitoring and Statistics
Go to **Dashboard → Statistics** to monitor:
* **Total requests**
* **Successful vs failed** requests
* **Success rate**
* **Data usage** (GB)
* **Time filters** — Last hour, 24h, 7d, 30d, 90d
* **Export CSV** for your own analysis
Use these metrics to spot issues and optimize configuration.
***
## Troubleshooting
| Issue | What to try |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| **Slow results** | Reduce local concurrency; release sessions to refresh IPs; check local ISP or server limits |
| **Target blocks you** | Release or rotate session; adjust country targeting; use sticky sessions for login/checkout flows |
| **High failure rate** | Release sessions; try different country targeting or fewer concurrent connections |
***
## FAQ
{" "}
Unlimited Residential is a speed-based plan. Your usage is not metered by GB; throughput is limited by your plan’s speed cap (e.g., 200 Mbps). How much data you use depends on your plan and how you run traffic.
{" "}
Residential IPs can vary in lifetime. Sticky sessions help maintain the same IP for a period, but we do not guarantee a single IP for 24 hours — use sticky sessions and avoid releasing if you need maximum persistence.
{" "}
Unlimited Residential currently supports the US gateway only. Other gateways are not yet available for this product.
{" "}
No. The plan does not enforce thread or concurrency limits. Performance depends on your own setup and the plan’s speed cap.
***
# Latency Testing (/docs/guides/proxy-speed-and-perfomance/success-latency)
This guide explains how to test the latency and success rate of your proxies using Python.\
You’ll learn how to measure proxy performance, analyze results, and visualize latency data.
***
## Overview
The provided script uses Python’s `requests` library to send concurrent requests and measure performance metrics like:
* **Latency (response time)**
* **Success rate (status code analysis)**
* **Error types (timeouts, connection issues)**
It supports both **SOCKS5** and **HTTPS** proxies and uses [ip-api.com](http://ip-api.com) as the default target URL.\
You can also test alternative endpoints like **Cloudflare trace** for comparison.
***
## What You’ll Learn
* How to run latency tests on multiple proxies.
* How to configure proxy protocols (SOCKS5 or HTTP).
* How to analyze average latency, median response time, and success rates.
* How to interpret graphical results to detect issues.
***
## Default Settings
| Parameter | Default Value | Description |
| -------------- | ------------------------------- | ------------------------------------------ |
| Protocol | HTTPS | Set `use_socks5 = True` for SOCKS5 proxies |
| Target | [ip-api.com](http://ip-api.com) | Default endpoint for IP tests |
| Concurrency | 5–10 threads | Recommended thread range |
| Testing Volume | 2000+ requests | Recommended for stable averages |
***
## Variable Settings
The script allows you to adjust several key variables:
* **Target Country** – optional (leave blank to use random pool)
* **Protocol** – choose between HTTP/HTTPS or SOCKS5
* **Session Type** – rotating (default)
* **Target URL** – endpoint to test (default: ip-api.com)
* **Number of Requests** – define test size
* **Threads** – set concurrent workers (recommended: 5–10)
Results may vary depending on which gateway you use. Geonode currently
provides three gateway locations.
***
## Port Ranges
| Session Type | Protocol | Port Range | Description |
| ------------ | ---------- | ----------- | ---------------------------------- |
| Rotating | HTTP/HTTPS | 9000–9010 | Changes IP for every request |
| Rotating | SOCKS5 | 11000–11010 | Changes IP for every request |
| Sticky | HTTP/HTTPS | 10000–10900 | Keeps same IP for session duration |
| Sticky | SOCKS5 | 12000–12010 | Keeps same IP for session duration |
***
## Steps to Test Proxy Latency
### Step 1: Install Required Libraries
Install dependencies before running the script:
```bash
pip install requests matplotlib numpy
```
### Libraries used
* `requests` — send HTTP requests
* `matplotlib` — visualize latency results
* `numpy` — calculate average and median latency
* `collections` — count occurrences of errors
***
## Step 2: Configure Proxy Settings
You can test **SOCKS5** or **HTTP(S)** proxies by adjusting the `use_socks5` flag.
### SOCKS5 Proxy Example
```python
use_socks5 = True
proxies = {
'http': 'socks5://username:password@proxy.geonode.io:11009',
'https': 'socks5://username:password@proxy.geonode.io:11009'
}
```
### HTTP Proxy Example
```python
use_socks5 = False
proxies = {
'http': 'http://username:password@proxy.geonode.io:9008',
'https': 'http://username:password@proxy.geonode.io:9008'
}
```
Replace `username` and `password` with your Geonode credentials
## Step 3: Configure Test Parameters
Set your test parameters in the script:
```python
url = 'http://ip-api.com' # Default test target
num_requests = 5000 # Number of requests
num_workers = 5 # Concurrent threads
```
For accuracy:
* Use **2000+ requests**
* Run with **5–10 threads**
***
## Step 4: Send Concurrent Requests
The script uses `ThreadPoolExecutor` to send multiple requests simultaneously:
```python
from concurrent.futures import ThreadPoolExecutor
import requests, time
def fetch_url(i):
try:
start_time = time.time()
response = requests.get(url, proxies=proxies, timeout=60)
latency = time.time() - start_time
return response.status_code, latency
except requests.exceptions.Timeout:
return 'Timeout', time.time() - start_time
except requests.exceptions.RequestException:
return 'Error', time.time() - start_time
```
Each request logs:
* **Status code**
* **Latency (seconds)**
* **Timeouts or errors**
***
## Step 5: Analyze and Visualize Results
After completing all requests, the script plots a latency graph.
| Color | Meaning |
| ----------- | -------------------------------- |
| **Blue** | Successful requests (status 200) |
| **Red** | Non-200 responses (404, 500) |
| **Green** | Timeouts |
| **Magenta** | Other errors |
***
## Step 6: View Test Statistics
Once the test completes, the script outputs key metrics:
```
Average Latency: 1.20 seconds
Median Latency: 0.89 seconds
Standard Deviation of Latency: 1.30 seconds
Status Code Percentages:
200: 99.54%
Error: 0.12%
401: 0.04%
402: 0.06%
500: 0.20%
502: 0.04%
Total Requests: 5000
Successful (Status 200): 4977
Timeouts: 0
Other Errors: 6
Error Messages:
Error: 6
```
These values help assess **reliability**, **consistency**, and **stability** of your proxy connections.
***
## Step 7: Interpret Results
Use the output to evaluate proxy quality:
| Metric | Meaning |
| ---------------------- | --------------------------------------- |
| **Success Rate** | Percentage of status 200 responses |
| **Latency** | Average response time per request |
| **Error Distribution** | Frequency of timeouts or other failures |
Rotating ports provide more accurate, diversified benchmarks than testing a single static proxy.
***
## Source Code
You can find the full source code for this script on GitHub:
[Geonode Proxy Testing Toolkit](https://github.com/geonodecom/proxy-testing-toolkit/tree/performance-testing/success-latency)
```
```
# Exclude Specific Location (/docs/guides/region-specific-proxies/exclude-specific-location)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import RegionSpecificFAQs from "../../../snippets/region-specific-faqs.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
***
This guide will help you understand how to exclude proxies from specific cities, countries, states, or ISPs using the Geonode API.
***
## Prerequisites
Before you begin, make sure you:
* Have active Geonode proxy credentials.
* Understand how to make API calls using tools like cURL or Python.
***
## What is Location Exclusion?
Geonode allows you to exclude certain locations while routing traffic through proxies. This is helpful when you want to avoid specific regions due to content restrictions, compliance, or testing needs.
➡️ Want to route traffic through a location instead? [See Targeting Locations](/docs/guides/region-specific-proxies/target-specific-location)
***
## What Can You Exclude?
You can exclude proxies based on:
* Country
* State
* City
* ASN (Autonomous System Number)
You can't combine different exclusion types in a single request. For example,
you can't exclude cities and ASNs together.
***
## Format for Exclusion
To exclude a location, modify your proxy username like this:
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-not.country-:" \
--url "http://ip-api.com/json"
```
Supported location types:
* `not.country`
* `not.city`
* `not.state`
* `not.asn`
You can pass:
* A single exclusion: `-not.city-tokyo`
* Multiple exclusions: `-not.city-tokyo,kyoto,osaka`
***
## Get Proxy with Exclusions from Dashboard
You can easily get the correct country codes, city names, state names, and ASN numbers directly from the Geonode Dashboard.
Just go to the right-hand filters for Country, City, State, or ASN targeting. Once selected, they will appear in the proxy string for reference.
***
## Calling API with Location Exclusions
### 1. Exclude by Country
Use `-not.country-xx` or multiple like `-not.country-xx,yy,zz`.
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-not.country-,:" \
--url "http://ip-api.com/json"
```
📄 [See full API doc for country exclusion](/api-reference/geo-targeting/exclude-country)
***
### 2. Exclude by State
Use `-not.state-`.
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--not.state-:" \
--url "http://ip-api.com/json"
```
📄 [See full API doc for state exclusion](/api-reference/geo-targeting/exclude-state)
***
### 3. Exclude by City
Use `-not.city-`.
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--not.city-:" \
--url "http://ip-api.com/json"
```
📄 [See full API doc for city exclusion](/api-reference/geo-targeting/exclude-city)
***
### 4. Exclude by ASN (ISP)
Use `-not.asn-`. You can also pass multiple values like `-not.asn-31898,12271`.
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--not.asn-:" \
--url "http://ip-api.com/json"
```
📄 [See full API doc for ASN exclusion](/api-reference/geo-targeting/exclude-asn)
***
## Example Response
Here's an example API response when city or ASN is excluded:
```json
{
"status": "success",
"country": "United States",
"countryCode": "US",
"region": "NC",
"regionName": "North Carolina",
"city": "Charlotte",
"zip": "28202",
"lat": 35.2327,
"lon": -80.8461,
"timezone": "America/New_York",
"isp": "FiberPower LLC",
"org": "FiberPower LLC",
"as": "AS214483 FiberPower LLC",
"query": "38.13.166.129"
}
```
This shows the API successfully excluded the targeted city, and routed through an allowed location instead.
***
## Troubleshooting Tips
* Make sure exclusions use correct names (e.g., "newyork" not "New York").
* City/state names should not have spaces.
* Double-check that you are not mixing exclusion types in one request.
* If you get `407` errors, check username/password.
***
# Switch Between Different Proxy Locations (/docs/guides/region-specific-proxies/switch-between-different-proxy-locations)
import BrowsersFaqs from "../../../snippets/browsers-faqs.mdx";
import VerifyProxyConnectionComponent from "../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
This guide explains how to switch between different proxy locations — for example, using proxies from various countries to access region-specific websites or services.
***
## Configure Proxy Based on Location
To switch proxies by country, state, or city, follow the detailed setup instructions here:
➡️ [How to Target Specific Location with Proxies](/docs/guides/region-specific-proxies/target-specific-location)
That guide explains how to choose and configure a proxy for a specific region, helping you set the right routing for your use case.
***
## Geonode Proxy Manager (Chrome Extension)
If you use Google Chrome, Geonode provides a dedicated browser extension to manage and switch proxies quickly.
➡️ [How to Use the Geonode Chrome Extension for Proxy Management](/docs/guides/extensions/geonode-proxy-manager)
The extension lets you:
* Switch between multiple proxy locations easily.
* Save frequently used proxies.
* Test and verify active connections in one click.
***
## FoxyProxy (Alternative Browser Extension)
If you prefer a third-party tool, **FoxyProxy** is a popular extension that allows switching proxies by location or rule-based logic.
➡️ [How to Set Up Proxy in FoxyProxy](/docs/guides/extensions/foxyproxy)
FoxyProxy supports:
* Multiple proxy profiles
* Location-based routing
* One-click switching between proxies
You can use any other proxy management extension as long as it supports location-based switching.
***
## Rotating Proxy
If you don’t need a specific location and prefer automatic IP rotation, use Geonode’s **Rotating Proxy Service**.\
It automatically assigns a new IP address from a different location for each request — ideal for tasks like scraping or multi-region testing.
➡️ [How to Set Up Rotating Proxies](/docs/guides/proxy-api-management/rotating-proxies)
***
***
***
# Target Specific Location (/docs/guides/region-specific-proxies/target-specific-location)
import ProxyInfoFromGeonode from "../../../snippets/get-proxy-info-from-geonode.mdx";
import RegionSpecificFAQs from "../../../snippets/region-specific-faqs.mdx";
import SupportParagraph from "../../../snippets/support-paragraph.mdx";
***
This guide will help you understand how to geo-target proxies based on locations like cities, countries, states, and ISPs using the Geonode API..
***
## Prerequisites
Before you begin, ensure that you:
* Have valid Geonode API credentials.
* Have basic knowledge of making API requests (e.g., using cURL or Python).
***
## What is Geo-Targeting?
Geonode's **geo-targeting** capabilities allow you to route requests through proxies located in specific countries, cities, states, or regions. This enables precise location-based proxy management for your needs.
➡️ **Learn more about Geo-Targeting**: [What is Geo-Targeting](/docs/guides/proxy-service-guide/geo-targeting)
***
## Ways to Target Specific Locations in Geonode
Geonode allows you to target proxies based on:
* **Country**
* **City**
* **State**
* **ISP/ASN**
You can't target both **state** and **city** at the same time.
***
## API Endpoint Structure for Geo-Targeting
Geonode's geo-targeting endpoints are designed to accept location parameters such as city, state, country, or ISP/ASN. Simply append the specific parameter (e.g., `-country-`) after the Geonode username.
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country-:" \
--url "http://ip-api.com/json"
```
Replace the placeholder values with your Geonode username, password, and desired location.
***
## Generating User Credentials Based on Location
Since the location needs to be included in the username, Geonode makes it easy to generate a location-based proxy username via the Geonode Dashboard:
* Go to the Geonode Dashboard.
* Scroll down to Proxy Configuration.
* On the right, you'll find various location targeting options.
* Once you configure the location, you'll see the updated username, which you can use in API calls for geo-targeted requests.
***
## Calling Geo-Targetting API
To target a specific city, state, or country using the Geonode API, use the following endpoint formats:
### Geo-Targeting by Country
To target a proxy by **country**, append `-country-` to the username.
**Example**
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country-:" \
--url "http://ip-api.com/json"
```
Check out the detailed API docs here ---> [Perform Country Targeting](/docs/api-reference/geo-targeting/get-country/get)
***
### Geo-Targeting by State
To target a proxy by **state**, append `-state-` to the username.
**Example**
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--state-:" \
--url "http://ip-api.com/json"
```
Check out the detailed API docs here ---> [Perform State Targeting](/docs/api-reference/geo-targeting/get-state/get)
***
### Geo-Targeting by City
To target a proxy by **city**, append `-city-` to the username.
**Example**
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--city-:" \
--url "http://ip-api.com/json"
```
Check out the detailed API docs here ---> [Perform City Targeting](/docs/api-reference/geo-targeting/get-city/get)
***
### Geo-Targeting by ISP/ASN
Geonode also allows you to target proxies based on the **ASN (Autonomous System Number)** of an ISP. To do this, append `-asn-` after specifying the country.
**Example**
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--asn-:" \
--url "http://ip-api.com/json"
```
Check out the detailed API docs here ---> [Perform ISP/ASN Targeting](/docs/api-reference/geo-targeting/get-isp/get)
***
## API Response
The API will respond with detailed information about the targeted location, including:
* **Region**, **City**, **ISP**, **Latitude**, **Longitude**, and more.
**Example Response:**
```json
{
"status": "success",
"city": "New York",
"region": "New York",
"country": "United States",
"latitude": "40.7128",
"longitude": "-74.0060",
"isp": "ISP Example",
"timezone": "America/New_York",
"postal_code": "10001"
}
```
This shows that the request was routed through the proxy located in **New York**, with corresponding geographical details.
***
## Troubleshooting
If you encounter issues when targeting a specific location:
* Double-check that the city, state, or country name is spelled correctly.
* Ensure that the proxy is available and accessible in the targeted location.
* Verify the authentication credentials if you receive errors related to access or authorization.
***
# Core Features of Geonode (/docs/guides/what-is-geonode/core-features-of-geonode)
When it comes to managing your online activity securely and efficiently, Geonode provides the tools you need.\
Here’s what it offers for both individual users and businesses.
***
## 1. Proxy products
Websites constantly track online activity — Geonode’s proxy network gives you control again.
With Geonode, you can:
* Browse anonymously — hide your IP and location to stay private
* Access blocked content — bypass geo-restrictions and visit region-limited websites
Geonode acts as a secure, private gateway to the web.
***
## 2. Scraper tools and data collection
Collecting data from multiple sources often leads to blocks. Geonode prevents that by rotating IPs automatically.
* Collect data efficiently — extract information without interruptions
* Avoid blocks — stay under detection limits through IP rotation
Ideal for businesses, researchers, and anyone working with large-scale web data.
***
## 3. Advanced tools
Managing multiple accounts or troubleshooting network issues can be complex.\
Geonode’s advanced tools simplify these tasks.
* Manage multiple accounts — operate several profiles safely at once
* Detect and fix issues quickly — identify and resolve connection problems easily
These tools are designed for both beginners and professionals.
***
## 4. Global reach
Geonode keeps you connected anywhere — from Singapore to New York or Tokyo.
* Access global content — open region-specific websites and services
* Choose IPs worldwide — select IPs from diverse countries for testing, marketing, or research
With Geonode, you don’t just use the internet — you control how you connect to it.
# Use Cases and Applications (/docs/guides/what-is-geonode/uses-cases-and-applications)
Geonode isn’t just a proxy provider — it’s a flexible tool for diverse online workflows.\
Here are a few key ways you can use it effectively:
***
## Web scraping and data collection
Extract valuable data from websites for research, business analytics, and market insights.\
Geonode ensures stable access and prevents IP bans, so your data collection runs smoothly.
***
## Digital marketing and SEO
Analyze competitor strategies, monitor performance, and gather location-specific results.\
Geonode helps marketers and SEO specialists test campaigns and view search results from any region.
***
## Cybersecurity and network testing
Test firewalls, identify vulnerabilities, and verify network configurations securely.\
Geonode assists in assessing your infrastructure without exposing your real IP or internal endpoints.
***
These are only a few ways Geonode supports technical and business workflows.\
[Explore more use cases →](https://geonode.com/use-cases)
# What is Geonode? (/docs/guides/what-is-geonode/what-is-geonode)
Geonode is a proxy service that helps you bypass internet restrictions by masking your real IP address. It makes your online activity private, secure, and unrestricted.
***
## How Geonode works
Geonode provides scalable proxy solutions to keep your connection stable and private.
Main proxy types:
* Residential proxies — real IPs from real devices for undetectable browsing
* Datacenter proxies — high-speed, cost-efficient options for large data operations
***
## Problems Geonode solves
Common challenges users face online:
* Access and data collection — scrape or gather data without getting blocked
* Privacy and security — protect sensitive information while browsing or automating tasks
***
## Why choose Geonode
Geonode stands out through reliability and flexibility.
* Unlimited proxy endpoints — generate and manage as many as needed
* Simple dashboard — intuitive design for fast configuration
* Global coverage — millions of IPs across worldwide locations
***
## Who should use this guide
This guide is suitable for all users — beginners and experienced alike.\
It explains how to use Geonode effectively to enhance privacy, access, and productivity online.
# Perform ASN Exclusion (/docs/api-reference/exclude-targeting/exclude-asn/get)
Route your proxy requests while excluding specific ASNs (Autonomous System Numbers) from the routing.
You cannot mix ASN exclusions with other exclusion types (country, city, or
state) in the same request. Use only one exclusion type per request.
Append `-not.asn-,` after your ``.
* **Single ASN**: `-not.asn-31898`
* **Multiple ASNs**: `-not.asn-31898,12345,67890`
* **With country targeting**: `-country-us-not.asn-31898`
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:9000" \
--user "-country-us-not.asn-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address, excluding the specified ASNs.
#### Response Fields
| Field | Type | Description |
| ------------- | ------ | ------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"country": "United States",
"countryCode": "US",
"region": "MA",
"regionName": "Massachusetts",
"city": "Springfield",
"zip": "01101",
"lat": 42.0986,
"lon": -72.5931,
"timezone": "America/New_York",
"isp": "RingSquared CC",
"org": "",
"as": "AS7849 RingSquared CC",
"query": "161.77.215.31"
}
```
# Perform City Exclusion (/docs/api-reference/exclude-targeting/exclude-city/get)
Route your proxy requests while excluding specific cities from the routing.
You can only exclude cities. You cannot combine city exclusions with country,
state, or ASN exclusions in the same request.
Append `-not.city-,` after your ``.
* **Single city**: `-not.city-charlotte`
* **Multiple cities**: `-not.city-charlotte,newyork,houston`
* **With country**: `-country-US-not.city-charlotte,newyork`
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--not.city-,:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address, excluding the specified cities.
#### Response Fields
| Field | Type | Description |
| ------------- | ------ | ------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter ISO country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"country": "United States",
"countryCode": "US",
"region": "NC",
"regionName": "North Carolina",
"city": "Charlotte",
"zip": "28202",
"lat": 35.2327,
"lon": -80.8461,
"timezone": "America/New_York",
"isp": "FiberPower LLC",
"org": "FiberPower LLC",
"as": "AS214483 FiberPower LLC",
"query": "38.13.166.129"
}
```
# Perform Country Exclusion (/docs/api-reference/exclude-targeting/exclude-country/get)
Route your proxy requests while excluding specific countries from the routing.
You can only exclude countries. You cannot combine country exclusions with
city, state, or ASN exclusions in the same request.
Append `-not.country-,` after your ``.
* **Single country**: `-not.country-US`
* **Multiple countries**: `-not.country-US,CA,MX`
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-not.country-,:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address, excluding the specified countries.
#### Response Fields
| Field | Type | Description |
| ------------- | ------ | ------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter ISO country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"country": "Mexico",
"countryCode": "MX",
"region": "AGU",
"regionName": "Aguascalientes",
"city": "Aguascalientes",
"zip": "20326",
"lat": 21.9419,
"lon": -102.2756,
"timezone": "America/Mexico_City",
"isp": "Uninet S.A. de C.V.",
"org": "UNINET",
"as": "AS8151 UNINET",
"query": "187.232.239.178"
}
```
# Perform State Exclusion (/docs/api-reference/exclude-targeting/exclude-state/get)
Route your proxy requests while excluding specific states or regions from the routing.
You can only exclude states. You cannot combine state exclusions with city,
country, or ASN exclusions in the same request.
Append `-not.state-,` after your ``.
* **Single state**: `-not.state-california`
* **Multiple states**: `-not.state-california,newyork,texas`
* **With country**: `-country-US-not.state-california,newyork`
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--not.state-,:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address, excluding the specified states.
#### Response Fields
| Field | Type | Description |
| ------------- | ------ | ------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter ISO country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"country": "United States",
"countryCode": "US",
"region": "NY",
"regionName": "New York",
"city": "Queens",
"zip": "11436",
"lat": 40.6744,
"lon": -73.8016,
"timezone": "America/New_York",
"isp": "Charter Communications",
"org": "Spectrum",
"as": "AS12271 Charter Communications Inc",
"query": "72.227.174.55"
}
```
# Perform City Targeting (/docs/api-reference/geo-targeting/get-city/get)
Route your proxy requests through a specific city by including both the country code and city name in your username string.
You cannot target both state and city at the same time. Choose either
state-level or city-level targeting.
Append `-city-` after `-country-` to target a specific city.
For example: `username-country-US-city-newyork` targets New York City in the United States.
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--city-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address assigned to your proxy connection.
#### Response Fields
| Field | Type | Description |
| --------------- | ------ | ------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The name of the continent |
| `continentCode` | string | The two-letter continent code |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `district` | string | The district name, if available |
| `zip` | string | The postal code associated with the IP |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"continent": "North America",
"continentCode": "NA",
"country": "United States",
"countryCode": "US",
"region": "AL",
"regionName": "Alabama",
"city": "Decatur",
"district": "",
"zip": 35601,
"query": "68.191.141.86"
}
```
# Perform Country Targeting (/docs/api-reference/geo-targeting/get-country/get)
Route your proxy requests through a specific country by including the country code in your username string.
Append `-country-` after your `` to target a specific country.
For example: `username-country-US` targets the United States.
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address assigned to your proxy connection.
#### Response Fields
| Field | Type | Description |
| --------------- | ------- | ------------------------------------------------ |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The name of the continent |
| `continentCode` | string | The two-letter continent code |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter country code (ISO 3166-1 alpha-2) |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `district` | string | The district name, if available |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `offset` | integer | The time offset in seconds from UTC |
| `currency` | string | The currency code of the country |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"continent": "North America",
"continentCode": "NA",
"country": "Canada",
"countryCode": "CA",
"region": "QC",
"regionName": "Quebec",
"city": "Montreal",
"district": "",
"zip": "H2Y",
"lat": 45.5088,
"lon": -73.5878,
"timezone": "America/Toronto",
"offset": -18000,
"currency": "CAD",
"isp": "Bell Canada",
"org": "Bell Canada",
"as": "AS577 Bell Canada",
"query": "207.134.47.124"
}
```
# Perform ISP/ASN Targeting (/docs/api-reference/geo-targeting/get-isp/get)
Route your proxy requests through a specific ISP or Autonomous System Number (ASN) by including the ASN number in your username string.
The username format supports multiple targeting options:
* **Country**: `-country-` - Specify the country
* **ASN**: `-asn-` - Filter by ASN number
* **IP Type**: `-type-` - Choose residential, datacenter, or mix
Refer to our [Geo-Locations List](https://docs.geonode.com/reference/obtaining-targeting-codes#/) to find available ASN numbers and locations.
## Request
```bash
curl -x "http://proxy.geonode.io:" \
--user "-type--country--asn-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address assigned to your proxy connection.
#### Response Fields
| Field | Type | Description |
| --------------- | ------- | ------------------------------------------------------ |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The continent where the IP is located |
| `continentCode` | string | The continent code |
| `country` | string | The country where the IP is registered |
| `countryCode` | string | The country code in ISO 3166-1 alpha-2 format |
| `region` | string | The regional subdivision (state/province) |
| `regionName` | string | The full name of the region |
| `city` | string | The city associated with the IP address |
| `district` | string | The district or subdivision of the city |
| `zip` | string | The postal or ZIP code of the location |
| `lat` | number | Latitude coordinate of the location |
| `lon` | number | Longitude coordinate of the location |
| `timezone` | string | Time zone in which the IP is located |
| `offset` | integer | Time offset from UTC in seconds |
| `currency` | string | Local currency used in the country |
| `isp` | string | The name of the Internet Service Provider (ISP) |
| `org` | string | The name of the organization associated with the IP |
| `as` | string | The Autonomous System (AS) number and name |
| `asname` | string | The full Autonomous System (AS) name |
| `mobile` | boolean | Indicates whether the IP is from a mobile network |
| `proxy` | boolean | Indicates whether the IP is being used as a proxy |
| `hosting` | boolean | Indicates whether the IP belongs to a hosting provider |
| `query` | string | The IP address queried in the request |
#### Example Response
```json
{
"status": "success",
"continent": "Europe",
"continentCode": "EU",
"country": "Russia",
"countryCode": "RU",
"region": "VGG",
"regionName": "Volgograd Oblast",
"city": "Volgograd",
"district": "",
"zip": "",
"lat": 48.5044,
"lon": 44.5838,
"timezone": "Europe/Volgograd",
"offset": 14400,
"currency": "RUB",
"isp": "JSC ER-Telecom Holding Volgograd branch",
"org": "JSC Columbia-Telecom",
"as": "AS50543 JSC ER-Telecom Holding",
"asname": "SARATOV-AS",
"mobile": false,
"proxy": false,
"hosting": false,
"query": "83.167.79.185"
}
```
# Perform State Targeting (/docs/api-reference/geo-targeting/get-state/get)
Route your proxy requests through a specific state or region by including both the country code and state name in your username string.
You cannot target both state and city at the same time. Choose either
state-level or city-level targeting.
Append `-state-` after `-country-` to target a specific state.
For example: `username-country-US-state-california` targets California in the United States.
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-country--state-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Returns detailed geolocation information about the IP address assigned to your proxy connection.
#### Response Fields
| Field | Type | Description |
| --------------- | ------ | ------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The name of the continent |
| `continentCode` | string | The two-letter continent code |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `district` | string | The district name, if available |
| `zip` | string | The postal code associated with the IP |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"continent": "North America",
"continentCode": "NA",
"country": "Canada",
"countryCode": "CA",
"region": "QC",
"regionName": "Quebec",
"city": "Granby",
"district": "",
"zip": "J2H",
"query": "192.168.1.1"
}
```
# Perform Bandwidth-Limited Proxy Session (/docs/api-reference/sticky-session/get-bandwidth-limited/get)
Create a proxy session with bandwidth limitations to control the data transfer rate for your connection.
This API requires Basic Authentication. Include the following in your request:
* **Username**: `-session--limit-`
* **Password**: ``
* **Proxy**: `http://proxy.geonode.io:`
* **Accept Header**: `application/json`
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-session--limit-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Bandwidth-limited proxy session executed successfully.
#### Response Fields
| Field | Type | Description |
| ------------- | ------ | ---------------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `country` | string | The full name of the country where the IP is located |
| `countryCode` | string | The two-letter country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"country": "Algeria",
"countryCode": "DZ",
"region": "22",
"regionName": "Sidi Bel Abbès",
"city": "Sidi Bel Abbes",
"zip": "22000",
"lat": 34.8934,
"lon": -0.6526,
"timezone": "Africa/Algiers",
"isp": "4 djaweb de AS fawri",
"org": "",
"as": "AS36947 Telecom Algeria",
"query": "197.203.245.147"
}
```
# Create a New Sticky Session (/docs/api-reference/sticky-session/get-create/get)
Create a new sticky session using proxy credentials. Sticky sessions let you keep the same IP address longer, which is useful for tasks that need a stable connection, like managing social media accounts or web scraping. Knowing how to use sticky sessions can improve your proxy experience by making it more efficient and reliable.
Geonode provides specific ports for sticky sessions, ensuring a persistent IP session:
| Protocol | Port Range |
| -------------- | ------------- |
| **HTTP/HTTPS** | 10000 - 10900 |
| **SOCKS5** | 12000 - 12010 |
Use sticky ports when you need a stable IP for session-based activities.
## Request
Make a request using a sticky session by including the session ID in your username string:
```bash
curl -X "http://proxy.geonode.io:" \
--user "-country--session-:" \
--url "http://ip-api.com/json" \
--header "Accept: application/json"
```
### Parameters
The session ID can be any custom string (1-25 alphanumeric characters or underscores). As long as you keep sending requests with the same session ID, you will maintain the same proxy IP.
## Response
### 200 Success
The response contains detailed geolocation information about the IP address assigned to your sticky session.
#### Response Fields
| Field | Type | Description |
| --------------- | ------- | --------------------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The continent where the IP is located |
| `continentCode` | string | The two-letter continent code |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter country code (ISO 3166-1 alpha-2) |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `district` | string | The district name, if available |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `offset` | integer | The time offset in seconds from UTC |
| `currency` | string | The currency code of the country |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `asname` | string | The name associated with the AS number |
| `mobile` | boolean | Indicates whether the connection is from a mobile network |
| `proxy` | boolean | Indicates whether the IP is a known proxy |
| `hosting` | boolean | Indicates whether the IP is from a hosting provider |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"continent": "Africa",
"continentCode": "AF",
"country": "Algeria",
"countryCode": "DZ",
"region": "05",
"regionName": "Batna",
"city": "Batna City",
"district": "",
"zip": "05000",
"lat": 35.5064,
"lon": 6.0707,
"timezone": "Africa/Algiers",
"offset": 3600,
"currency": "DZD",
"isp": "4 djaweb de AS fawri",
"org": "",
"as": "AS36947 Telecom Algeria",
"asname": "ALGTEL-AS",
"mobile": false,
"proxy": false,
"hosting": false,
"query": "XXX.XXX.XXX.XXX"
}
```
# List All Active Sessions (/docs/api-reference/sticky-session/get-list-active/get)
Retrieve a paginated list of all currently active proxy sessions for your account. This endpoint helps you monitor and manage your active connections.
## Request
```bash
curl -X GET "https://app-api.geonode.com/api/sessions/proxies" \
-H "Authorization: Basic base64(username:password)"
```
### Query Parameters
| Parameter | Type | Required | Default | Description |
| ---------- | ------- | -------- | ------- | ------------------------------------- |
| `page` | integer | No | 1 | Page number for pagination |
| `pageSize` | integer | No | 250 | Number of sessions per page (max 250) |
## Response
### 200 Success
A list of active sessions retrieved successfully.
#### Response Fields
| Field | Type | Description |
| -------------------------------------- | ------- | ----------------------------------------------------------- |
| `sessions` | array | A list of currently active proxy sessions |
| `sessions[].id` | string | A unique identifier for the session |
| `sessions[].userSessionId` | string | The user-defined session identifier |
| `sessions[].userId` | string | The Geonode user ID associated with the session |
| `sessions[].port` | string | The port number assigned to the session |
| `sessions[].domain` | string | The target domain being accessed in the session |
| `sessions[].country` | string | The country code representing the location |
| `sessions[].rotatingIntervalInSeconds` | number | The interval (in seconds) at which the session rotates |
| `sessions[].durationInSeconds` | number | The total duration (in seconds) the session has been active |
| `count` | integer | The number of active sessions returned in the current page |
| `total` | integer | The total number of active sessions across all pages |
| `page` | integer | The current page number |
| `pageSize` | integer | The number of sessions per page |
#### Example Response
```json
{
"sessions": [
{
"id": "a7f7c7a3-aaaa-4908-b7bd-71091daadaa6",
"userSessionId": "vzzzzd",
"userId": "geonode_userid",
"port": "10000",
"domain": "ip-api.com",
"country": "dz",
"rotatingIntervalInSeconds": 179.32,
"durationInSeconds": 2.785
}
],
"count": 1,
"total": 1,
"page": 1,
"pageSize": 250
}
```
# Configuring Proxy Session ID & Lifetime (/docs/api-reference/sticky-session/get-proxy-session/get)
Control the duration of your proxy sessions by setting a custom session ID and lifetime. This allows you to maintain stable connections for extended periods, which is essential for tasks requiring persistent IP addresses.
The `lifetime` parameter is measured in **minutes** and defines how long the session remains active:
| Constraint | Value |
| ----------- | ----------------------- |
| **Minimum** | 3 minutes |
| **Maximum** | 1440 minutes (24 hours) |
| **Default** | 10 minutes |
**Examples:**
* `lifetime: 5` → 5 minutes
* `lifetime: 30` → 30 minutes
* `lifetime: 60` → 1 hour
* `lifetime: 180` → 3 hours
Your custom session ID must follow these rules:
* **Format**: 1-25 alphanumeric characters or underscores (`_`)
* **Regex pattern**: `^[A-Za-z0-9_]{1,25}$`
* **Valid characters**: Letters (A-Z, a-z), digits (0-9), and underscores
* **No spaces or special symbols** allowed
**Examples of valid session IDs:**
* `session123`
* `my_session_01`
* `ABC123`
## Request
```bash
curl --request GET \
-x "http://proxy.geonode.io:" \
--user "-session--lifetime-:" \
--url "http://ip-api.com/json"
```
## Response
### 200 Success
Proxy session created successfully with the specified lifetime.
#### Response Fields
| Field | Type | Description |
| --------------- | ------- | --------------------------------------------------------- |
| `status` | string | The status of the request (e.g., "success") |
| `continent` | string | The continent where the IP is located |
| `continentCode` | string | The two-letter continent code |
| `country` | string | The full name of the country |
| `countryCode` | string | The two-letter country code |
| `region` | string | The region code |
| `regionName` | string | The full name of the region |
| `city` | string | The name of the city |
| `district` | string | The district name, if available |
| `zip` | string | The postal code associated with the IP |
| `lat` | number | The latitude coordinate |
| `lon` | number | The longitude coordinate |
| `timezone` | string | The timezone of the IP location |
| `offset` | integer | The time offset in seconds from UTC |
| `currency` | string | The currency code of the country |
| `isp` | string | The name of the Internet Service Provider |
| `org` | string | The organization that owns the IP address |
| `as` | string | The Autonomous System (AS) number |
| `asname` | string | The name associated with the AS number |
| `mobile` | boolean | Indicates whether the connection is from a mobile network |
| `proxy` | boolean | Indicates whether the IP is a known proxy |
| `hosting` | boolean | Indicates whether the IP is from a hosting provider |
| `query` | string | The queried IP address |
#### Example Response
```json
{
"status": "success",
"continent": "Africa",
"continentCode": "AF",
"country": "Algeria",
"countryCode": "DZ",
"region": "05",
"regionName": "Batna",
"city": "Batna City",
"district": "",
"zip": "05000",
"lat": 35.5064,
"lon": 6.0707,
"timezone": "Africa/Algiers",
"offset": 3600,
"currency": "DZD",
"isp": "4 djaweb de AS fawri",
"org": "",
"as": "AS36947 Telecom Algeria",
"asname": "ALGTEL-AS",
"mobile": false,
"proxy": false,
"hosting": false,
"query": "192.168.1.1"
}
```
# Release Sticky Session by Session ID and Port (/docs/api-reference/sticky-session/release-sticky-session/put-release-by-session-id-and-port)
Release one or more sticky sessions by specifying their session IDs and ports. This allows you to free up resources and terminate specific proxy connections.
## Request
```bash
curl -X PUT "https://app-api.geonode.com/api/sessions/release/proxies" \
-H "Authorization: Basic base64(username:password)" \
-H "Content-Type: application/json" \
-d '{"data":[{"sessionId":"random0001","port":10000}]}'
```
### Request Body Parameters
| Field | Type | Required | Description |
| ------------------ | ------- | -------- | ------------------------------------------- |
| `data` | array | Yes | Array containing session details |
| `data[].sessionId` | string | Yes | The session ID to release |
| `data[].port` | integer | Yes | The port number associated with the session |
### Example Request Body
```json
{
"data": [
{
"sessionId": "random0001",
"port": 10000
}
]
}
```
## Response
### 200 Success
Session released successfully.
#### Response Fields
| Field | Type | Description |
| --------- | ------- | ---------------------------------------------------- |
| `success` | boolean | Indicates whether the session release was successful |
#### Example Response
```json
{
"success": true
}
```
# Release Proxy Session by Multiple Port (/docs/api-reference/sticky-session/release-sticky-session/put-release-proxy-session-by-multiple-port)
Release sticky sessions running on multiple ports in a single request. This is useful when you need to free several proxy connections at once.
## Request
```bash
curl -X PUT "https://monitor.geonode.com/sessions/release/proxies" \
-H "Authorization: Basic base64(username:password)" \
-H "Content-Type: application/json" \
-d '{"data":[{"port":10000},{"port":10001},{"port":10002}]}'
```
### Request Body Parameters
| Field | Type | Required | Description |
| ------------- | ------- | -------- | -------------------------------------------- |
| `data` | array | Yes | Array containing session details |
| `data[].port` | integer | Yes | Port number of each proxy session to release |
### Example Request Body
```json
{
"data": [{ "port": 10000 }, { "port": 10001 }, { "port": 10002 }]
}
```
## Response
### 200 Success
Successfully released the specified ports.
#### Response Fields
| Field | Type | Description |
| --------- | ------- | ---------------------------------------------------- |
| `success` | boolean | Indicates whether the session release was successful |
#### Example Response
```json
{
"success": true
}
```
# Release Proxy Session by Port (/docs/api-reference/sticky-session/release-sticky-session/put-release-proxy-session-by-port)
Release a sticky session by specifying its port number. Use this when you need to free up a particular proxy connection without affecting other sessions.
## Request
```bash
curl -X PUT "https://monitor.geonode.com/sessions/release/proxies" \
-H "Authorization: Basic base64(username:password)" \
-H "Content-Type: application/json" \
-d '{"data":[{"port":10001}]}'
```
### Request Body Parameters
| Field | Type | Required | Description |
| ------------- | ------- | -------- | ----------------------------------------------- |
| `data` | array | Yes | Array containing session details |
| `data[].port` | integer | Yes | The port number of the proxy session to release |
### Example Request Body
```json
{
"data": [
{
"port": 10001
}
]
}
```
## Response
### 200 Success
Session released successfully.
#### Response Fields
| Field | Type | Description |
| --------- | ------- | ---------------------------------------------------- |
| `success` | boolean | Indicates whether the session release was successful |
#### Example Response
```json
{
"success": true
}
```
# Overview (/docs/api-reference/sticky-session/release-sticky-session/release-sticky-session)
Release sticky sessions for specified Geonode services by session ID and port. This allows you to free up resources and terminate specific proxy connections.
## What is Session Release?
Session release is the process of terminating active sticky sessions before they naturally expire. When you release a session, you're telling the Geonode proxy system to immediately free up the IP address and resources associated with that session.
## Why Release Sessions?
Release sessions when you need to free up resources or terminate specific proxy connections before they naturally expire.
## How It Works
To release a sticky session, you need to provide:
* **Session ID**: The unique identifier for the session you want to release
* **Port**: The port number associated with the session
The system will immediately terminate the session and free up the associated resources. Once released, the IP address becomes available for other users, and you'll need to create a new session if you want to continue using a sticky connection.
## Available Operations
This section provides endpoints for managing sticky session releases:
* **[Release Sticky Session by Session ID and Port](/docs/api-reference/sticky-session/release-sticky-session/put-release-by-session-id-and-port)**: Release one or more specific sessions by providing their session IDs and ports
Before releasing sessions, you can view all your active sessions using the
[List All Active
Sessions](/docs/api-reference/sticky-session/get-list-active/get) endpoint to
identify which sessions you want to release.
## Best Practices
Before releasing sessions, you can view all your active sessions to identify which ones you want to release. Once a session is released, it cannot be restored, so make sure you're ready to release it before executing the operation.
Once a session is released, it cannot be restored. You'll need to create a new
session if you want to continue using a sticky connection. Make sure you're
ready to release a session before executing the release operation.
# New Sticky Session (/docs/guides/proxy-api-management/sticky-session/new-sticky-session)
import VerifyProxyConnectionComponent from "../../../../snippets/verify-proxy-connection-component.mdx";
import SupportParagraph from "../../../../snippets/support-paragraph.mdx";
import MonitorProxyUsage from "../../../../snippets/monitor-proxy-usage-component.mdx";
This guide explains how to create a new sticky session with Geonode.
***
## What Are Sticky Proxies
Sticky proxies allow you to keep the same IP address for a set duration, making them ideal for activities that require stable connections — such as managing social media accounts, scraping sites with login sessions, or performing long-running data collection.
➡️ See the detailed explanation here: [What Are Sticky Session Proxies](/docs/guides/proxy-service-guide/sticky-session)
***
## Geonode's Sticky Proxy Ports
Geonode assigns specific port ranges for sticky sessions to maintain consistent IPs over time:
* **HTTP:** 10000–10900
* **SOCKS5:** 12000–12010
***
## How to Create a Sticky Session via the Geonode API
Before creating a session, configure your proxy settings in the Geonode dashboard.
### Step 1: Configure Your Proxy Settings
1. Log in to the **Geonode Dashboard**.
2. Open the **Proxies** section from the sidebar.
3. Select **Sticky** as your session type.
4. Set the session duration:
* Minimum: 3 minutes
* Maximum: 24 hours (1440 minutes)
5. Leave other fields as default unless you have specific preferences.
Example configuration:
* IP Type: *Residential*
* Gateway: *France*
* Port Range: *HTTP 10000–10900*
* Session Type: *Sticky Session*
Once configured, copy your proxy endpoint, which looks like this:
```
92.204.164.15:10000:geonode_demouser-type-residential-lifetime-3-RAOnwR
```
Where:
* IP → `92.204.164.15`
* Port → `10000`
* Username → `geonode_demouser-type-residential-lifetime-3-RAOnwR`
* Password → `demopass`
You can use this configuration for API access or in third-party tools such as
Chrome extensions.
***
### Step 2: Create a Sticky Session via API
To start a sticky session through the API, make a request to the `:` endpoint using your configured username and password.
Example using **cURL**:
```bash
curl -x 92.204.164.15:10000 \
--user "geonode_demouser-type-residential-lifetime-3-RAOnwR:demopass" \
--url "http://ip-api.com/json" \
--header "Accept: application/json"
```
Follow this Sticky session API Guide to learn more about the API [Create a New Sticky Session](/api-reference/sticky-session/get-create)
***
***
***
***
## FAQs
{" "}
{" "}
Sticky sessions maintain the same IP for a defined period, while rotating proxies
assign a new IP with every request.{" "}
{" "}
The session duration depends on your configuration — from 3 minutes to 24 hours.
You set this when creating the session.{" "}
{" "}
No, session parameters like IP and type cannot be changed once created. You can,
however, release the current session and create a new one with updated settings.{" "}
{" "}
# Cancel a batch job (/docs/scraper-api/batch/cancel_batch_v1_batch__job_id__delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Stop scheduling new batch items and let in-flight child extractions drain
# Start a batch extraction job (/docs/scraper-api/batch/create_batch_v1_batch_post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Queue a batch of URLs for asynchronous extraction
# Get batch job status (/docs/scraper-api/batch/get_batch_status_v1_batch__job_id__get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Poll for the current status and partial results of a batch job
# List batch jobs (/docs/scraper-api/batch/list_batch_jobs_v1_batch_jobs_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
List batch jobs for the authenticated user with optional filtering and pagination
# Cancel a crawl job (/docs/scraper-api/crawl/cancel_crawl_v1_crawl__job_id__delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Stop scheduling new crawl pages and let in-flight page work drain
# Start a crawl job (/docs/scraper-api/crawl/create_crawl_v1_crawl_post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Crawl a website starting from a seed URL up to a given depth and page limit
# Get crawl job status (/docs/scraper-api/crawl/get_crawl_status_v1_crawl__job_id__get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Poll for the current status and results of a crawl job
# List crawl jobs (/docs/scraper-api/crawl/list_crawl_jobs_v1_crawl_jobs_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
List crawl jobs for the authenticated user with optional filtering and pagination
# Extract content from a URL (/docs/scraper-api/extraction/extract_v1_extract_post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Extract clean markdown or HTML from any URL with sync or async mode support
# Get extraction job result (/docs/scraper-api/extraction/get_job_result_v1_extract__job_id__get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Poll for job progress and retrieve extraction results (async mode only)
# List extraction jobs (/docs/scraper-api/extraction/list_jobs_v1_extract_jobs_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
List and filter extraction jobs by job ID, URL, status, output format, and date range
# Internal aggregated statistics (/docs/scraper-api/internal-statistics/get_internal_statistics_v1_internal_statistics_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns aggregated extraction analytics across all users in the requested window. Intended for Geonode's internal team only; gated by INTERNAL\_API\_AUTH\_\* Basic Auth.
# Get map job details (/docs/scraper-api/map/get_map_job_v1_map__job_id__get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Retrieve the full details and discovered links for a completed map job
# List map jobs (/docs/scraper-api/map/list_map_jobs_v1_map_jobs_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
List map jobs for the authenticated user with optional filtering and pagination
# Discover all URLs under a base URL (/docs/scraper-api/map/map_urls_v1_map_post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns the list of URLs found under the given base URL by combining sitemap parsing with HTML link extraction from the seed page. The optional `search` parameter filters the discovered URLs by case-insensitive substring match — it does NOT query a search engine.
# Get extraction statistics (/docs/scraper-api/statistics/get_statistics_v1_statistics_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Retrieve aggregated extraction statistics for a given date range
# Health check (/docs/scraper-api/system/health_check_health_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Register a webhook (/docs/scraper-api/webhooks/create_webhook_v1_webhooks_post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Create a webhook subscription for a given event type and return its generated signing secret
# Delete a webhook (/docs/scraper-api/webhooks/delete_webhook_v1_webhooks__webhook_id__delete)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Permanently remove a webhook subscription
# Get a webhook (/docs/scraper-api/webhooks/get_webhook_v1_webhooks__webhook_id__get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Retrieve a single webhook by its identifier
# List delivery history (/docs/scraper-api/webhooks/list_deliveries_v1_webhooks__webhook_id__deliveries_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
List webhook delivery attempts with optional status filter and pagination
# List webhooks (/docs/scraper-api/webhooks/list_webhooks_v1_webhooks_get)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
List webhooks registered for the current user with pagination
# Rotate webhook secret (/docs/scraper-api/webhooks/rotate_secret_v1_webhooks__webhook_id__rotate_secret_post)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Generate a new signing secret for the webhook and invalidate the previous one
# Update a webhook (/docs/scraper-api/webhooks/update_webhook_v1_webhooks__webhook_id__patch)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Partially update a webhook's url, description, event type, or active flag
# Before You Start (/docs/scraper-api/guides/extraction/00_before_you_start)
import { Step, Steps } from "fumadocs-ui/components/steps";
This guide covers the basic requirements needed to follow the Extraction guides and ensure your account is set up and ready to make requests.
## Prerequisites
#### Create a Geonode Account
Sign up for a Geonode account if you do not already have one.
#### Get Access to the Scraper API
Make sure your account has access to the Scraper API.
#### Generate an API Key
1. Go to `https://app.geonode.com/scraper-api`.
2. Click `Get Code`.
3. The `API & Integrations` modal will open.
4. Click `Copy API Key` to copy your API key.
## Authentication
Include your API key in the `X-Api-Key` request header.
```bash
X-Api-Key: YOUR_API_KEY
```
Requests without a valid API key will be rejected.
## Base URL
All Extraction API endpoints are available through the following base URL:
```bash
https://scraper.geonode.io
```
## Next Steps
Now that your account is set up, continue to **Understanding Extraction** to learn how the Extraction API works and when to use its different features.
# Understanding Extraction (/docs/scraper-api/guides/extraction/01_understanding_extraction)
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import { FileText, CodeXml } from "lucide-react";
The Extraction API converts webpages into clean, structured content that can be consumed by applications, AI systems, search pipelines, and automation workflows.
Instead of downloading a webpage and manually parsing raw HTML, you can send a URL and receive the extracted content in a format that is easier to process.
## How It Works
#### Submit a URL
Send the URL of the webpage you want to extract.
#### The Page Is Processed
Geonode fetches the webpage and extracts the primary content.
#### Output Is Generated
The extracted content is returned in one or more supported output formats.
#### Use the Result
Store, analyze, search, or process the extracted content in your application.
## Extraction Endpoints
The Extraction API consists of three endpoints.
| Endpoint | Purpose |
| -------------------------- | ----------------------------------------------------------- |
| `POST /v1/extract` | Extract Markdown and/or HTML from a webpage. |
| `GET /v1/extract/jobs` | List and filter previous extraction jobs. |
| `GET /v1/extract/{job_id}` | Retrieve the status or result of a specific extraction job. |
Most extraction workflows begin with `POST /v1/extract`. The remaining endpoints are primarily used to monitor and retrieve asynchronous extraction jobs.
## Processing Modes
The Extraction API supports both synchronous and asynchronous processing.
The request remains open until extraction is complete.
The extracted content is returned directly in the response.
The request immediately returns a `job_id`.
The extraction continues in the background and the result can be retrieved later using `GET /v1/extract/{job_id}`.
## Extraction Workflow
### Synchronous
```text
POST /v1/extract
↓
Extraction completes
↓
Content returned
```
### Asynchronous
```text
POST /v1/extract
↓
job_id returned
↓
GET /v1/extract/{job_id}
↓
Content returned
```
## Output Formats
The Extraction API supports Markdown, HTML, or both formats in a single request.
Markdown
HTML
Both
The extracted content is returned in the `data.markdown` field.
```json
{
"formats": ["markdown"]
}
```
Markdown returns the extracted content as plain text with lightweight formatting.
The extracted content is returned in the `data.html` field.
```json
{
"formats": ["html"]
}
```
HTML returns the extracted content with a structure closer to the original webpage.
The extracted content is returned in both the `data.markdown` and `data.html` fields.
```json
{
"formats": ["markdown", "html"]
}
```
Both Markdown and HTML are returned in the same response.
## Next Steps
Continue to **Your First Extraction** to send your first extraction request and retrieve content from a webpage.
# Your First Extraction (/docs/scraper-api/guides/extraction/02_your_first_extraction)
In this guide, you'll send your first extraction request and retrieve the content of a webpage.
## What You'll Build
By the end of this guide, you'll be able to:
* Send an extraction request
* Extract content from a webpage
* Understand the response structure
* Access the extracted content
## Send Your First Request
Use the following request:
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com"
}'
```
## Request Breakdown
| Field | Description |
| ----- | ------------------------------------ |
| `url` | The webpage to extract content from. |
Since no `formats` field is provided, the API returns HTML by default.
## Understanding the Response
A successful request returns the extracted content and metadata.
```json title="request.json"
{
"data": {
"html": "..."
},
"metadata": {
"url": "http://example.com/",
"render_js": false,
"http_status": 200,
"formats": ["html"],
"processing_mode": "sync"
},
"tokens_charged": 1
}
```
## Access the Extracted Content
The extracted page content is available in:
```text
data.html
```
The metadata section contains additional information about the extraction, including:
* Target URL
* HTTP status
* Output format
* Processing mode
* Extraction duration
## Success
If you received a response similar to the example above, your first extraction was successful.
Your API key is working, the Extraction API is accessible, and you're ready to start working with different output formats and extraction options.
## Next Steps
Continue to **Working With Output Formats** to learn how to return Markdown, HTML, or both formats in a single request.
# Working With Output Formats (/docs/scraper-api/guides/extraction/03_working_with_output_formats)
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import { FileText, CodeXml } from "lucide-react";
The Extraction API can return content in Markdown, HTML, or both formats in a single request.
All examples in this guide use the following endpoint:
```http
POST /v1/extract
```
The `formats` field controls which output formats are returned by the extraction request.
```json
{
"formats": ["markdown"]
}
```
If the `formats` field is omitted, the API returns HTML by default.
## Output Formats
Markdown
HTML
Both
Markdown returns the extracted content as clean, readable text.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["markdown"]
}'
```
### Response
```json title="response.json"
{
"data": {
"markdown": "# Example Domain..."
}
}
```
The extracted content is available in the `data.markdown` field.
Common use cases:
* AI and LLM workflows
* Search indexing
* Knowledge bases
* Text processing pipelines
HTML returns the extracted content with a structure closer to the original webpage.
### Request
```bash
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["html"]
}'
```
### Response
```json
{
"data": {
"html": "..."
}
}
```
The extracted content is available in the `data.html` field.
Common use cases:
* Rendering content in applications
* Preserving page structure
* Working with HTML elements
* Content transformation workflows
Request both Markdown and HTML when your application needs both formats from the same extraction.
### Request
```bash
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["markdown", "html"]
}'
```
### Response
```json
{
"data": {
"markdown": "# Example Domain...",
"html": "..."
}
}
```
The extracted content is available in both the `data.markdown` and `data.html` fields.
## Choosing the Right Format
| Format | Best For |
| -------- | -------------------------------------------------------------------- |
| Markdown | AI workflows, search indexing, knowledge bases, and text processing |
| HTML | Preserving page structure and rendering content |
| Both | Applications that need both representations from a single extraction |
## Success
You now know how to control the format returned by the Extraction API.
Whether you need Markdown, HTML, or both, you can choose the format that best fits your workflow.
## Next Steps
Continue to **Extracting JavaScript Websites** to learn how to extract content from pages that rely on client-side rendering.
# JavaScript Rendering (/docs/scraper-api/guides/extraction/04_extracting_javascript_websites)
Many modern websites load content after the initial page request using JavaScript.
When this happens, a standard extraction may return incomplete content because the page has not finished rendering.
To handle these websites, enable JavaScript rendering with the `render_js` option.
## When to Use JavaScript Rendering
Enable JavaScript rendering when:
* Important content is missing from the extraction result
* Content appears after the page loads
* The website relies on client-side rendering
## Enable JavaScript Rendering
Set `render_js` to `true` in your extraction request.
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://geonode.com/",
"render_js": true
}'
```
### Request Breakdown
| Field | Description |
| ----------- | -------------------------------------------------------- |
| `url` | The webpage to extract content from. |
| `render_js` | Renders the page in a browser before extracting content. |
## Response
A successful response includes the rendered page content and extraction metadata.
```json title="response.json"
{
"data": {
"html": "..."
},
"metadata": {
"url": "https://geonode.com/",
"render_js": true,
"http_status": 200
}
}
```
Notice that `metadata.render_js` is set to `true`, confirming that browser rendering was used during extraction.
## Things to Consider
JavaScript rendering provides more complete extraction results for dynamic websites, but it may:
* Take longer than a standard extraction
* Use additional browser resources
* Be unnecessary for static websites
For static websites, leave `render_js` disabled for faster extraction.
## Success
You can now extract content from websites that rely on JavaScript to display their content.
## Next Steps
Continue to **Processing Modes** to learn the difference between synchronous and asynchronous extraction requests.
# Waiting for Dynamic Content (/docs/scraper-api/guides/extraction/04_waiting_for_dynamic_content)
Modern websites often load content after the initial page load using JavaScript. If content appears a few seconds later, extracting immediately may return incomplete results.
The `wait_config` parameter gives you control over when the extraction should begin.
## How wait\_config Works
When a `wait_config` is provided, the extraction process follows this order:
```text
wait_until
↓
wait_for
↓
wait_timeout
↓
Extract Content
```
This allows you to wait for page events, specific elements, or additional delays before extraction starts.
## wait\_until
The `wait_until` option controls which browser lifecycle event must complete before moving to the next step.
### commit
Wait until the browser receives the response headers and commits the navigation.
```json
{
"url": "https://example.com",
"wait_config": {
"wait_until": "commit"
}
}
```
Best for:
* Very fast extractions
* Cases where you only need the initial response
### domcontentloaded
Wait until the HTML is parsed and the DOM is ready.
```json
{
"url": "https://example.com",
"wait_config": {
"wait_until": "domcontentloaded"
}
}
```
Best for:
* Most websites
* Pages where content is already present in the HTML
> This is the default value when `wait_until` is not provided.
### load
Wait until the page and all resources are fully loaded.
```json
{
"url": "https://example.com",
"wait_config": {
"wait_until": "load"
}
}
```
Best for:
* Pages that depend on images or external scripts
* Slower websites that require additional loading time
### networkidle
Wait until there is no network activity for 500 milliseconds.
```json
{
"url": "https://example.com",
"wait_config": {
"wait_until": "networkidle"
}
}
```
Best for:
* Single-page applications (SPA)
* React, Vue, Angular, and Next.js websites
* Dynamic content loaded through API requests
## wait\_for
The `wait_for` option waits until a specific element appears on the page before extraction starts.
### Using a CSS Selector
```json
{
"url": "https://example.com",
"wait_config": {
"wait_for": ".product-grid"
}
}
```
Extraction begins only after an element matching `.product-grid` is found.
### Using XPath
```json
{
"url": "https://example.com",
"wait_config": {
"wait_for": "//div[@class='product-grid']"
}
}
```
XPath expressions must start with:
```text
//
```
or
```text
xpath=
```
Otherwise, the value is treated as a CSS selector.
### Common Examples
| Use Case | Selector |
| ------------------ | ----------------- |
| Product listing | `.product-grid` |
| Search results | `.search-results` |
| Article content | `article` |
| Table data | `table` |
| Loading completion | `.loaded` |
## wait\_timeout
The `wait_timeout` option adds an additional delay after all previous waits complete.
```json
{
"url": "https://example.com",
"wait_config": {
"wait_for": ".product-grid",
"wait_timeout": 5000
}
}
```
In this example:
1. Wait for `.product-grid`
2. Wait an additional 5 seconds
3. Extract content
### When to Use wait\_timeout
Use this option when content continues updating after the target element appears.
Common examples include:
* Infinite scrolling pages
* Late-loading advertisements
* Client-side rendering delays
* Dynamic dashboards
## Complete Example
```json
{
"url": "https://example.com",
"formats": ["markdown"],
"wait_config": {
"wait_until": "networkidle",
"wait_for": ".product-grid",
"wait_timeout": 3000
}
}
```
This configuration:
1. Waits until network activity stops
2. Waits for `.product-grid` to appear
3. Waits an additional 3 seconds
4. Extracts the content
## Browser Rendering Behavior
When a non-null `wait_config` is provided, browser rendering is automatically enabled if `render_js` is not explicitly specified.
Example:
```json
{
"url": "https://example.com",
"wait_config": {
"wait_until": "networkidle"
}
}
```
The extraction will automatically use browser rendering.
## Invalid Configuration
The following request is rejected:
```json
{
"url": "https://example.com",
"render_js": false,
"wait_config": {
"wait_until": "networkidle"
}
}
```
This is considered ambiguous because `wait_config` requires browser rendering while `render_js` explicitly disables it.
## Best Practices
* Use `domcontentloaded` for most websites.
* Use `networkidle` for JavaScript-heavy applications.
* Use `wait_for` when a specific element contains the data you need.
* Use `wait_timeout` only when additional rendering time is required.
* Avoid excessive delays, as they increase extraction time and cost.
## Next Steps
Now that you understand how to wait for dynamic content, learn how to work with synchronous and asynchronous extraction workflows.
# Processing Modes (/docs/scraper-api/guides/extraction/05_processing_modes)
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
The Extraction API supports two processing modes:
* `sync` for immediate results
* `async` for background processing
Use the `processing_mode` field to control how extraction requests are handled.
```json
{
"processing_mode": "sync"
}
```
If `processing_mode` is omitted, the API uses `sync` mode by default.
## Processing Modes
Synchronous mode waits for extraction to complete before returning a response.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"processing_mode": "sync"
}'
```
### Response
```json title="response.json"
{
"data": {
"html": "...",
"markdown": null
},
"metadata": {
"url": "http://example.com/",
"http_status": 200,
"processing_mode": "sync"
},
"tokens_charged": 1
}
```
The request remains open until extraction is complete and the content is returned in the response.
Asynchronous mode immediately creates an extraction job and returns a job ID.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://geonode.com/",
"processing_mode": "async"
}'
```
### Response
```json title="response.json"
{
"job_id": "32561cfc-4d87-4a46-af4a-a10e5f3168b9",
"status": "queued",
"status_url": "/v1/extract/32561cfc-4d87-4a46-af4a-a10e5f3168b9",
"estimated_tokens": 1
}
```
The extraction continues in the background while your application continues running.
Use the returned `job_id` or `status_url` to retrieve the extraction result later.
## Choosing a Processing Mode
| Mode | Best For |
| ----- | -------------------------------------------------------------------- |
| Sync | Interactive applications, quick extractions, and immediate results |
| Async | Background processing, large workloads, and long-running extractions |
## Success
You now know how to choose between synchronous and asynchronous extraction requests.
Synchronous mode returns the extracted content immediately, while asynchronous mode returns a job ID that can be used to retrieve the result later.
## Next Steps
Continue to **Checking Job Status** to learn how to retrieve the status and results of an asynchronous extraction job using `GET /v1/extract/{job_id}`.
# Proxy and Geo-Targeting (/docs/scraper-api/guides/extraction/06_proxy_and_geo_targeting)
The Scraper API can route extraction requests through Geonode proxies.
If you do not provide a `proxy` object, the API uses residential proxies by default and automatically determines the most appropriate routing location when possible.
Geo-targeting is useful when a website returns different content, language, pricing, availability, or search results based on the visitor's location.
## Configure a Proxy
Use the `proxy` object to control the country and proxy type used for the extraction request.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"proxy": {
"country": "US",
"type": "residential"
}
}'
```
## Country Codes
The `proxy.country` field uses standard ISO 3166-1 alpha-2 country codes.
| Country | Code |
| -------------- | ---- |
| United States | `US` |
| United Kingdom | `GB` |
| Germany | `DE` |
| Pakistan | `PK` |
| Canada | `CA` |
| France | `FR` |
For the complete list of supported country codes:
[https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
## Proxy Types
### Residential
Routes requests through residential IP addresses.
```json title="request.json"
{
"proxy": {
"type": "residential"
}
}
```
### Datacenter
Routes requests through datacenter IP addresses.
```json title="request.json"
{
"proxy": {
"type": "datacenter"
}
}
```
### Mix
Allows the API to use a combination of available proxy networks.
```json title="request.json"
{
"proxy": {
"type": "mix"
}
}
```
## Proxy Configuration Reference
| Field | Type | Description |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `proxy.country` | string or null | Two-letter ISO country code such as `US`, `GB`, `DE`, or `PK`. |
| `proxy.type` | string | Proxy type. Supported values are `residential`, `datacenter`, and `mix`. Defaults to `residential`. |
## Verify the Applied Proxy
The proxy configuration used for the request is returned in the response metadata.
### Response
```json title="response.json"
{
"data": {
"html": "..."
},
"metadata": {
"url": "http://example.com/",
"proxy": {
"country": "US",
"type": "residential"
},
"processing_mode": "sync"
},
"tokens_charged": 1
}
```
You can inspect `metadata.proxy.country` and `metadata.proxy.type` to verify which proxy configuration was applied during extraction.
## Success
You now know how to control the country and proxy network used for extraction requests.
## Next Steps
Continue to **Using Custom Headers** to learn how to send additional HTTP headers with extraction requests.
# Using Custom Headers (/docs/scraper-api/guides/extraction/07_using_custom_headers)
Use the `headers` object to send custom HTTP headers with the extraction request.
## Important
```json title="request.json"
{
"url": "https://example.com",
"headers": {
"Accept-Language": "en-US,en;q=0.9"
}
}
```
Do not put your Geonode API key inside `headers`.
Authentication belongs in the `X-Api-Key` request header sent to the Scraper API.
## Send Custom Headers
Use the `headers` object to include one or more HTTP headers in your extraction request.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://geonode.com/",
"headers": {
"Accept-Language": "en-US,en;q=0.9",
"User-Agent": "Mozilla/5.0"
}
}'
```
## Common Headers
| Header | Purpose |
| ----------------- | ------------------------------------------------- |
| `Accept-Language` | Request content in a specific language |
| `User-Agent` | Identify the browser or client making the request |
| `Referer` | Indicate the page that initiated the request |
| `Cookie` | Send session or authentication cookies |
## Multiple Headers
You can send multiple headers in a single request.
```json title="request.json"
{
"url": "https://geonode.com/",
"headers": {
"Accept-Language": "en-US,en;q=0.9",
"User-Agent": "Mozilla/5.0"
}
}
```
## Success
You now know how to send custom HTTP headers during extraction requests.
## Next Steps
Continue to **Link Extraction** to learn how to return links found on a webpage along with its extracted content.
# Link Extraction (/docs/scraper-api/guides/extraction/08_extracting_links)
By default, the Extraction API returns the extracted page content.
If you also need links found on the page, enable link extraction using the `extract_links` option.
## Enable Link Extraction
Set `extract_links` to `true` in the extraction request.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://quotes.toscrape.com/",
"formats": ["markdown"],
"extract_links": true
}'
```
## Response
When link extraction is enabled, the response includes a `links` field inside `data`.
```json title="response.json"
{
"data": {
"markdown": "...",
"html": null,
"links": [
"https://quotes.toscrape.com/login",
"https://quotes.toscrape.com/author/Albert-Einstein",
"https://www.goodreads.com/quotes"
]
}
}
```
## Access Extracted Links
The extracted links are available in:
```text title="response-path.txt"
data.links
```
Each item in the array contains a URL discovered on the extracted page.
## When to Use Link Extraction
Enable `extract_links` when you need to:
* Collect links from a webpage
* Discover related pages referenced by the content
* Build URL lists for further processing
* Analyze page relationships
## Important
`extract_links` returns links found on the extracted page.
It does not crawl those links or recursively discover additional pages.
For example:
```text
Page A
├─ Link B
├─ Link C
└─ Link D
```
The API returns links B, C, and D.
It does not visit those pages automatically.
{/* ## Link Extraction vs Map API
| Task | Recommended API |
|--------|--------|
| Extract content and links from a page | Extraction API |
| Discover URLs across a website | Map API |
| Crawl multiple pages | Map API |
| Build a site inventory | Map API |
Use the Map API when you need large-scale URL discovery before deciding which pages to extract. */}
## Success
You now know how to return links alongside extracted content in a single extraction request.
## Next Steps
Continue to **Extraction Workflows** to learn how different extraction options can be combined in real-world scenarios.
# Checking Job Status (/docs/scraper-api/guides/extraction/09_checking_job_status)
When you run an extraction in asynchronous mode, the API immediately returns a job ID instead of waiting for the extraction to finish.
You can use that job ID to check the current status of the extraction and retrieve the result once processing is complete.
## How It Works
The asynchronous extraction workflow follows these steps:
1. Start an extraction using `processing_mode: "async"`.
2. Receive a `job_id`.
3. Poll the job status endpoint.
4. Retrieve the extracted content when the job is completed.
## Get an Extraction Job
Use the following endpoint to retrieve the current status of an extraction job.
```http
GET /v1/extract/{job_id}
```
Replace `{job_id}` with the value returned by your extraction request.
## Example Request
```bash
curl -X GET "https://scraper.geonode.io/v1/extract/4844831a-a222-4cac-b5e6-7e3f2dd07b48" \
-H "X-Api-Key: YOUR_API_KEY"
```
## Response While Processing
A job may still be running when you check its status.
During this stage, the extracted content is not yet available.
```json
{
"job_id": "4844831a-a222-4cac-b5e6-7e3f2dd07b48",
"status": "processing",
"created_at": "2026-05-26T10:30:00Z",
"completed_at": null,
"data": null,
"metadata": null,
"error": null,
"tokens_charged": null
}
```
### What This Means
| Field | Description |
| ---------------- | ---------------------------------------------- |
| `status` | Current state of the extraction job |
| `created_at` | Time the job was created |
| `completed_at` | `null` until processing finishes |
| `data` | Extracted content, available after completion |
| `metadata` | Extraction details, available after completion |
| `error` | Error information if the job fails |
| `tokens_charged` | Token usage after processing completes |
## Response After Completion
Once the extraction finishes successfully, the response includes the extracted content and metadata.
```json
{
"job_id": "4844831a-a222-4cac-b5e6-7e3f2dd07b48",
"status": "completed",
"created_at": "2026-05-26T10:30:00Z",
"completed_at": "2026-05-26T10:30:04Z",
"data": {
"markdown": "# Example Page Content"
},
"metadata": {
"url": "https://docs.python.org/3/library/json.html",
"render_js": false,
"http_status": 200,
"duration_ms": 631,
"formats": ["markdown"],
"processing_mode": "async"
},
"error": null,
"tokens_charged": 1
}
```
## Job Status Values
The API can return the following job statuses.
| Status | Description |
| ------------ | ------------------------------------------------- |
| `queued` | The job has been accepted and is waiting to start |
| `processing` | The extraction is currently running |
| `completed` | The extraction finished successfully |
| `failed` | The extraction could not be completed |
| `cancelled` | The job was cancelled before completion |
## Starting an Async Extraction
To use this endpoint, first create an asynchronous extraction job.
```bash
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://docs.python.org/3/library/json.html",
"formats": ["markdown"],
"processing_mode": "async"
}'
```
## Async Job Response
The extraction endpoint returns a job ID that can be used for polling.
```json
{
"job_id": "4844831a-a222-4cac-b5e6-7e3f2dd07b48",
"status": "queued",
"status_url": "/v1/extract/4844831a-a222-4cac-b5e6-7e3f2dd07b48",
"estimated_tokens": 1
}
```
## Polling for Results
A common pattern is to periodically check the job status until the extraction completes.
```text
POST /v1/extract
↓
Receive job_id
↓
GET /v1/extract/{job_id}
↓
status = processing
↓
GET /v1/extract/{job_id}
↓
status = completed
↓
Read extracted content
```
## Next Step
Now that you can monitor individual extraction jobs, the next guide explains how to view and filter multiple extraction jobs using the Jobs endpoint.
# Listing Extraction Jobs (/docs/scraper-api/guides/extraction/10_listing_extraction_jobs)
Use the Jobs endpoint to view extraction jobs associated with your account.
This endpoint is useful when you need to find a previous job, retrieve a job ID, monitor running jobs, or review extraction history.
## List Extraction Jobs
Use the following endpoint to retrieve extraction jobs.
```http
GET /v1/extract/jobs
```
### Request
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs" \
-H "X-Api-Key: YOUR_API_KEY"
```
### Response
```json title="response.json"
{
"jobs": [
{
"job_id": "0131f784-9037-4fdd-af9e-b8d445fe2d5f",
"status": "completed",
"url": "https://geonode.com/",
"created_at": "2026-06-13T18:14:54.926869Z",
"execution_time": 2297,
"output": [
"html"
]
}
],
"page": 1,
"page_size": 100,
"page_count": 1
}
```
## Job Fields
Each job contains summary information about an extraction request.
| Field | Description |
| ---------------- | ----------------------------------------- |
| `job_id` | Unique identifier for the extraction job |
| `status` | Current status of the extraction |
| `url` | URL that was extracted |
| `created_at` | Time the job was created |
| `execution_time` | Processing time in milliseconds |
| `output` | Output formats returned by the extraction |
## Filter Jobs
### Filter by Status
Retrieve jobs with a specific status.
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs?status=completed" \
-H "X-Api-Key: YOUR_API_KEY"
```
Supported values:
```text
queued
processing
completed
failed
cancelled
```
### Filter by Output Format
Retrieve jobs that generated a specific output format.
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs?output=html" \
-H "X-Api-Key: YOUR_API_KEY"
```
Supported values:
```text
html
markdown
```
### Filter by URL
Retrieve jobs created for a specific URL.
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs?url=https://geonode.com/" \
-H "X-Api-Key: YOUR_API_KEY"
```
### Filter by Job ID
Retrieve a specific job from the results.
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs?job_id=0131f784-9037-4fdd-af9e-b8d445fe2d5f" \
-H "X-Api-Key: YOUR_API_KEY"
```
### Filter by Date Range
Retrieve jobs created within a specific time period.
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs?start_date=2026-06-01&end_date=2026-06-30" \
-H "X-Api-Key: YOUR_API_KEY"
```
## Pagination
Use pagination when working with a large number of extraction jobs.
### Request
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/jobs?page=1&page_size=5" \
-H "X-Api-Key: YOUR_API_KEY"
```
### Pagination Fields
| Field | Description |
| ------------ | -------------------------------- |
| `page` | Current page number |
| `page_size` | Number of jobs returned per page |
| `page_count` | Total number of available pages |
## Retrieve Full Job Details
The Jobs endpoint returns summary information.
To retrieve the complete extraction result, use:
```http
GET /v1/extract/{job_id}
```
Example:
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/0131f784-9037-4fdd-af9e-b8d445fe2d5f" \
-H "X-Api-Key: YOUR_API_KEY"
```
## Common Use Cases
Use this endpoint to:
* Find a lost job ID
* Review extraction history
* Monitor running jobs
* View completed extractions
* Search jobs by URL
* Retrieve recent extraction activity
## Success
You now know how to list, search, and filter extraction jobs.
## Next Steps
Continue to **Extraction Workflows** to learn how extraction features can be combined in real-world scenarios.
# Extraction Workflows (/docs/scraper-api/guides/extraction/11_extraction_workflows)
The Extraction API supports a variety of options that can be combined depending on your use case.
This guide demonstrates common extraction workflows and the recommended settings for each scenario.
## Standard Website Extraction
Use the default extraction settings when working with traditional websites that do not rely heavily on JavaScript.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com"
}'
```
### Best For
* Blogs
* News websites
* Documentation sites
* Static webpages
***
## AI and RAG Workflows
Markdown is often the preferred format when content will be processed by AI systems.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://docs.python.org/3/library/json.html",
"formats": ["markdown"]
}'
```
### Best For
* Vector databases
* RAG pipelines
* Embedding generation
* Knowledge bases
* LLM applications
***
## JavaScript-Powered Websites
Some websites render content in the browser and require JavaScript execution before extraction.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://geonode.com/",
"render_js": true
}'
```
### Best For
* React applications
* Next.js websites
* Vue applications
* Single-page applications (SPAs)
***
## Geo-Targeted Extraction
Use a proxy configuration when content changes based on visitor location.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"proxy": {
"country": "DE",
"type": "residential"
}
}'
```
### Best For
* Local search results
* Country-specific pricing
* Regional content
* Localized webpages
***
## Content and Link Extraction
Extract page content and collect links from the same request.
### Request
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://quotes.toscrape.com/",
"formats": ["markdown"],
"extract_links": true
}'
```
### Best For
* URL discovery
* Content analysis
* Link collection
* Website research
***
## Large Async Extractions
Use asynchronous processing for pages that may take longer to extract.
### Start the Extraction
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://geonode.com/",
"render_js": true,
"processing_mode": "async"
}'
```
### Response
```json title="response.json"
{
"job_id": "4844831a-a222-4cac-b5e6-7e3f2dd07b48",
"status": "queued",
"status_url": "/v1/extract/4844831a-a222-4cac-b5e6-7e3f2dd07b48"
}
```
### Check Job Status
```bash title="request.sh"
curl -X GET "https://scraper.geonode.io/v1/extract/4844831a-a222-4cac-b5e6-7e3f2dd07b48" \
-H "X-Api-Key: YOUR_API_KEY"
```
### Best For
* Large pages
* Slow websites
* Background processing
* High-volume workflows
***
## Recommended Settings
| Scenario | Recommended Configuration |
| ------------------------ | -------------------------- |
| Standard webpage | Default request |
| AI and RAG workflows | `formats: ["markdown"]` |
| JavaScript websites | `render_js: true` |
| Country-specific content | `proxy` |
| Link discovery | `extract_links: true` |
| Long-running extractions | `processing_mode: "async"` |
## Success
You now know how to combine extraction features for common real-world workflows.
## Next Steps
Continue to **Best Practices** to learn how to improve extraction performance, reliability, and efficiency.
# Best Practices (/docs/scraper-api/guides/extraction/12_best_practices)
The following recommendations can help improve extraction results and reduce unnecessary processing.
## Choose the Right Output Format
Use the output format that matches your use case.
| Format | Best For |
| ---------- | ---------------------------------------------------------- |
| `markdown` | AI workflows, RAG pipelines, indexing, and text processing |
| `html` | Preserving page structure and rendering content |
| Both | Applications that require both formats |
Requesting only the formats you need can reduce response size.
## Enable JavaScript Rendering Only When Needed
JavaScript rendering increases extraction time because the page must be rendered before content can be extracted.
Use:
```json title="request.json"
{
"render_js": true
}
```
only for websites that depend on client-side rendering.
Common examples include:
* React
* Next.js
* Vue
* Single-page applications (SPAs)
## Use Asynchronous Processing for Large Workloads
For long-running extractions, use asynchronous processing.
```json title="request.json"
{
"processing_mode": "async"
}
```
This prevents request timeouts and allows your application to continue processing while extraction runs in the background.
## Use Geo-Targeting Only When Required
Proxy routing may increase processing time.
Only specify a country when content differs by location.
```json title="request.json"
{
"proxy": {
"country": "DE",
"type": "residential"
}
}
```
## Reuse Job IDs
When using asynchronous extraction:
1. Create the extraction job once.
2. Store the returned `job_id`.
3. Poll the job status endpoint.
Avoid creating duplicate extraction jobs for the same request.
## Use Link Extraction Only When Needed
```json title="request.json"
{
"extract_links": true
}
```
Enable link extraction only when you need URLs from the page.
This keeps responses smaller and easier to process.
## Monitor Job Status
Before retrieving extraction results, check the job status.
```http
GET /v1/extract/{job_id}
```
Wait until the status becomes:
```text
completed
```
before processing the result.
## Store Extracted Content
If content does not change frequently, consider storing extraction results instead of repeatedly extracting the same page.
This can reduce costs and improve performance.
## Success
You now know the recommended practices for building reliable extraction workflows.
## Next Steps
Continue to **Common Errors** to learn how to troubleshoot common extraction issues.
# Common Errors (/docs/scraper-api/guides/extraction/common_errors)
The following issues are commonly encountered when working with the Extraction API.
## Missing API Key
Requests must include the `X-Api-Key` header.
### Incorrect
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract"
```
### Correct
```bash title="request.sh"
curl -X POST "https://scraper.geonode.io/v1/extract" \
-H "X-Api-Key: YOUR_API_KEY"
```
## Invalid URL
The `url` field must contain a valid URL.
### Incorrect
```json title="request.json"
{
"url": "example"
}
```
### Correct
```json title="request.json"
{
"url": "https://example.com"
}
```
## Job Still Processing
When using asynchronous extraction, the result may not be available immediately.
### Response
```json title="response.json"
{
"status": "processing",
"data": null
}
```
Wait until the job status becomes:
```text
completed
```
before attempting to use the extracted content.
## Job Not Found
A job may not exist or may belong to a different account.
### Request
```http
GET /v1/extract/{job_id}
```
Verify that the job ID is correct and that it was created using the same API key.
## Empty or Unexpected Results
Some websites require JavaScript rendering before content becomes available.
Try enabling:
```json title="request.json"
{
"render_js": true
}
```
This is common for:
* React applications
* Next.js websites
* Vue applications
* Single-page applications
## Geo-Targeted Content Is Different Than Expected
Some websites return different content based on location.
Specify a country explicitly:
```json title="request.json"
{
"proxy": {
"country": "US",
"type": "residential"
}
}
```
## Custom Headers Not Applied
Headers must be passed inside the `headers` object.
### Correct
```json title="request.json"
{
"headers": {
"Accept-Language": "en-US,en;q=0.9"
}
}
```
Do not place your Geonode API key inside the `headers` object.
Authentication must use:
```text
X-Api-Key
```
## Link Extraction Does Not Crawl Websites
`extract_links` only returns links found on the extracted page.
```json title="request.json"
{
"extract_links": true
}
```
It does not visit discovered links or recursively crawl a website.
For large-scale URL discovery, use the Map API.
## Using JavaScript Rendering Unnecessarily
JavaScript rendering increases extraction time.
```json title="request.json"
{
"render_js": true
}
```
Enable it only when a website requires client-side rendering.
## Need More Help?
If you continue to experience issues:
* Verify the request payload
* Verify the target URL
* Check job status for asynchronous requests
* Review response metadata
* Contact the Geonode support team
## Success
You now understand the most common Extraction API issues and how to resolve them.
## What's Next
You have completed the Extraction guides.
Continue to the next API section to learn about additional scraping and data collection capabilities.
# Overview (/docs/scraper-api/guides/mcp/00_overview)
Connect Geonode's scraping tools to the AI assistants and IDEs you already use. Once connected, your assistant can extract single pages, batch-process URL lists, and crawl whole sites from inside the tool you already work in.
## What is MCP?
Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Connecting Geonode over MCP lets your assistant fetch, render, and structure live web pages through Geonode's residential-proxy network.
## What you can do with Geonode MCP
Once connected, your assistant can call these tools based on your request:
| Tool | What it does |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `extract` | Scrape a single URL into Markdown or HTML. Supports JS rendering, proxy geo-targeting, and custom headers. |
| `batch` | Asynchronous extraction of up to 1,000 URLs in one job. |
| `batch_status` | Poll a batch job for progress and paginated results. |
| `cancel_batch` | Stop a running batch job. |
| `crawl` | Crawl a site from a seed URL (BFS, depth up to 10, up to 10,000 pages, same-domain or subdomain filtering). |
| `crawl_status` | Poll a crawl job for progress and crawled pages. |
| `cancel_crawl` | Stop a running crawl job. |
| `job` | Retrieve the result of a single async extraction. |
| `jobs` | List your extraction jobs with filters (status, URL, date, format). |
| `statistics` | Aggregated usage stats: extraction count, success rate, tokens used. |
The assistant picks the tool for you: ask it to read a page and it scrapes; ask it to pull every doc page on a site and it crawls.
## Install Geonode MCP
Start with [Before You Start](/docs/scraper-api/scraper-mcp/before-you-start) for your API key, endpoint, and authentication. Then follow the guide for your client:
* [Claude Desktop](/docs/scraper-api/scraper-mcp/claude-desktop)
* [Cursor](/docs/scraper-api/scraper-mcp/cursor)
* [Claude Code](/docs/scraper-api/scraper-mcp/claude-code)
* [Windsurf](/docs/scraper-api/scraper-mcp/windsurf)
* [Smithery](/docs/scraper-api/scraper-mcp/smithery)
* [Docker MCP](/docs/scraper-api/scraper-mcp/docker-mcp)
If something does not connect, see [Help & FAQ](/docs/scraper-api/scraper-mcp/help-and-faq).
# Before You Start (/docs/scraper-api/guides/mcp/01_before-you-start)
You'll need a Geonode API key. It's in your Geonode dashboard under **API Keys**. Keep it private.
## Endpoint
```
https://scraper.geonode.io/mcp
```
## Authentication
Geonode MCP reads your API key from the `X-Api-Key` HTTP header. Clients that can't set custom headers can instead pass the key as an `api_key` argument on each tool call. The header is the better option, so the client guides below use it.
Replace `YOUR_API_KEY` with your real key in every example below.
# Claude Code (/docs/scraper-api/guides/mcp/02_claude-code)
Claude Code adds remote HTTP servers from the terminal in one command.
***
## Step 1 — Add the server
Run:
```bash
claude mcp add --transport http geonode-scraper https://scraper.geonode.io/mcp \
--header "X-Api-Key: YOUR_API_KEY"
```
All options (`--transport`, `--header`, `--scope`) come **before** the server name.
***
## Step 2 — Choose scope (optional)
* Add `--scope project` to write the config to a shared `.mcp.json` in your repo, so teammates inherit the server when they commit it.
* Add `--scope user` to make the server available across all your projects.
* The default scope is local to the current project.
***
## Step 3 — Manage or remove the connection
Check and manage the connection inside a session with the `/mcp` slash command.
Remove the server any time with:
```bash
claude mcp remove geonode-scraper
```
# Claude Desktop (/docs/scraper-api/guides/mcp/03_claude-desktop)
Geonode authenticates with an API-key header, so Claude Desktop connects through the `mcp-remote` bridge. The built-in "Add custom connector" UI is built for OAuth servers and has no field for a custom header.
***
## Step 1 — Open Claude Desktop config
1. Open Claude Desktop → **Settings** → **Developer** → **Edit Config**.
2. This opens `claude_desktop_config.json`.
***
## Step 2 — Add the Geonode server
Add the Geonode server block to `mcpServers`:
```json
{
"mcpServers": {
"geonode-scraper": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://scraper.geonode.io/mcp",
"--header",
"X-Api-Key:${GEONODE_API_KEY}"
],
"env": {
"GEONODE_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
***
## Step 3 — Restart and verify
1. Save the file and fully restart Claude Desktop.
2. The Geonode tools show up under the tools menu in a new chat.
`mcp-remote` needs Node.js installed on your machine. The
`X-Api-Key:${GEONODE_API_KEY}` value has no space after the colon on purpose,
since `mcp-remote` reads everything after the first colon as the header value.
# Cursor (/docs/scraper-api/guides/mcp/04_cursor)
Cursor supports remote MCP servers over a URL with headers.
***
## Step 1 — Open MCP settings
1. Open **Cursor Settings** → **MCP** → **Add new MCP server**.
2. Or edit `~/.cursor/mcp.json` directly.
***
## Step 2 — Add server configuration
Add the Geonode server block:
```json
{
"mcpServers": {
"geonode-scraper": {
"url": "https://scraper.geonode.io/mcp",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
```
***
## Step 3 — Refresh and use in Agent mode
1. Save and refresh the MCP server list in Settings. A green dot means it connected, and the Geonode tools become available to the Agent.
2. In the Composer (Agent mode), describe what you want scraped and Cursor calls Geonode for you.
# Docker MCP (/docs/scraper-api/guides/mcp/05_docker-mcp)
For self-hosted or containerized setups, run the Geonode connection through Docker so it sits alongside your other MCP gateway services instead of on each developer's machine.
***
## Option A — Bridge with a container
Run the hosted MCP endpoint through `mcp-remote` inside a container:
```bash
docker run -i --rm \
-e GEONODE_API_KEY=YOUR_API_KEY \
node:20-alpine \
npx -y mcp-remote https://scraper.geonode.io/mcp \
--header "X-Api-Key:${GEONODE_API_KEY}"
```
Point your client's MCP config at this container as a stdio command, or register it behind the Docker MCP Gateway or MCP Toolkit so all your AI clients share one managed endpoint.
***
## Option B — Docker MCP Toolkit (Docker Desktop)
Add Geonode as a custom server in the MCP Toolkit catalog using the production URL and the `X-Api-Key` header, then enable it for the clients you've connected to the gateway.
# Smithery (/docs/scraper-api/guides/mcp/06_smithery)
Smithery is a registry and gateway for deploying and managing MCP servers across clients.
***
## Step 1 — Install from the registry
Once Geonode Scraper is published to the Smithery registry, install it into any supported client with one command:
```bash
npx -y @smithery/cli install @geonode/scraper-mcp --client claude
```
Swap `--client claude` for `cursor`, `windsurf`, `vscode`, and so on.
***
## Step 2 — Complete setup in your client
Smithery asks for your Geonode API key during install and writes the config into the target client for you.
Until the registry listing is live, use the per-client instructions in this
section with the production endpoint
`https://scraper.geonode.io/mcp`.
# Windsurf (/docs/scraper-api/guides/mcp/07_windsurf)
Windsurf connects to remote servers through its MCP config file.
***
## Step 1 — Open MCP settings
1. Open **Windsurf Settings** → **Cascade** → **MCP Servers** → **Manage / Add custom server**.
2. Or edit `~/.codeium/windsurf/mcp_config.json` directly.
***
## Step 2 — Add server configuration
Add the Geonode server block:
```json
{
"mcpServers": {
"geonode-scraper": {
"serverUrl": "https://scraper.geonode.io/mcp",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
```
***
## Step 3 — Refresh the MCP panel
1. Save the config file.
2. Click **Refresh** in the MCP panel. Geonode's tools appear for Cascade's agents.
# Help & FAQ (/docs/scraper-api/guides/mcp/help-and-faq)
## Troubleshooting
* **No tools appear:** check that Node.js is installed (for `mcp-remote` setups), restart the client fully, and re-check the endpoint URL.
* **401 / authentication errors:** check the `X-Api-Key` value and that the key is active in your Geonode dashboard.
* **Header not recognized:** with `mcp-remote`, keep the format `X-Api-Key:${VAR}` with no space after the colon.
***
## FAQs
Any MCP-compatible client. Claude Desktop, Cursor, Claude Code, and Windsurf
have direct support; Smithery and Docker MCP help you deploy and manage
connections.
{" "}
Only what you ask it to scrape, through your authenticated Geonode account and
its limits.
{" "}
You need an active Geonode API key. On the client side, some assistants require
their own paid tier to turn on MCP.
# Cancel a Batch Job (/docs/scraper-api/v1/batch/cancel-batch-job)
Stop scheduling new batch items and let in-flight child extractions drain
# Get Batch Job Status (/docs/scraper-api/v1/batch/get-batch-job-status)
Poll for the current status and partial results of a batch job
# Start a Batch Job (/docs/scraper-api/v1/batch/start-batch-job)
Queue a batch of URLs for asynchronous extraction
# Cancel a Crawl Job (/docs/scraper-api/v1/crawl/cancel-crawl-job)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Stop scheduling new crawl pages and let in-flight page work drain
# Get Crawl Job Status (/docs/scraper-api/v1/crawl/get-crawl-job-status)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Poll for the current status and results of a crawl job
# Start a Crawl Job (/docs/scraper-api/v1/crawl/start-crawl-job)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Crawl a website starting from a seed URL up to a given depth and page limit
# Extract Content (/docs/scraper-api/v1/extraction/extract-content)
Extract clean markdown or HTML from any URL with sync or async mode support
# Get Extraction Job (/docs/scraper-api/v1/extraction/get-extraction-job)
Poll for job progress and retrieve extraction results (async mode only)
# List Extraction Jobs (/docs/scraper-api/v1/extraction/list-extraction-jobs)
List and filter extraction jobs by job ID, URL, status, output format, and date range
# Map URLs (/docs/scraper-api/v1/map/map-urls)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Returns the list of URLs found under the given base URL by combining sitemap parsing with HTML link extraction from the seed page. The optional `search` parameter filters the discovered URLs by case-insensitive substring match — it does NOT query a search engine.
# Before You Start (/docs/scraper-api/v1/scraper-mcp/before-you-start)
You'll need a Geonode API key. It's in your Geonode dashboard under **API Keys**. Keep it private.
## Endpoint
```
https://scraper.geonode.io/mcp
```
## Authentication
Geonode MCP reads your API key from the `X-Api-Key` HTTP header. Clients that can't set custom headers can instead pass the key as an `api_key` argument on each tool call. The header is the better option, so the client guides below use it.
Replace `YOUR_API_KEY` with your real key in every example below.
# Claude Code (/docs/scraper-api/v1/scraper-mcp/claude-code)
Claude Code adds remote HTTP servers from the terminal in one command.
***
## Step 1 — Add the server
Run:
```bash
claude mcp add --transport http geonode-scraper https://scraper.geonode.io/mcp \
--header "X-Api-Key: YOUR_API_KEY"
```
All options (`--transport`, `--header`, `--scope`) come **before** the server name.
***
## Step 2 — Choose scope (optional)
* Add `--scope project` to write the config to a shared `.mcp.json` in your repo, so teammates inherit the server when they commit it.
* Add `--scope user` to make the server available across all your projects.
* The default scope is local to the current project.
***
## Step 3 — Manage or remove the connection
Check and manage the connection inside a session with the `/mcp` slash command.
Remove the server any time with:
```bash
claude mcp remove geonode-scraper
```
# Claude Desktop (/docs/scraper-api/v1/scraper-mcp/claude-desktop)
Geonode authenticates with an API-key header, so Claude Desktop connects through the `mcp-remote` bridge. The built-in "Add custom connector" UI is built for OAuth servers and has no field for a custom header.
***
## Step 1 — Open Claude Desktop config
1. Open Claude Desktop → **Settings** → **Developer** → **Edit Config**.
2. This opens `claude_desktop_config.json`.
***
## Step 2 — Add the Geonode server
Add the Geonode server block to `mcpServers`:
```json
{
"mcpServers": {
"geonode-scraper": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://scraper.geonode.io/mcp",
"--header",
"X-Api-Key:${GEONODE_API_KEY}"
],
"env": {
"GEONODE_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
***
## Step 3 — Restart and verify
1. Save the file and fully restart Claude Desktop.
2. The Geonode tools show up under the tools menu in a new chat.
`mcp-remote` needs Node.js installed on your machine. The
`X-Api-Key:${GEONODE_API_KEY}` value has no space after the colon on purpose,
since `mcp-remote` reads everything after the first colon as the header value.
# Cursor (/docs/scraper-api/v1/scraper-mcp/cursor)
Cursor supports remote MCP servers over a URL with headers.
***
## Step 1 — Open MCP settings
1. Open **Cursor Settings** → **MCP** → **Add new MCP server**.
2. Or edit `~/.cursor/mcp.json` directly.
***
## Step 2 — Add server configuration
Add the Geonode server block:
```json
{
"mcpServers": {
"geonode-scraper": {
"url": "https://scraper.geonode.io/mcp",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
```
***
## Step 3 — Refresh and use in Agent mode
1. Save and refresh the MCP server list in Settings. A green dot means it connected, and the Geonode tools become available to the Agent.
2. In the Composer (Agent mode), describe what you want scraped and Cursor calls Geonode for you.
# Docker MCP (/docs/scraper-api/v1/scraper-mcp/docker-mcp)
For self-hosted or containerized setups, run the Geonode connection through Docker so it sits alongside your other MCP gateway services instead of on each developer's machine.
***
## Option A — Bridge with a container
Run the hosted MCP endpoint through `mcp-remote` inside a container:
```bash
docker run -i --rm \
-e GEONODE_API_KEY=YOUR_API_KEY \
node:20-alpine \
npx -y mcp-remote https://scraper.geonode.io/mcp \
--header "X-Api-Key:${GEONODE_API_KEY}"
```
Point your client's MCP config at this container as a stdio command, or register it behind the Docker MCP Gateway or MCP Toolkit so all your AI clients share one managed endpoint.
***
## Option B — Docker MCP Toolkit (Docker Desktop)
Add Geonode as a custom server in the MCP Toolkit catalog using the production URL and the `X-Api-Key` header, then enable it for the clients you've connected to the gateway.
# Help & FAQ (/docs/scraper-api/v1/scraper-mcp/help-and-faq)
## Troubleshooting
* **No tools appear:** check that Node.js is installed (for `mcp-remote` setups), restart the client fully, and re-check the endpoint URL.
* **401 / authentication errors:** check the `X-Api-Key` value and that the key is active in your Geonode dashboard.
* **Header not recognized:** with `mcp-remote`, keep the format `X-Api-Key:${VAR}` with no space after the colon.
***
## FAQs
Any MCP-compatible client. Claude Desktop, Cursor, Claude Code, and Windsurf
have direct support; Smithery and Docker MCP help you deploy and manage
connections.
{" "}
Only what you ask it to scrape, through your authenticated Geonode account and
its limits.
{" "}
You need an active Geonode API key. On the client side, some assistants require
their own paid tier to turn on MCP.
# Overview (/docs/scraper-api/v1/scraper-mcp/overview)
Connect Geonode's scraping tools to the AI assistants and IDEs you already use. Once connected, your assistant can extract single pages, batch-process URL lists, and crawl whole sites from inside the tool you already work in.
## What is MCP?
Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Connecting Geonode over MCP lets your assistant fetch, render, and structure live web pages through Geonode's residential-proxy network.
## What you can do with Geonode MCP
Once connected, your assistant can call these tools based on your request:
| Tool | What it does |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `extract` | Scrape a single URL into Markdown or HTML. Supports JS rendering, proxy geo-targeting, and custom headers. |
| `batch` | Asynchronous extraction of up to 1,000 URLs in one job. |
| `batch_status` | Poll a batch job for progress and paginated results. |
| `cancel_batch` | Stop a running batch job. |
| `crawl` | Crawl a site from a seed URL (BFS, depth up to 10, up to 10,000 pages, same-domain or subdomain filtering). |
| `crawl_status` | Poll a crawl job for progress and crawled pages. |
| `cancel_crawl` | Stop a running crawl job. |
| `job` | Retrieve the result of a single async extraction. |
| `jobs` | List your extraction jobs with filters (status, URL, date, format). |
| `statistics` | Aggregated usage stats: extraction count, success rate, tokens used. |
The assistant picks the tool for you: ask it to read a page and it scrapes; ask it to pull every doc page on a site and it crawls.
## Install Geonode MCP
Start with [Before You Start](/docs/scraper-api/scraper-mcp/before-you-start) for your API key, endpoint, and authentication. Then follow the guide for your client:
* [Claude Desktop](/docs/scraper-api/scraper-mcp/claude-desktop)
* [Cursor](/docs/scraper-api/scraper-mcp/cursor)
* [Claude Code](/docs/scraper-api/scraper-mcp/claude-code)
* [Windsurf](/docs/scraper-api/scraper-mcp/windsurf)
* [Smithery](/docs/scraper-api/scraper-mcp/smithery)
* [Docker MCP](/docs/scraper-api/scraper-mcp/docker-mcp)
If something does not connect, see [Help & FAQ](/docs/scraper-api/scraper-mcp/help-and-faq).
# Smithery (/docs/scraper-api/v1/scraper-mcp/smithery)
Smithery is a registry and gateway for deploying and managing MCP servers across clients.
***
## Step 1 — Install from the registry
Once Geonode Scraper is published to the Smithery registry, install it into any supported client with one command:
```bash
npx -y @smithery/cli install @geonode/scraper-mcp --client claude
```
Swap `--client claude` for `cursor`, `windsurf`, `vscode`, and so on.
***
## Step 2 — Complete setup in your client
Smithery asks for your Geonode API key during install and writes the config into the target client for you.
Until the registry listing is live, use the per-client instructions in this
section with the production endpoint
`https://scraper.geonode.io/mcp`.
# Windsurf (/docs/scraper-api/v1/scraper-mcp/windsurf)
Windsurf connects to remote servers through its MCP config file.
***
## Step 1 — Open MCP settings
1. Open **Windsurf Settings** → **Cascade** → **MCP Servers** → **Manage / Add custom server**.
2. Or edit `~/.codeium/windsurf/mcp_config.json` directly.
***
## Step 2 — Add server configuration
Add the Geonode server block:
```json
{
"mcpServers": {
"geonode-scraper": {
"serverUrl": "https://scraper.geonode.io/mcp",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
```
***
## Step 3 — Refresh the MCP panel
1. Save the config file.
2. Click **Refresh** in the MCP panel. Geonode's tools appear for Cascade's agents.
# Get Statistics (/docs/scraper-api/v1/statistics/get-statistics)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Retrieve aggregated extraction statistics for a given date range
# Health Check (/docs/scraper-api/v1/system/health-check)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a Webhook (/docs/scraper-api/v1/webhooks/create-webhook)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Create a webhook subscription for a given event type and return its generated signing secret
# Delete a Webhook (/docs/scraper-api/v1/webhooks/delete-webhook)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Permanently remove a webhook subscription
# Get a Webhook (/docs/scraper-api/v1/webhooks/get-webhook)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Retrieve a single webhook by its identifier
# List Webhook Deliveries (/docs/scraper-api/v1/webhooks/list-webhook-deliveries)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
List webhook delivery attempts with optional status filter and pagination
# List Webhooks (/docs/scraper-api/v1/webhooks/list-webhooks)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
List webhooks registered for the current user with pagination
# Rotate Webhook Secret (/docs/scraper-api/v1/webhooks/rotate-webhook-secret)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Generate a new signing secret for the webhook and invalidate the previous one
# Update a Webhook (/docs/scraper-api/v1/webhooks/update-webhook)
This endpoint is documented but not yet available in production. The contract
below reflects the planned behavior. Reach out via
[support](https://geonode.com/contact) for early access or launch notification.
Partially update a webhook's url, description, event type, or active flag