API

API reference

Manage organizations, proxy credentials, and usage over HTTP.

https://masklabs.io/api/v1OpenAPI document (JSON)

Overview

The API covers organizations, proxy credentials, and usage. Proxy traffic does not go through it; see the quickstart for connecting to the proxy.

Base URL: https://masklabs.io/api/v1. The full contract is available as an OpenAPI document for client generators.

Quick start

Create a key under API keys on your Account page. It is shown once.
List your organizations. Each has an id used in the other endpoints.

curl "https://masklabs.io/api/v1/organizations" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Authentication

Send the key in the Authorization header: Authorization: Bearer masklabs_…. Keys are created and revoked on the Account page.

A key has the access of the user who created it: every organization that user belongs to, with that user's role in each. Owners and admins can delete credentials and rotate passwords; members can create, rename, limit, enable, and disable them. If the user is removed from an organization, their keys lose access to it. See Organizations, users, and credentials.

A key can be limited to one organization when it is created. Requests for other organizations return 403 forbidden.

Conventions

Data is in bytes. 1 GB = 1,000,000,000 bytes.
Timestamps are ISO-8601 in UTC. Usage is grouped by UTC date, written YYYY-MM-DD.
Usage endpoints take from and to dates. The default range is the last 30 days and the maximum is 366. from is moved forward to the creation date when the range starts earlier, so a series never includes days before the organization or credential existed. The current day is incomplete until it ends; as_of is when the usage data was last updated.
The sum of per-credential usage can differ slightly from the organization total. Billing is based on the organization total.
Rate limit: 600 requests per minute per key. Responses include X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit, requests return 429 with Retry-After in seconds.
Responses are sent with Cache-Control: no-store.
A credential's password is returned only by the create and rotate endpoints. It cannot be read later.

Errors

Errors return an error object with a code and a message. Validation errors also include details with one entry per failed field.

400 Bad Request

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request.",
    "details": [
      {
        "path": "daily_limit_bytes",
        "message": "Caps are whole bytes."
      }
    ]
  }
}

Code	Meaning
bad_request	The request is malformed or not allowed in the current state.
validation_error	A field failed validation. `details` lists each one.
unauthorized	Missing, invalid, expired, or disabled API key.
forbidden	The key is limited to another organization, the account is suspended, or the action requires an owner or admin.
not_found	The organization or credential does not exist or is not accessible with this key.
method_not_allowed	The path exists but does not support this method. `Allow` lists the methods that do.
conflict	The request conflicts with the current state.
credential_limit_reached	The organization holds as many credentials as its limit allows. Delete one, or contact support to raise the limit.
rate_limited	Rate limit exceeded. `Retry-After` gives the wait in seconds.
internal_error	Server error.

Organizations

Organizations the key can access, with plan, cycle, and remaining data.

GET/organizationsList organizations
GET/organizations/{orgId}Get an organization

GET/organizations

List organizations

A key limited to one organization returns only that one.

Response

200

organizationsOrganizationSummary[]
- idstring
  Organization id, used in paths.
- namestring
- slugstring
- rolestring
  owner, admin, or member.
- created_atstring (date-time)

Errors

401Missing, invalid, expired, or disabled API key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "organizations": [
    {
      "id": "oZK4Ku1vQ9Y2Hc7tXbLm3nWd",
      "name": "Example Organization",
      "slug": "example-organization",
      "role": "owner",
      "created_at": "2026-03-02T15:21:44.000Z"
    },
    {
      "id": "pR7sTw2xY8zA4bCd6eFg1hJk",
      "name": "Second Organization",
      "slug": "second-organization",
      "role": "member",
      "created_at": "2026-05-19T10:02:08.000Z"
    }
  ]
}

GET/organizations/{orgId}

Get an organization

Plan, current cycle, and remaining data.

Path parameters

orgIdstringrequired
Organization id.

Response

200 · Organization

idstring
Organization id, used in paths.
namestring
slugstring
rolestring
owner, admin, or member.
created_atstring (date-time)
planobject | null
Null if the organization has no plan.
- slugstring
  Plan identifier.
- namestring | null
- included_bytesinteger | null
  Data included per cycle.
entitledboolean
Whether the plan is active and paid through the current period. Credentials only pass traffic while this is true.
cancel_at_period_endboolean
Whether the plan ends at cycle.end_at instead of renewing.
cycleobject
- start_atstring (date-time) | null
- end_atstring (date-time) | null
  End of the current period.
- allowance_bytesinteger
  Plan data plus added data for this cycle.
- used_bytesinteger
  Bytes used this cycle.
- remaining_bytesinteger
  Bytes remaining, including non-expiring credit.
- cycle_remaining_bytesinteger
  Remaining bytes that expire at the end of the cycle.
- credit_remaining_bytesinteger
  Remaining non-expiring credit.
credentialsobject
- countinteger
- limitinteger
  Maximum credentials per organization.

Errors

401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "id": "oZK4Ku1vQ9Y2Hc7tXbLm3nWd",
  "name": "Example Organization",
  "slug": "example-organization",
  "role": "owner",
  "created_at": "2026-03-02T15:21:44.000Z",
  "plan": {
    "slug": "advanced",
    "name": "Advanced",
    "included_bytes": 125000000000
  },
  "entitled": true,
  "cancel_at_period_end": false,
  "cycle": {
    "start_at": "2026-09-01T00:00:00.000Z",
    "end_at": "2026-10-01T00:00:00.000Z",
    "allowance_bytes": 145000000000,
    "used_bytes": 61904337210,
    "remaining_bytes": 83095662790,
    "cycle_remaining_bytes": 83095662790,
    "credit_remaining_bytes": 0
  },
  "credentials": {
    "count": 4,
    "limit": 50
  }
}

Credentials

Proxy credentials. Members can create, rename, limit, enable, and disable them. Daily and monthly limits refill on the UTC calendar; a lifetime limit never refills, so a credential stops for good once it is reached. Deleting and rotating passwords require an owner or admin.

GET/organizations/{orgId}/credentialsList credentials
POST/organizations/{orgId}/credentialsCreate a credential
GET/organizations/{orgId}/credentials/{credentialId}Get a credential
PATCH/organizations/{orgId}/credentials/{credentialId}Update a credential
DELETE/organizations/{orgId}/credentials/{credentialId}Delete a credential
POST/organizations/{orgId}/credentials/{credentialId}/rotate-passwordRotate the password

GET/organizations/{orgId}/credentials

List credentials

Path parameters

orgIdstringrequired
Organization id.

Response

200

credentialsCredential[]
- idstring (uuid)
- usernamestring
  Proxy username. Add _loc_CODE or _sticky suffixes when connecting.
- labelstring | null
- statusenum
  active: passing traffic. suspended: paused because the organization has no data or no active plan. disabled: turned off.
  activesuspendeddisabled
- enabledboolean
  Whether the credential is passing traffic.
- lifetime_used_bytesinteger
  Total bytes used since creation.
- daily_limit_bytesinteger | null
  Daily limit in bytes, or null.
- monthly_limit_bytesinteger | null
  Monthly limit in bytes, or null.
- lifetime_limit_bytesinteger | null
  Total lifetime limit in bytes, or null.
- lifetime_remaining_bytesinteger | null
  Bytes left on the lifetime limit, or null when there is none. 0 means the credential is exhausted and will not pass traffic again until the limit is raised.
- created_atstring (date-time)

Errors

401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "credentials": [
    {
      "id": "2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30",
      "username": "mlabs_4f1c9be2a7",
      "label": "example-credential",
      "status": "active",
      "enabled": true,
      "lifetime_used_bytes": 41283990112,
      "daily_limit_bytes": 5000000000,
      "monthly_limit_bytes": null,
      "lifetime_limit_bytes": null,
      "lifetime_remaining_bytes": null,
      "created_at": "2026-06-14T09:12:03.000Z"
    },
    {
      "id": "9b1e6d24-3c7a-4f58-b2e1-0d6f4a8c2e17",
      "username": "mlabs_c07d21e9b4",
      "label": "second-credential",
      "status": "active",
      "enabled": true,
      "lifetime_used_bytes": 22510004871,
      "daily_limit_bytes": null,
      "monthly_limit_bytes": 100000000000,
      "lifetime_limit_bytes": null,
      "lifetime_remaining_bytes": null,
      "created_at": "2026-07-22T18:30:56.000Z"
    }
  ]
}

POST/organizations/{orgId}/credentials

Create a credential

The password is returned only in this response. Requires an active plan. Each organization has a credential limit.

Path parameters

orgIdstringrequired
Organization id.

Request body

optional

labelstring | nulloptional
Up to 60 characters. Null clears it.
daily_limit_bytesinteger | nulloptional
Daily limit in bytes. Omit or null for none.
monthly_limit_bytesinteger | nulloptional
Monthly limit in bytes. Omit or null for none.
lifetime_limit_bytesinteger | nulloptional
Total bytes the credential may ever use, never refilled. Omit or null for none.

Response

201 · CredentialCreated

credentialCredential
- idstring (uuid)
- usernamestring
  Proxy username. Add _loc_CODE or _sticky suffixes when connecting.
- labelstring | null
- statusenum
  active: passing traffic. suspended: paused because the organization has no data or no active plan. disabled: turned off.
  activesuspendeddisabled
- enabledboolean
  Whether the credential is passing traffic.
- lifetime_used_bytesinteger
  Total bytes used since creation.
- daily_limit_bytesinteger | null
  Daily limit in bytes, or null.
- monthly_limit_bytesinteger | null
  Monthly limit in bytes, or null.
- lifetime_limit_bytesinteger | null
  Total lifetime limit in bytes, or null.
- lifetime_remaining_bytesinteger | null
  Bytes left on the lifetime limit, or null when there is none. 0 means the credential is exhausted and will not pass traffic again until the limit is raised.
- created_atstring (date-time)
passwordstring
Returned only in this response.

Errors

400Invalid body or no active plan.
401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
409Credential limit reached (credential_limit_reached).
429Rate limit exceeded. See Retry-After.

curl -X POST "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials" \
  -H "Authorization: Bearer $MASKLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"example-credential","daily_limit_bytes":5000000000,"lifetime_limit_bytes":50000000000}'

Response · 201

{
  "credential": {
    "id": "2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30",
    "username": "mlabs_4f1c9be2a7",
    "label": "example-credential",
    "status": "active",
    "enabled": true,
    "lifetime_used_bytes": 0,
    "daily_limit_bytes": 5000000000,
    "monthly_limit_bytes": null,
    "lifetime_limit_bytes": 50000000000,
    "lifetime_remaining_bytes": 50000000000,
    "created_at": "2026-06-14T09:12:03.000Z"
  },
  "password": "Vq7mP2xR9kL4nW8sT1yB6zC3"
}

GET/organizations/{orgId}/credentials/{credentialId}

Get a credential

Path parameters

orgIdstringrequired
Organization id.
credentialIdstring (uuid)required
Credential id.

Response

200 · Credential

idstring (uuid)
usernamestring
Proxy username. Add _loc_CODE or _sticky suffixes when connecting.
labelstring | null
statusenum
active: passing traffic. suspended: paused because the organization has no data or no active plan. disabled: turned off.
activesuspendeddisabled
enabledboolean
Whether the credential is passing traffic.
lifetime_used_bytesinteger
Total bytes used since creation.
daily_limit_bytesinteger | null
Daily limit in bytes, or null.
monthly_limit_bytesinteger | null
Monthly limit in bytes, or null.
lifetime_limit_bytesinteger | null
Total lifetime limit in bytes, or null.
lifetime_remaining_bytesinteger | null
Bytes left on the lifetime limit, or null when there is none. 0 means the credential is exhausted and will not pass traffic again until the limit is raised.
created_atstring (date-time)

Errors

401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials/2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "id": "2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30",
  "username": "mlabs_4f1c9be2a7",
  "label": "example-credential",
  "status": "active",
  "enabled": true,
  "lifetime_used_bytes": 41283990112,
  "daily_limit_bytes": 5000000000,
  "monthly_limit_bytes": null,
  "lifetime_limit_bytes": null,
  "lifetime_remaining_bytes": null,
  "created_at": "2026-06-14T09:12:03.000Z"
}

PATCH/organizations/{orgId}/credentials/{credentialId}

Update a credential

Only the fields sent are changed. Set a limit to null to remove it. Raising a lifetime limit grants that much more data; removing one also clears the amount counted against it, so setting a new one starts from zero. Enabling requires the organization to have data remaining.

Path parameters

orgIdstringrequired
Organization id.
credentialIdstring (uuid)required
Credential id.

Request body

required

labelstring | nulloptional
Up to 60 characters. Null clears it.
enabledbooleanoptional
Enable or disable the credential. Enabling requires the organization to have data remaining.
daily_limit_bytesinteger | nulloptional
Daily limit in bytes. Null removes it.
monthly_limit_bytesinteger | nulloptional
Monthly limit in bytes. Null removes it.
lifetime_limit_bytesinteger | nulloptional
Total bytes the credential may ever use, never refilled. Raising it grants that much more traffic; lowering it below what is already spent stops the credential. Null removes it, which also resets the spend counted against a future lifetime limit.

Response

200 · Credential

idstring (uuid)
usernamestring
Proxy username. Add _loc_CODE or _sticky suffixes when connecting.
labelstring | null
statusenum
active: passing traffic. suspended: paused because the organization has no data or no active plan. disabled: turned off.
activesuspendeddisabled
enabledboolean
Whether the credential is passing traffic.
lifetime_used_bytesinteger
Total bytes used since creation.
daily_limit_bytesinteger | null
Daily limit in bytes, or null.
monthly_limit_bytesinteger | null
Monthly limit in bytes, or null.
lifetime_limit_bytesinteger | null
Total lifetime limit in bytes, or null.
lifetime_remaining_bytesinteger | null
Bytes left on the lifetime limit, or null when there is none. 0 means the credential is exhausted and will not pass traffic again until the limit is raised.
created_atstring (date-time)

Errors

400Invalid body.
401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl -X PATCH "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials/2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30" \
  -H "Authorization: Bearer $MASKLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false,"monthly_limit_bytes":50000000000}'

Response · 200

{
  "id": "2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30",
  "username": "mlabs_4f1c9be2a7",
  "label": "example-credential",
  "status": "disabled",
  "enabled": false,
  "lifetime_used_bytes": 41283990112,
  "daily_limit_bytes": 5000000000,
  "monthly_limit_bytes": 50000000000,
  "lifetime_limit_bytes": null,
  "lifetime_remaining_bytes": null,
  "created_at": "2026-06-14T09:12:03.000Z"
}

DELETE/organizations/{orgId}/credentials/{credentialId}

Delete a credential

Requires an owner or admin. Returns 204 even if the credential is already deleted.

Path parameters

orgIdstringrequired
Organization id.
credentialIdstring (uuid)required
Credential id.

Response

204

Deleted

Errors

401Missing, invalid, expired, or disabled API key.
403Requires an owner or admin, or the key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl -X DELETE "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials/2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 204, no body.

POST/organizations/{orgId}/credentials/{credentialId}/rotate-password

Rotate the password

Requires an owner or admin. The old password stops working immediately. The new one is returned only in this response.

Path parameters

orgIdstringrequired
Organization id.
credentialIdstring (uuid)required
Credential id.

Response

200 · PasswordRotated

passwordstring
The new password. Returned only in this response.

Errors

401Missing, invalid, expired, or disabled API key.
403Requires an owner or admin, or the key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl -X POST "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials/2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30/rotate-password" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "password": "Hd2kN7vB4qX9wM1cR6tL8yP5"
}

Usage

Bytes used per UTC date, per organization or per credential. Default range 30 days, maximum 366.

GET/organizations/{orgId}/usageGet organization usage by date
GET/organizations/{orgId}/usage/credentialsGet usage per credential
GET/organizations/{orgId}/credentials/{credentialId}/usageGet credential usage by date

GET/organizations/{orgId}/usage

Get organization usage by date

Usage for the whole organization, which billing is based on. Dates are UTC. from is moved forward to the creation date when the requested range starts earlier, so the series never includes days before the organization or credential existed. The current day is incomplete until the day ends; as_of is when the usage data was last updated.

Path parameters

orgIdstringrequired
Organization id.

Query parameters

fromstring (date)
First date, inclusive. Defaults to 29 days before to. The range can be at most 366 days.
tostring (date)
Last date, inclusive. Defaults to today (UTC).

Response

200 · OrganizationUsage

organization_idstring
fromstring (date)
First date, inclusive.
tostring (date)
Last date, inclusive.
as_ofstring (date-time) | null
When the usage data was last updated. Null if there is no usage yet.
total_bytesinteger
Total bytes in the range.
seriesUsagePoint[]
One entry per date. Dates with no usage have 0 bytes.
- datestring (date)
  UTC date.
- bytesinteger
  Bytes used on that date.

Errors

400Invalid date range.
401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/usage?from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "organization_id": "oZK4Ku1vQ9Y2Hc7tXbLm3nWd",
  "from": "2026-09-01",
  "to": "2026-09-07",
  "as_of": "2026-09-07T13:59:41.000Z",
  "total_bytes": 61904337210,
  "series": [
    {
      "date": "2026-09-01",
      "bytes": 9210442118
    },
    {
      "date": "2026-09-02",
      "bytes": 8884003920
    },
    {
      "date": "2026-09-03",
      "bytes": 9402118557
    },
    {
      "date": "2026-09-04",
      "bytes": 9115770002
    },
    {
      "date": "2026-09-05",
      "bytes": 8301994461
    },
    {
      "date": "2026-09-06",
      "bytes": 8997212006
    },
    {
      "date": "2026-09-07",
      "bytes": 7992796146
    }
  ]
}

GET/organizations/{orgId}/usage/credentials

Get usage per credential

Totals for each current credential over the range. The sum can differ slightly from the organization total; billing is based on the organization total. Dates are UTC. from is moved forward to the creation date when the requested range starts earlier, so the series never includes days before the organization or credential existed. The current day is incomplete until the day ends; as_of is when the usage data was last updated.

Path parameters

orgIdstringrequired
Organization id.

Query parameters

fromstring (date)
First date, inclusive. Defaults to 29 days before to. The range can be at most 366 days.
tostring (date)
Last date, inclusive. Defaults to today (UTC).

Response

200 · CredentialUsageBreakdown

organization_idstring
fromstring (date)
First date, inclusive.
tostring (date)
Last date, inclusive.
as_ofstring (date-time) | null
When the usage data was last updated. Null if there is no usage yet.
total_bytesinteger
Total bytes in the range.
credentialsobject[]
All current credentials, oldest first.
- credential_idstring (uuid)
- usernamestring
- labelstring | null
- bytesinteger
  Bytes used in the range.

Errors

400Invalid date range.
401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/usage/credentials?from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "organization_id": "oZK4Ku1vQ9Y2Hc7tXbLm3nWd",
  "from": "2026-09-01",
  "to": "2026-09-07",
  "as_of": "2026-09-07T13:59:41.000Z",
  "total_bytes": 61880120044,
  "credentials": [
    {
      "credential_id": "2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30",
      "username": "mlabs_4f1c9be2a7",
      "label": "example-credential",
      "bytes": 40113557902
    },
    {
      "credential_id": "9b1e6d24-3c7a-4f58-b2e1-0d6f4a8c2e17",
      "username": "mlabs_c07d21e9b4",
      "label": "second-credential",
      "bytes": 21766562142
    }
  ]
}

GET/organizations/{orgId}/credentials/{credentialId}/usage

Get credential usage by date

Dates are UTC. from is moved forward to the creation date when the requested range starts earlier, so the series never includes days before the organization or credential existed. The current day is incomplete until the day ends; as_of is when the usage data was last updated.

Path parameters

orgIdstringrequired
Organization id.
credentialIdstring (uuid)required
Credential id.

Query parameters

fromstring (date)
First date, inclusive. Defaults to 29 days before to. The range can be at most 366 days.
tostring (date)
Last date, inclusive. Defaults to today (UTC).

Response

200 · CredentialUsage

credential_idstring (uuid)
fromstring (date)
First date, inclusive.
tostring (date)
Last date, inclusive.
as_ofstring (date-time) | null
When the usage data was last updated. Null if there is no usage yet.
total_bytesinteger
Total bytes in the range.
seriesUsagePoint[]
One entry per date. Dates with no usage have 0 bytes.
- datestring (date)
  UTC date.
- bytesinteger
  Bytes used on that date.

Errors

400Invalid date range.
401Missing, invalid, expired, or disabled API key.
403The key is limited to another organization.
404Organization not found or not accessible with this key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/organizations/oZK4Ku1vQ9Y2Hc7tXbLm3nWd/credentials/2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30/usage?from=2026-09-05&to=2026-09-07" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "credential_id": "2f5d9c0a-6b3e-4a1f-9d7c-8e2b1a4c6f30",
  "from": "2026-09-05",
  "to": "2026-09-07",
  "as_of": "2026-09-07T13:59:41.000Z",
  "total_bytes": 16401552003,
  "series": [
    {
      "date": "2026-09-05",
      "bytes": 5511200118
    },
    {
      "date": "2026-09-06",
      "bytes": 5902001446
    },
    {
      "date": "2026-09-07",
      "bytes": 4988350439
    }
  ]
}

Proxy

Connection details: host, ports, and available locations.

GET/proxyGet connection details

GET/proxy

Get connection details

Response

200 · ProxyInfo

hoststring
Proxy hostname.
portsobject
- httpinteger
  HTTP port.
- httpsinteger
  HTTP proxy over TLS.
- socks5integer
  SOCKS5 port.
- http3integer
  UDP port of the HTTP/3 (MASQUE) endpoint.
http3Templatestring
URI template for CONNECT-UDP requests (RFC 9298).
locationsstring[]
Location codes with an available exit.

Errors

401Missing, invalid, expired, or disabled API key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/proxy" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "host": "proxy.masklabs.io",
  "ports": {
    "http": 8080,
    "https": 443,
    "socks5": 1080,
    "http3": 443
  },
  "http3Template": "https://proxy.masklabs.io/.well-known/masque/udp/{target_host}/{target_port}/",
  "locations": [
    "ATL",
    "DFW",
    "LAX",
    "NYC",
    "ORD",
    "SEA"
  ]
}

Identity

The key and its owner.

GET/meGet the current key and user

GET/me

Get the current key and user

Response

200 · Me

userobject
- idstring
- emailstring
- namestring | null
keyobject
- idstring
- namestring | null
- created_atstring (date-time)
- expires_atstring (date-time) | null
- restricted_to_organization_idstring | null
  Organization the key is limited to, or null.

Errors

401Missing, invalid, expired, or disabled API key.
429Rate limit exceeded. See Retry-After.

curl "https://masklabs.io/api/v1/me" \
  -H "Authorization: Bearer $MASKLABS_API_KEY"

Response · 200

{
  "user": {
    "id": "u_8kQm2pXv7YtR4wLn",
    "email": "[email protected]",
    "name": "Example User"
  },
  "key": {
    "id": "k_3nVb9cXz1LqW6tPy",
    "name": "example-key",
    "created_at": "2026-09-01T17:40:12.000Z",
    "expires_at": null,
    "restricted_to_organization_id": null
  }
}