---
title: "Search providers (filters, sorting, paging)"
method: GET
path: "/providers"
tags: ["providers"]
---

# Search providers (filters, sorting, paging)

`GET /providers`

## Request

- Base URL: `https://workingproxysites.info/api/v1`
- URL: `https://workingproxysites.info/api/v1/providers`
- Auth: none required

Searches the provider database. Without parameters: active providers in rank order (featured, community score, staff rank), 50 per page. Each entry is the full ProviderRecord plus live summary fields. Invalid values are a 400 whose error lists the allowed values; unknown parameters are ignored and named in `warnings`. Product filters (pricing_model, max_price, min_countries, min_pool, targeting, country, rotation, unlimited_bandwidth, plus protocol when any of them is set) must all hold for one and the same product (of `type` when given), never match an unknown value, and so only match providers with structured product data. A known parameter given more than once is a 400.

## Query parameters

- `type` 'residential' | 'mobile' | 'datacenter' | 'isp'
- `protocol` 'HTTP' | 'HTTPS' | 'SOCKS5' | 'UDP'
- `pricing_model` 'per_gb' | 'per_ip' | 'per_port' | 'per_request' | 'unlimited' | 'other'
- `max_price` number
- `min_countries` integer
- `min_pool` integer
- `targeting` 'country' | 'state' | 'city' | 'zip' | 'asn' | 'carrier'
- `kyc` 'none' | 'conditional' | 'required' | 'unknown'
- `payment` 'card' | 'paypal' | 'crypto' | 'wire' | 'alipay' | 'google_pay' | 'apple_pay' | 'other'
- `free_trial` 'true' | 'false'
- `api` 'true' | 'false'
- `listing_status` 'active' | 'pre-launch' | 'defunct' | 'suspended' | 'unverifiable' | 'any'
- `live_status` 'operational' | 'degraded' | 'down' | 'unknown'
- `q` string
- `country` string
- `rotation` 'per_request' | 'timed' | 'sticky' | 'static'
- `unlimited_bandwidth` 'true' | 'false'
- `auth` 'user_pass' | 'ip_whitelist' | 'api_token'
- `support_24_7` 'true' | 'false'
- `certification` 'iso_27001' | 'soc2' | 'ewdci' | 'iwf'
- `sort` 'rank' | 'score' | 'price' | 'pool' | 'countries' | 'name' | 'updated'
- `order` 'asc' | 'desc'
- `limit` integer
- `offset` integer

## Response `200`

Matching providers.

- ProviderSearchResult
  - `total` integer, required: Providers matching the filters (before limit/offset).
  - `limit` integer, required
  - `offset` integer, required
  - `filters` object, required: The filters as applied, with defaults filled in (listing_status, sort and order are always present; order is null for sort=rank).
    - `listing_status` string, required
    - `sort` string, required
    - `order` string, nullable, required
  - `warnings` string[], required: Hints about the query: ignored parameters, price comparisons across units, providers without product data.
  - `providers` ProviderListItem[], required
    - `slug` string, required: Stable identifier used in every URL and API call.
    - `name` string, required: Brand name.
    - `website` string, uri, required: Provider's own website.
    - `listing_status` 'active' | 'pre-launch' | 'defunct' | 'suspended' | 'unverifiable', required: active: selling now. pre-launch: announced, not selling yet. defunct: shut down. suspended: delisted by staff. unverifiable: claims could not be verified.
    - `notice` string, nullable, required: Short editorial label shown next to the name, e.g. "Pre-launch".
    - `aliases` string[], required: Other names the provider trades or is known under.
    - `legal_entity` string, nullable, required: Company behind the service, as stated in its terms or imprint.
    - `parent_company` string, nullable, required: Owning group or company when it is not the operator itself (e.g. Webshare → "Oxylabs"). null when none or unknown.
    - `related_brands` string[], required: Sister or white-label brands run by the same operator (names; some are providers in this database).
    - `founded` string, nullable, required: Founding year (or date) as claimed.
    - `hq_country` string, nullable, required: Headquarters country (ISO 3166-1 alpha-2 when known).
    - `hq_city` string, nullable, required: Headquarters city.
    - `hq` string, nullable, required: Headquarters in words, e.g. "Manchester, United Kingdom".
    - `types` string[], required: Proxy types sold.
    - `protocols` string[], required: Proxy protocols supported across products.
    - `best_for` string, nullable, required: One-line editorial summary of what the provider suits.
    - `highlights` string[], required: Editorial strengths.
    - `considerations` string[], required: Editorial caveats ("good to know").
    - `price_from` string, nullable, required: Cheapest advertised price in words, across products.
    - `pricing_notes` string, nullable, required: Free-text pricing notes (discounts, minimums, billing).
    - `purchasing` object[], required: Scoped purchase-condition reviews with their own sources and dates. Empty where not researched.
      - `provider` string, required: Provider slug.
      - `type` 'residential' | 'mobile' | 'datacenter' | 'isp', required
      - `scope` string, required: Exact products, pools and billing options reviewed; other products are outside scope.
      - `checkedAt` string, date, required: Date these purchase sources were checked, independent of the full provider record.
      - `reviewDueAt` string, date, required: Next source-review deadline.
      - `reviewDue` boolean, required: True if evidence is overdue or future-dated; confirm current terms.
      - `customQuoteFromGb` number, nullable, required: GB quantity at which this per-GB product requires a documented custom quote. Null means no boundary was recorded; it is not a promise of unlimited fixed-price availability. Respect the order increments stated in the review scope.
      - `facts` object[], required
        - `id` 'minimum' | 'renewal' | 'retention' | 'trial' | 'refund', required
        - `text` string, required: Scoped published condition or explicit uncertainty.
        - `status` 'documented' | 'unconfirmed' | 'conflicting', required
        - `sources` string[], required: Source IDs in this purchasing profile.
      - `sources` object[], required
        - `id` string, required: Source ID.
        - `label` string, required: Reference label.
        - `url` string, uri, required: Primary reference URL.
    - `operations` object[], required: Scoped operational findings with per-answer evidence status, sources and dates. Empty where no public source was retrievable.
      - `provider` string, required: Provider slug.
      - `type` 'residential' | 'mobile' | 'datacenter' | 'isp', required
      - `scope` string, required: Product, plan, account and per-IP qualifications; supplier publications, not measured performance.
      - `checkedAt` string, date, required: Date these operational sources were checked, independent of the full provider record.
      - `reviewDueAt` string, date, required: Next source-review deadline.
      - `reviewDue` boolean, required: True if this bounded source review is overdue or future-dated.
      - `facts` object[], required
        - `id` 'concurrency' | 'session_duration' | 'traffic_expiry' | 'country_list' | 'price_ladder', required
        - `text` string, required: Scoped operational finding or explicit uncertainty.
        - `status` 'documented' | 'unconfirmed' | 'conflicting', required
        - `sources` string[], required: Source IDs in this operational profile.
      - `sources` object[], required
        - `id` string, required: Source ID.
        - `label` string, required: Reference label.
        - `url` string, uri, required: Primary reference URL.
    - `pool_size_text` string, nullable, required: Advertised pool size in words, across products (see products[].pool_size for numbers).
    - `locations` string, nullable, required: Advertised locations in words, across products (see products[].countries for numbers).
    - `targeting_text` string, nullable, required: Geo-targeting options in words (see products[].targeting for the structured list).
    - `payment_text` string, nullable, required: Payment options in words (see payment_methods for the structured list).
    - `products` ProviderProduct[], required: Structured per-type products, in residential, mobile, datacenter, isp order. Empty while research has not structured this provider yet.
      - `type` 'residential' | 'mobile' | 'datacenter' | 'isp', required: Proxy type this product row describes. One row per type.
      - `pricing_model` 'per_gb' | 'per_ip' | 'per_port' | 'per_request' | 'unlimited' | 'other', required: How the product is billed: per GB of traffic, per IP, per port, per request, unlimited traffic (billed by time/threads) or other.
      - `price_from_usd` number, nullable, required: Lowest advertised price in USD per price_unit (usually the largest plan or with volume discounts). null when not published.
      - `price_unit` string, required: Unit of price_from_usd, e.g. "GB", "IP/month", "port/month", "1k requests". Empty when unknown.
      - `price_from_text` string, required: Starting price as advertised, in words (e.g. "$0.49/GB at 1 TB"). Empty when not published.
      - `entry_price_usd` number, nullable, required: Smallest purchase in USD (cheapest plan or top-up). null when unknown.
      - `pool_size` integer, nullable, required: Advertised number of IPs in the pool (as claimed by the provider). null when not published.
      - `pool_size_text` string, required: Pool size as advertised, in words (e.g. "150M+ IPs"). Empty when not published.
      - `countries` integer, nullable, required: Number of countries with IPs for this type. null when not published.
      - `targeting` string[], required: Geo/network targeting options for this type.
      - `protocols` string[], required: Proxy protocols supported for this type.
      - `sticky_sessions` string, required: Sticky/rotating session options as advertised (e.g. "up to 24h"). Empty when unknown.
      - `ipv6` boolean, nullable, required: Whether IPv6 addresses are offered for this type; null when unknown.
      - `price_tiers` PriceTier[], required: The full published price ladder in ascending quantity order (at most 64 tiers). Empty when not researched yet.
        - `kind` 'volume' | 'plan' | 'graduated', required: volume: buying at least `quantity` units costs `unit_price_usd` each. plan: a fixed package of `quantity` units for `total_usd`. graduated: one band of a marginal ladder; units from this band's `quantity` up to the next graduated band's (same billing_period, ip_version and shared) cost `unit_price_usd` each, the lowest band starts at 0 (its `quantity` is the smallest purchase), and `total_usd` on the lowest band is a minimum charge per billing period.
        - `quantity` number, required: Units, counted in the product's pricing unit: GB (per_gb), IPs (per_ip), ports (per_port), thousands of requests (per_request), ports or plans (unlimited).
        - `unit_price_usd` number, nullable, required: Price per unit in USD for the billing period (required for volume and graduated tiers; null when a plan does not state one).
        - `total_usd` number, nullable, required: Price of the whole tier in USD for the billing period (required for plans). On the lowest graduated band: the minimum charge per period.
        - `billing_period` 'one_time' | 'day' | 'week' | 'month' | 'quarter' | 'year', required: one_time (pay as you go, a top-up or a pack that does not renew), day, week, month, quarter or year. Prices are for this period, not converted.
        - `note` string, required: Promotions, conditions or what the plan includes, as published. Empty when none.
        - `once` boolean, required: true for a trial, intro or new-user offer that can be bought only once. Such tiers are shown but never used in price quotes or in the derived price_from_usd and entry_price_usd.
        - `ip_version` 'ipv4' | 'ipv6' | 'null', nullable, required: IP version the tier sells (ipv4 or ipv6); null when the ladder does not say. Quotes count null as IPv4.
        - `shared` boolean, nullable, required: true: shared IPs; false: dedicated (private) IPs; null when the ladder does not say.
      - `country_codes` string[], nullable, required: ISO 3166-1 alpha-2 codes (upper case, sorted) of the published location list. null when the provider only gives a count ("195+ countries") or no list.
      - `rotation` string[], required: Rotation modes: per_request, timed (every N minutes), sticky (keep an IP for a session), static (fixed IP). Empty when unknown.
      - `max_session_minutes` integer, nullable, required: Longest sticky session offered, in minutes (24 h = 1440). null for static IPs or when not stated.
      - `max_concurrency` integer, nullable, required: Published cap on concurrent connections or threads. null when none is published.
      - `unlimited_concurrency` boolean, nullable, required: The provider says concurrency is unlimited; null when unknown.
      - `unlimited_bandwidth` boolean, nullable, required: Traffic is not metered (typical for per-IP and per-port products); false for per-GB products; null when unknown.
      - `traffic_never_expires` boolean, nullable, required: Per-GB products: purchased traffic never expires; null when unknown.
      - `traffic_expiry_days` integer, nullable, required: Per-GB products: days until purchased traffic expires, when it does. null when unknown or it never expires.
    - `free_trial` boolean, nullable, required: Whether a free trial is offered; null when unknown.
    - `trial` string, nullable, required: Trial terms as advertised.
    - `refund_days` integer, nullable, required: Refund window in days; null when unknown or none published.
    - `kyc` 'none' | 'conditional' | 'required' | 'unknown', required: Identity verification: none, conditional (for some products/targets or above a spend), required, or unknown.
    - `kyc_text` string, nullable, required: KYC details.
    - `payment_methods` string[], required: Accepted payment methods.
    - `api_access` boolean, nullable, required: Whether a self-service API (e.g. for sub-users or IP lists) is offered; null when unknown.
    - `auth_methods` string[], required: How proxy connections authenticate: user_pass, ip_whitelist, api_token. Empty when unknown.
    - `support_channels` string[], required: Support channels offered. Empty when unknown.
    - `support_24_7` boolean, nullable, required: The provider claims 24/7 support; null when unknown.
    - `certifications` string[], required: Certifications and memberships with evidence on the provider's or the certifying body's site: iso_27001, soc2, ewdci (Ethical Web Data Collection Initiative), iwf (Internet Watch Foundation). Empty when none found.
    - `extra_products` string[], required: Other products (scraper APIs, unblockers, datasets, browsers…).
    - `ip_sourcing` string, nullable, required: How the provider says it sources residential/mobile IPs (as claimed, not verified).
    - `ip_sourcing_methods` string[], required: IP sourcing methods as claimed: sdk (partner-app SDK), bandwidth_app (users share bandwidth in the provider's app), own_hardware, isp_partnership, datacenter, reseller, unknown. Empty when not researched.
    - `red_flags` string, nullable, required: Problems found during research (ethics, sourcing, billing, reliability). null when none.
    - `trustpilot` object, nullable, required: The provider's Trustpilot profile as shown when checked (a review-site signal, not our rating).
      - `rating` number, nullable, required: TrustScore from 0 to 5; null when Trustpilot shows none.
      - `reviews` integer, nullable, required: Number of reviews; null when unknown.
      - `url` string, uri, required: The Trustpilot profile.
      - `notice` string, nullable, required: Any Trustpilot warning shown on the profile (e.g. fake reviews removed); null when none.
    - `featured` boolean, required: Featured by staff (sorted first in rank order).
    - `community` object, required: Votes and replies on the provider's directory thread.
      - `score` integer, required: Community vote score (up minus down).
      - `up_votes` integer, required: Up votes.
      - `down_votes` integer, required: Down votes.
      - `replies` integer, required: Replies in the provider's directory thread.
    - `live` ProviderLive, required: Live status snapshot at response time (see /api/v1/status for the current value).
      - `status` 'operational' | 'degraded' | 'down' | 'unknown', required: Aggregated status over the last 60 minutes of agent reports; "unknown" when too few independent agents reported.
      - `reporters` integer, required: Independent reporters (one per agent and network) in the window.
      - `verified_reporters` integer, required: How many of those reporters are verified agents (weighted 3x).
      - `last_report_at` string, date-time, nullable, required: Newest counted report.
      - `success_rate` number, nullable, required: Mean reported success rate in percent; null while the status is unknown.
      - `latency_ms` integer, nullable, required: Median reported latency in milliseconds; null while the status is unknown.
      - `top_issue` 'none' | 'timeouts' | 'connection_errors' | 'auth_errors' | 'blocked' | 'captcha' | 'slow' | 'geo_mismatch' | 'ip_leak' | 'pool_exhausted' | 'dashboard' | 'billing' | 'other' | 'null', nullable, required: Most reported problem, if any.
      - `open_incidents` integer, required: Open incidents opened by staff or verified agents.
    - `provenance` object, required: Where the facts come from and how fresh they are.
      - `sources` string[], required: Pages the facts were taken from (usually the provider’s own pricing and docs pages).
      - `confidence` 'high' | 'medium' | 'low', required: How well the facts are sourced.
      - `checked_at` string, date, nullable, required: Date the facts were last checked against the sources.
      - `data_version` integer, required: Research release the record was last loaded from.
      - `updated_at` string, date-time, required: When the record last changed in the database.
    - `links` object, required: Direct links to the provider's own pages (null when not found). Our links are in `urls`.
      - `pricing` string, uri, nullable, required: The provider's pricing page.
      - `docs` string, uri, nullable, required: The provider's API or documentation home.
      - `status_page` string, uri, nullable, required: The provider's own status page.
    - `urls` object, required: Canonical links for this provider.
      - `page` string, uri, required: Human page (the directory thread).
      - `markdown` string, uri, required: This record as Markdown.
      - `api` string, uri, required: Full API detail (history, reports, incidents, changes).
      - `visit` string, uri, required: Outbound link to the provider's website (may be an affiliate link, see /disclosure).
    - `url` string, uri, required: Provider's directory thread.
    - `status` 'operational' | 'degraded' | 'down' | 'unknown', required: Aggregated status over the last 60 minutes; "unknown" when nobody reported.
    - `reporters` integer, required
    - `last_report_at` string, date-time, nullable, required
    - `success_rate` number, nullable, required
    - `latency_ms` integer, nullable, required
    - `top_issue` 'none' | 'timeouts' | 'connection_errors' | 'auth_errors' | 'blocked' | 'captcha' | 'slow' | 'geo_mismatch' | 'ip_leak' | 'pool_exhausted' | 'dashboard' | 'billing' | 'other', required
    - `open_incidents` integer, required
    - `score` integer, required: Community vote score (up minus down).
    - `up_votes` integer, required
    - `down_votes` integer, required
    - `reply_count` integer, required

## Other responses

- `400`: Invalid input (invalid_field, invalid_parameter, invalid_json…).

---

[API](https://skmtc.dev/workingproxysites/apis/working-proxy-sites-api.md) · [All operations](https://skmtc.dev/workingproxysites/apis/working-proxy-sites-api/llms.txt) · [OpenAPI document](https://skmtc.dev/workingproxysites/apis/working-proxy-sites-api/revisions/569b34abb022?raw)