> ## Documentation Index > Fetch the complete documentation index at: https://floppydata.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Connections > Builds one rotating proxy connection string from dashboard-style options. Use connection.connectionString as the primary copy-paste value. Set subuserId to an ID from /v2/proxy/rotating/subusers, or omit it to use the first account subuser. Use locations first to choose valid country, city, and state values; state takes precedence over city. Run this request to generate a live `connection.connectionString` you can copy into an HTTP client, browser profile, or proxy checker. The `subuserId` field is optional. Omit it to use your account's default proxy credentials, or see [Manage Rotating Proxy Subusers](/docs/guides/subusers) when you need separate proxy groups or replacement credentials. For UDP, set `protocol` to `socks5`, choose `residential` or `mobile`, and set `udp` to `true`. ## OpenAPI ````yaml api-reference/openapi.json POST /v2/proxy/rotating/connections openapi: 3.1.0 info: title: Floppydata Client API description: >- Client API v2 for Web Data, proxy products, proxy tools, and account rollups. You can manage your API keys in [API keys](https://app.floppydata.com/api-keys). version: 2.0.0 servers: - url: https://api.floppydata.net description: Production security: - apiKeyHeader: [] tags: - name: Web Data description: Fetch pages and inspect Web Data balance and usage. - name: Proxy description: Proxy tools shared across proxy products. - name: Rotating Proxy description: Rotating proxy subusers, connections, locations, balance, and usage. - name: Static Proxy description: Static proxy inventory for the authenticated account. - name: Account description: Account-level balance and usage rollups across available products. - name: Cloud Browser description: |- Session-first cloud browsers with persistent settings under the hood. Create a session, connect using the returned WebSocket URL, then navigate with Playwright or Puppeteer. Reuse settings.id to restore the same identity and browser state. paths: /v2/proxy/rotating/connections: post: tags: - Rotating Proxy summary: Build a rotating proxy connection description: >- Builds one rotating proxy connection string from dashboard-style options. Use connection.connectionString as the primary copy-paste value. Set subuserId to an ID from /v2/proxy/rotating/subusers, or omit it to use the first account subuser. Use locations first to choose valid country, city, and state values; state takes precedence over city. operationId: buildRotatingProxyConnection requestBody: content: application/json: schema: type: object properties: subuserId: description: >- Subuser ID from GET /v2/proxy/rotating/subusers. When omitted, the first account subuser is used. example: 123 type: integer exclusiveMinimum: 0 maximum: 9007199254740991 type: type: string enum: - residential - mobile - datacenter description: Proxy type example: residential country: description: 2-letter country code. example: US type: string pattern: ^[a-zA-Z]{2}$ city: description: >- City name from GET /v2/proxy/rotating/locations. Spaces are encoded as underscores. Used only when state is not supplied. example: New York type: string minLength: 1 state: description: >- State or subdivision value from GET /v2/proxy/rotating/locations. When supplied, it takes precedence over city. example: CA type: string minLength: 1 asn: description: Target ASN as digits. example: '15169' type: string pattern: ^\d+$ rotation: default: 15 description: >- Rotation value: -1 for each request, 0 for sticky, or interval minutes. example: 15 anyOf: - type: number const: -1 - type: number const: 0 - type: number const: 5 - type: number const: 10 - type: number const: 15 - type: number const: 20 - type: number const: 60 session: example: my_session_1 type: string minLength: 1 maxLength: 128 protocol: default: http example: http type: string enum: - http - https - socks5 udp: default: false description: >- Route UDP traffic through the proxy. Supported only for SOCKS5 residential or mobile proxies. example: false type: boolean required: - type - country additionalProperties: false responses: '200': description: Generated rotating proxy connection details. content: application/json: schema: type: object properties: connection: type: object properties: protocol: type: string enum: - http - https - socks5 example: http host: type: string example: geo.g-w.info port: type: integer minimum: -9007199254740991 maximum: 9007199254740991 example: 10080 username: type: string example: >- user-USERNAME-type-residential-session-my_session_1-country-US-city-New_York-asn-15169-rotation-15-udp-1 password: type: string example: PASSWORD connectionString: type: string description: Canonical copy-paste proxy URL. example: >- socks5://user-USERNAME-type-residential-session-my_session_1-country-US-city-New_York-asn-15169-rotation-15-udp-1:PASSWORD@geo.g-w.info:10800 required: - protocol - host - port - username - password - connectionString description: >- Generated proxy connection. Use connection.connectionString as the primary copy-paste value. parameters: type: object properties: subuserId: description: >- Subuser ID from GET /v2/proxy/rotating/subusers. When omitted, the first account subuser is used. example: 123 type: integer exclusiveMinimum: 0 maximum: 9007199254740991 type: type: string enum: - residential - mobile - datacenter description: Proxy type example: residential country: description: 2-letter country code. example: US type: string pattern: ^[a-zA-Z]{2}$ city: description: >- City name from GET /v2/proxy/rotating/locations. Spaces are encoded as underscores. Used only when state is not supplied. example: New York type: string minLength: 1 state: description: >- State or subdivision value from GET /v2/proxy/rotating/locations. When supplied, it takes precedence over city. example: CA type: string minLength: 1 asn: description: Target ASN as digits. example: '15169' type: string pattern: ^\d+$ rotation: default: 15 description: >- Rotation value: -1 for each request, 0 for sticky, or interval minutes. example: 15 anyOf: - type: number const: -1 - type: number const: 0 - type: number const: 5 - type: number const: 10 - type: number const: 15 - type: number const: 20 - type: number const: 60 session: example: my_session_1 type: string minLength: 1 maxLength: 128 protocol: default: http example: http type: string enum: - http - https - socks5 udp: default: false description: >- Route UDP traffic through the proxy. Supported only for SOCKS5 residential or mobile proxies. example: false type: boolean required: - type - country additionalProperties: false required: - connection - parameters example: connection: protocol: socks5 host: geo.g-w.info port: 10800 username: >- user-USERNAME-type-residential-session-my_session_1-country-US-state-california-asn-15169-rotation-15-udp-1 password: PASSWORD connectionString: >- socks5://user-USERNAME-type-residential-session-my_session_1-country-US-state-california-asn-15169-rotation-15-udp-1:PASSWORD@geo.g-w.info:10800 parameters: subuserId: 123 type: residential country: US state: california asn: '15169' rotation: 15 session: my_session_1 protocol: socks5 udp: true '400': description: The request body or query parameters are invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: invalid_request message: Invalid request parameters. details: issues: - path: country code: invalid_format message: Expected a 2-letter country code. '401': description: The API key is missing, invalid, or expired. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: unauthorized message: Unauthorized details: {} '402': description: The account does not have enough balance for this request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: insufficient_balance message: Insufficient proxy traffic balance. details: {} '403': description: The API key does not grant access to this operation. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: forbidden message: Forbidden details: {} '404': description: The requested resource is not available. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: not_found message: Rotating proxy credential was not found. details: {} '409': description: The authenticated account is not configured for this product. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: account_not_configured message: Account is not configured for proxy products. details: {} '500': description: An unexpected server error occurred. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: internal_error message: Internal Server Error details: {} '502': description: An upstream service failed while processing the request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - forbidden - invalid_request - insufficient_balance - account_not_configured - not_found - settings_in_use - settings_limit_reached - session_not_active - connection_in_use - upstream_error - internal_error message: type: string example: Invalid request parameters. details: type: object properties: target: example: settings.id type: string recoveryHint: example: >- Stop the active session before reusing these settings. type: string activeSessionId: example: 58e531ee-16ca-49d0-8722-b425d154cc10 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nextOperationId: example: stopBrowserSession type: string requestId: example: a1901a29e82a999f-CDG type: string upstreamStatus: example: 503 type: integer minimum: 100 maximum: 599 failureStage: example: provider_browser_start type: string diagnosticCode: example: token_sign_failed type: string additionalProperties: {} required: - code - message - details required: - error example: error: code: upstream_error message: Failed to fetch data from an upstream service. details: upstreamStatus: 503 components: securitySchemes: apiKeyHeader: type: apiKey in: header name: X-Api-Key description: Client API key for the authenticated account. ````