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

# Generate proxies

> GET /api/genProxy: generate proxies in any format from a template

Turn a single proxy template (with whatever targeting and session settings you want) into a list of formatted proxy strings.

<Note>
  **No authentication required.** `genProxy` is a pure formatter — it expands your template into the requested count and output format. It does not validate your credentials, your targeting, or that the resulting proxies actually work; it just reformats whatever template you pass in. Test the output with a real request (see [Quickstart](/quickstart#4-test-it)).
</Note>

## Query parameters

<ParamField query="proxy" type="string" required>
  URL-encoded proxy template in the form `username:password:host:port`. The username can contain all the geo/session/ASN segments you want: see [Residential setup](/setup/residential#username-segments).

  **The port in the template determines the session type.** The example below uses `:10000` (sticky) with a `-session-` segment. For rotating proxies, use the rotating port (`:9000` for Residential HTTP) and omit the `-session-` segment. See [Residential ports](/setup/residential#ports).
</ParamField>

<ParamField query="format" type="string" required>
  Output format string. Token reference:
  , `h` → host
  , `pt` → port
  , `u` → username
  , `ps` → password

  Examples: `h:pt:u:ps` produces `host:port:username:password`.
</ParamField>

<ParamField query="amount" type="number" required>
  Number of proxies to return. Maximum **1000** per request (the response is capped at 1000 lines). To generate more, page across multiple calls — e.g. vary the `-session-` segment per batch.
</ParamField>

## Example request

```bash theme={"dark"}
curl "https://www.eclipseproxy.com/api/genProxy?\
proxy=eclipse_yourname-country-kh-state-phnompenh-asn-38901-session-session123-lifetime-30%3A8d5c90c2-3f3d-4061-be8e-579c49e0fa7a%3Acore.eclipseproxy.com%3A10000\
&format=h:pt:u:ps\
&amount=10"
```

The `%3A` is URL-encoded `:`: needed because the proxy template itself contains colons.

## Response format

The response is **plain text** (`text/plain`), **one proxy per line, newline-delimited** — not JSON. Split on newlines to get the list (this is why the examples below use `.text.splitlines()` / `.split("\n")`).

```
core.eclipseproxy.com:10000:eclipse_yourname-country-kh-...:8d5c90c2-...
core.eclipseproxy.com:10000:eclipse_yourname-country-kh-...:8d5c90c2-...
...
```

Each line follows the `format` string you passed. The response contains at most **1000 lines** (see `amount`).

## Generating across many countries

Loop the request: one call per country, then concatenate:

<CodeGroup>
  ```python python theme={"dark"}
  import requests, urllib.parse

  TEMPLATE = "eclipse_yourname-country-{cc}-session-{sid}-lifetime-30:YOUR_PASS:core.eclipseproxy.com:10000"
  COUNTRIES = ["us", "gb", "de", "fr", "kh"]

  all_proxies = []
  for cc in COUNTRIES:
      proxy = urllib.parse.quote(TEMPLATE.format(cc=cc, sid=f"batch-{cc}"))
      r = requests.get(
          f"https://www.eclipseproxy.com/api/genProxy"
          f"?proxy={proxy}&format=h:pt:u:ps&amount=10"
      )
      all_proxies.extend(r.text.splitlines())

  print(len(all_proxies), "proxies generated")
  ```

  ```javascript node theme={"dark"}
  const countries = ["us", "gb", "de", "fr", "kh"];
  const template = (cc, sid) =>
    `eclipse_yourname-country-${cc}-session-${sid}-lifetime-30:YOUR_PASS:core.eclipseproxy.com:10000`;

  const all = [];
  for (const cc of countries) {
    const proxy = encodeURIComponent(template(cc, `batch-${cc}`));
    const r = await fetch(
      `https://www.eclipseproxy.com/api/genProxy?proxy=${proxy}&format=h:pt:u:ps&amount=10`
    );
    all.push(...(await r.text()).split("\n"));
  }
  console.log(all.length, "proxies generated");
  ```

  ```bash curl theme={"dark"}
  for cc in us gb de fr kh; do
    curl -s "https://www.eclipseproxy.com/api/genProxy\
  ?proxy=eclipse_yourname-country-$cc-session-batch-$cc-lifetime-30%3AYOUR_PASS%3Acore.eclipseproxy.com%3A10000\
  &format=h:pt:u:ps&amount=10"
  done
  ```
</CodeGroup>

## Rotating sessions on demand

To force a new IP on a sticky session, change the `session-` segment in the proxy template before regenerating. Same session ID returns the same IP; new session ID returns a new IP.

## Use cases

* Bulk generation: get 100 proxies at once for a scrape job
* Format conversion: generate the same logical proxy in multiple formats for different tools
* Per-session batching: append a random session ID, request `amount=N`, get N unique sticky sessions