IPMusk Residential API
The Residential API from IPMusk — 3 operation(s) for residential.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/ipmusk-com:ipmusk-com-residential-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: IPMusk Customer Residential API
version: 1.0.0
description: 'Read the catalogue, get residential and static proxy credentials, check usage and orders, and handle support tickets. Authenticate with an API key from the dashboard (Settings > API keys) sent as `Authorization: Bearer `; each key carries the scopes read, connect and/or support. Rate limits per key and minute: read 60, connect 20, support 30 (429 rate_limited, with a Retry-After header in seconds). JSON responses are `{ data, request_id }`; errors are `{ error: { code, message, field_errors? }, request_id }`. Money is amount_minor (minor units) with an ISO 4217 currency.'
servers:
- url: https://ipmusk.com
tags:
- name: Residential
paths:
/api/v1/residential/credentials:
get:
operationId: residential_credentials_get
summary: Residential gateway credentials
description: 'Gateway host and port, the proxy username and password, and the traffic left. Returns a password: call it only when the user wants to connect. 404 not_found when there is no usable residential traffic (never bought, still being delivered, used up, expired or disabled); the message says which.'
security:
- bearerAuth: []
x-ipmusk-scope: connect
parameters: []
responses:
'200':
description: Residential gateway credentials
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
gateway:
type: object
properties:
host:
type: string
port:
type: integer
minimum: 1
maximum: 65535
required:
- host
- port
additionalProperties: false
account:
type: string
username:
type: string
password:
type: string
traffic:
type: object
properties:
active_packages:
type: integer
minimum: 0
maximum: 9007199254740991
remaining_bytes:
type: integer
minimum: 0
maximum: 9007199254740991
total_bytes:
anyOf:
- type: integer
minimum: 0
maximum: 9007199254740991
- type: 'null'
earliest_expiry:
anyOf:
- type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
- type: 'null'
required:
- active_packages
- remaining_bytes
- total_bytes
- earliest_expiry
additionalProperties: false
pending_delivery:
type: boolean
countries:
type: array
items:
type: string
pattern: ^[A-Z]{2}$
required:
- gateway
- account
- username
- password
- traffic
- pending_delivery
- countries
additionalProperties: false
request_id:
type: string
minLength: 8
maxLength: 128
required:
- data
- request_id
additionalProperties: false
default:
$ref: '#/components/responses/Error'
tags:
- Residential
/api/v1/residential/proxy-url:
post:
operationId: residential_proxy_url_create
summary: Build ready-to-use residential proxy URLs
description: 'protocol://username:password@host:port URLs targeting a country, optionally a state and a city (a city needs its state). sticky keeps one exit IP for sticky_minutes (1, 3, 10 or 30; default 10) and each of the count URLs gets its own session, so its own IP. rotating changes IP on every request, so every URL would be identical: rotating returns exactly one item whatever count says. A misspelt state is not caught here; the connection then fails. 404 not_found when there is no usable residential traffic.'
security:
- bearerAuth: []
x-ipmusk-scope: connect
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
country:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 exit country, e.g. US.
state:
description: State or region of the country, in English, e.g. "California".
type: string
minLength: 1
maxLength: 80
pattern: ^[A-Za-z0-9 '’-]+$
city:
description: City under the state, in English. Needs state.
type: string
minLength: 1
maxLength: 80
pattern: ^[A-Za-z0-9 '’-]+$
session:
type: string
enum:
- rotating
- sticky
description: 'rotating: new exit IP per request. sticky: one IP for sticky_minutes.'
sticky_minutes:
description: How long a sticky session keeps its IP. Default 10. Sticky only.
anyOf:
- type: number
const: 1
- type: number
const: 3
- type: number
const: 10
- type: number
const: 30
protocol:
default: http
type: string
enum:
- http
- socks5
count:
default: 1
description: How many sticky URLs, each its own IP. Rotating always returns one.
type: integer
minimum: 1
maximum: 100
required:
- country
- session
additionalProperties: false
responses:
'200':
description: Build ready-to-use residential proxy URLs
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
protocol:
type: string
enum:
- http
- socks5
session:
type: string
enum:
- rotating
- sticky
sticky_minutes:
anyOf:
- anyOf:
- type: number
const: 1
- type: number
const: 3
- type: number
const: 10
- type: number
const: 30
- type: 'null'
items:
minItems: 1
maxItems: 100
type: array
items:
type: object
properties:
url:
type: string
host:
type: string
port:
type: integer
minimum: 1
maximum: 65535
username:
type: string
password:
type: string
required:
- url
- host
- port
- username
- password
additionalProperties: false
required:
- protocol
- session
- sticky_minutes
- items
additionalProperties: false
request_id:
type: string
minLength: 8
maxLength: 128
required:
- data
- request_id
additionalProperties: false
default:
$ref: '#/components/responses/Error'
tags:
- Residential
/api/v1/residential/usage:
get:
operationId: residential_usage_get
summary: Residential traffic usage
description: Daily usage for the last 7 or 30 days (default 30), the active packages, a 7-day daily average and when the traffic is projected to run out. Figures are as of the last sync (packages.syncedAt). Keys are camelCase.
security:
- bearerAuth: []
x-ipmusk-scope: read
parameters:
- name: days
in: query
required: false
description: Range in days. Default 30.
schema:
description: Range in days. Default 30.
type: string
enum:
- '7'
- '30'
responses:
'200':
description: Residential traffic usage
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
rangeDays:
anyOf:
- type: number
const: 7
- type: number
const: 30
startDate:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
endDate:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
series:
type: array
items:
type: object
properties:
date:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
bytes:
type: integer
minimum: 0
maximum: 9007199254740991
updating:
type: boolean
recorded:
type: boolean
required:
- date
- bytes
- updating
- recorded
additionalProperties: false
rangeTotalBytes:
type: integer
minimum: 0
maximum: 9007199254740991
lastUpdatedAt:
anyOf:
- type: string
- type: 'null'
packages:
anyOf:
- type: object
properties:
packageCount:
type: integer
minimum: 0
maximum: 9007199254740991
totalBytes:
anyOf:
- type: integer
minimum: 0
maximum: 9007199254740991
- type: 'null'
usedBytes:
anyOf:
- type: integer
minimum: 0
maximum: 9007199254740991
- type: 'null'
remainingBytes:
type: integer
minimum: 0
maximum: 9007199254740991
remainingPercent:
anyOf:
- type: number
minimum: 0
maximum: 100
- type: 'null'
earliestExpiry:
anyOf:
- type: string
- type: 'null'
syncedAt:
anyOf:
- type: string
- type: 'null'
required:
- packageCount
- totalBytes
- usedBytes
- remainingBytes
- remainingPercent
- earliestExpiry
- syncedAt
additionalProperties: false
- type: 'null'
dailyAverageBytes:
anyOf:
- type: integer
minimum: 0
maximum: 9007199254740991
- type: 'null'
averageDays:
type: integer
minimum: 0
maximum: 7
projection:
anyOf:
- oneOf:
- type: object
properties:
kind:
type: string
const: runs_out
date:
type: string
required:
- kind
- date
additionalProperties: false
- type: object
properties:
kind:
type: string
const: left_at_expiry
bytes:
type: integer
minimum: 0
maximum: 9007199254740991
date:
type: string
required:
- kind
- bytes
- date
additionalProperties: false
- type: 'null'
required:
- rangeDays
- startDate
- endDate
- series
- rangeTotalBytes
- lastUpdatedAt
- packages
- dailyAverageBytes
- averageDays
- projection
additionalProperties: false
request_id:
type: string
minLength: 8
maxLength: 128
required:
- data
- request_id
additionalProperties: false
default:
$ref: '#/components/responses/Error'
tags:
- Residential
components:
responses:
Error:
description: 'Any failure: 400 validation_error, 401 authentication_required, 403 forbidden / capability_unavailable, 404 not_found, 409 invalid_state_transition / idempotency_conflict, 422 product_unavailable, 429 rate_limited, 500 internal_error.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
schemas:
ErrorEnvelope:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- validation_error
- authentication_required
- region_blocked
- forbidden
- not_found
- idempotency_conflict
- invalid_state_transition
- checkout_unavailable
- product_unavailable
- capability_unavailable
- rate_limited
- challenge_required
- upstream_unavailable
- internal_error
message:
type: string
minLength: 1
maxLength: 500
field_errors:
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
minLength: 1
maxLength: 300
required:
- code
- message
additionalProperties: false
request_id:
type: string
minLength: 8
maxLength: 128
required:
- error
- request_id
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: An IPMusk API key (ipm_live_…).