Build a NodeMaven proxy URL with geo targeting encoded in the username.

Use this to hand a ready connection string to another tool - curl, Playwright, Scrapy, requests - instead of guessing NodeMaven's username syntax. No network call is made. To verify the IP actually works, use nodemaven_check_proxy.

Returns: str: Markdown or JSON with the schema: { "proxy_url": str, # e.g. "http://user-country-us-sid-ab12:***@gate.nodemaven.com:8080" "username": str, # targeting username "host": str, "port": int, "protocol": str, "password_masked": bool } On failure: "Error: "

Examples: - "give me a US proxy string for curl" -> country='us', reveal_credentials=true - "same IP for the whole login flow" -> session_id='ab12cd' - Don't use when: you want the page content (use nodemaven_fetch instead)

Send one request through the proxy and report the exit IP, its geo and latency.

Use this before a scraping run to confirm the targeting resolves to a real pool and that the exit IP is where you expect. Over-narrow targeting (a rare city plus an ISP filter) is the usual reason a connection fails.

Returns: str: Markdown or JSON with the schema: { "exit_ip": str, # e.g. "104.28.51.7" "country": str, # e.g. "US" "region": str, "city": str, "org": str, "latency_ms": int, "proxy": str, # password-masked proxy URL "session_id_used": bool } On failure: "Error: "

Examples: - "am I really coming out of Germany?" -> country='de' - "does this sticky session hold?" -> session_id='ab12cd', call twice - Don't use when: you need the catalogue of available cities (use nodemaven_list_locations)

Fetch a URL through a NodeMaven residential or mobile IP and return its content.

Use this when a page is geo-restricted or blocks datacenter traffic. HTML is converted to readable text by default so it does not flood the context; set as_text=false when the markup itself matters.

Returns: str: Markdown or JSON with the schema: { "url": str, # final URL after redirects "status_code": int, "content_type": str, "title": str | None, # HTML when available "latency_ms": int, "truncated": bool, "bytes": int, "body": str, "proxy": str # password-masked proxy URL } On failure: "Error: "

Examples: - "read this page as a German visitor" -> url=..., country='de' - "check the price shown to US shoppers" -> url=..., country='us', city='new york' - Don't use when: the site is reachable without a proxy (use a plain fetch)

List the countries, regions, cities, ISPs or zip codes available for targeting.

Use this to discover exact spellings before targeting - guessing a city name is the most common reason a proxy connection returns an empty pool.

Returns: str: Markdown or JSON with the schema: { "total": int, "count": int, "offset": int, "limit": int, "has_more": bool, "next_offset": int | None, "items": [ { ... } ] # raw records as returned by NodeMaven } On failure: "Error: "

Examples: - "which countries can I target?" -> level='countries' - "list German cities" -> level='cities', country='de' - "which carriers exist in the US?" -> level='isps', country='us'

Requires NODEMAVEN_API_KEY.

Report account usage: traffic consumed, request counts or per-domain breakdown.

Use this to check remaining traffic before a large run, or to attribute spend to the domains that caused it.

Returns: str: Markdown or JSON with the same pagination envelope as nodemaven_list_locations, where items are usage records. On failure: "Error: "

Examples: - "how much traffic have I burned?" -> kind='data' - "which domains cost me the most?" -> kind='domains'

Requires NODEMAVEN_API_KEY.