# 批量搜索静态实例

只读批量精确 IP 搜索，与订单/分组/地区/状态取交集。完整 IPv4/IPv6 校验并去重，每次最多 500 个。无效、空集合、超限整批拒绝，不泄露其他账户匹配情况。

只读批量精确 IP 搜索，与订单/分组/地区/状态取交集。完整 IPv4/IPv6 校验并去重，每次最多 500 个。无效、空集合、超限整批拒绝，不泄露其他账户匹配情况。

所有示例为合成数据与占位凭据，仅展示结构；接口合同不代表目标环境已开放。

## 接口与认证

`POST /openapi/v1/static/instances/search`

使用 HTTPS 和账户 API 令牌。响应包含 Cache-Control: no-store 和 X-Request-Id。

## 请求参数

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| api_key | string | 是 | Query · 唯一非空 | 账户 API 令牌，在受控服务端保存；示例使用占位符。 |

### 请求示例 · application/json

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| ips | string | 是 | 最少项 1；最多项 10000 | 完整 IPv4/IPv6 数组，按地址校验去重后最多 500；原始输入最多 10000 项，空集合及无效地址拒绝。精确匹配存储的 IP 文本，支持 IPv4:port 与 IPv6:port，端口1–65535，带端口精确匹配；不带端口匹配所有端口。不接受片段、CIDR 或 zone。 |
| activatedFrom | string | 否 | RFC3339，含时区 | 开通时间下界，含边界，可仅填一端。 |
| activatedTo | string | 否 | RFC3339，含时区 | 开通时间上界，含边界，不得早于下界。 |
| orderNo | string | 否 | — | 平台订单号；查询筛选时精确匹配本人订单。 |
| groupId | integer \| null | 否 | 最小 0 | 筛选分组：省略或 null 为全部，0 为未分组，正整数为本人分组。 |
| countryCode | string | 否 | — | 国家三字码，例如 USA；使用国家目录返回值。 |
| cityCode | string | 否 | — | 城市编码，使用城市目录返回值。 |
| status | string | 否 | — | 实例状态精确筛选：provisioning、active、expired、cancelled 或 failed。 |
| page | integer | 否 | 默认 1；最小 1；最大 1000000 | 页码，从 1 开始，默认 1。 |
| pageSize | integer | 否 | 默认 20；最小 1；最大 1000 | 每页数量，默认 20；最大值见字段限制。 |

## 请求示例

```bash
curl --request POST \
  "https://api.zzhttp.com/openapi/v1/static/instances/search?api_key=${STATIC_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"ips":["203.0.113.10","2001:db8::1"],"orderNo":"STATIC-DEMO-001","groupId":0,"countryCode":"USA","cityCode":"NYC","status":"active","page":1,"pageSize":20}'
```

请求示例：

```json
{
  "ips": [
    "203.0.113.10",
    "2001:db8::1"
  ],
  "orderNo": "STATIC-DEMO-001",
  "groupId": 0,
  "countryCode": "USA",
  "cityCode": "NYC",
  "status": "active",
  "page": 1,
  "pageSize": 20
}
```

## 成功响应

响应不包含代理密码，凭据仅由专用接口返回。

HTTP 200 · 成功响应：成功

| 字段 | 类型 | 必填 | 默认值 / 限制 | 说明 |
| --- | --- | --- | --- | --- |
| code | integer | 是 | 固定 200 | 统一数字业务码：HTTP 与业务码成功均为 200；异步受理不代表交付完成。 |
| message | string | 是 | — | 服务端结果说明。 |
| requestId | string | 是 | — | 本次请求的追踪 ID，用于排障，不是业务幂等编号。 |
| data | object | 是 | — | 本接口业务数据。 |
| data.items | object | 是 | — | 结果或提交明细数组，具体字段见下级。 |
| data.items.instanceId | integer | 是 | 最小 1；格式 int64 | 实例 ID，属于当前账户；分组绑定此 ID。 |
| data.items.offerId | integer | 是 | 最小 1；格式 int64 | 当前可采购商品 ID，来自商品列表。 |
| data.items.status | string | 是 | 枚举 provisioning / active / expired / cancelled / failed | 当前状态；枚举见限制，按逐项结果确认终态。 |
| data.items.ip | string | 是 | — | 实例实际 IP 地址。 |
| data.items.port | integer | 是 | 最小 0；格式 int64 | 实例直连端口。 |
| data.items.protocols | string | 是 | — | 支持协议；实例列表为字符串数组，凭据响应为逗号分隔字符串。 |
| data.items.countryCode | string | 是 | — | 国家三字码，例如 USA；使用国家目录返回值。 |
| data.items.cityCode | string | 是 | — | 城市编码，使用城市目录返回值。 |
| data.items.ispType | integer | 是 | 最小 0；格式 int64 | IP 类型：1 标准静态住宅，2 原生静态住宅。 |
| data.items.expiresAt | string \| null | 是 | 格式 date-time | 实例到期时间，RFC3339；未知为 null。 |
| data.items.activatedAt | string \| null | 是 | 格式 date-time | 实例激活时间，RFC3339；未激活为 null。 |
| data.items.capabilities | object | 是 | — | 真实货源或实例能力；声明不替代提交时业务校验，缺失快照可为空对象。 |
| data.items.capabilities.purchase | object | 否 | — | 采购期限规则。 |
| data.items.capabilities.purchase.allowedDays | integer | 否 | — | 允许的期限天数集合；非空时优先采用该集合。 |
| data.items.capabilities.purchase.minDays | integer | 否 | 最小 0 | 无 allowedDays 集合时的最短期限。 |
| data.items.capabilities.purchase.maxDays | integer | 否 | 最小 0 | 最长期限，0 表示不设上限。 |
| data.items.capabilities.purchase.stepDays | integer | 否 | 最小 0 | 从最短期限起允许的增量天数。 |
| data.items.capabilities.renew | object | 否 | — | 续费期限规则。 |
| data.items.capabilities.renew.allowedDays | integer | 否 | — | 允许的期限天数集合；非空时优先采用该集合。 |
| data.items.capabilities.renew.minDays | integer | 否 | 最小 0 | 无 allowedDays 集合时的最短期限。 |
| data.items.capabilities.renew.maxDays | integer | 否 | 最小 0 | 最长期限，0 表示不设上限。 |
| data.items.capabilities.renew.stepDays | integer | 否 | 最小 0 | 从最短期限起允许的增量天数。 |
| data.items.capabilities.convertTrial | object | 否 | — | 试用转正式期限规则。 |
| data.items.capabilities.convertTrial.allowedDays | integer | 否 | — | 允许的期限天数集合；非空时优先采用该集合。 |
| data.items.capabilities.convertTrial.minDays | integer | 否 | 最小 0 | 无 allowedDays 集合时的最短期限。 |
| data.items.capabilities.convertTrial.maxDays | integer | 否 | 最小 0 | 最长期限，0 表示不设上限。 |
| data.items.capabilities.convertTrial.stepDays | integer | 否 | 最小 0 | 从最短期限起允许的增量天数。 |
| data.items.capabilities.trialDays | integer | 否 | 最小 0 | 试用期限天数；0 表示不提供试用。 |
| data.items.capabilities.changeIp | boolean | 否 | — | 是否支持换 IP。 |
| data.items.capabilities.selectReplacement | boolean | 否 | — | 是否支持选择替换节点。 |
| data.items.capabilities.customCredentials | boolean | 否 | — | 是否支持客户指定账密。 |
| data.items.capabilities.randomCredentials | boolean | 否 | — | 是否支持随机生成账密。 |
| data.items.capabilities.maxBatchSize | integer | 否 | 最小 0 | 货源能力声明的批量上限；服务端请求限制仍适用。 |
| data.items.groupId | integer \| null | 是 | 最小 1 | 所属自定义分组 ID，未分组为 null；新实例默认未分组。 |
| data.page | integer | 是 | 最小 0；格式 int64 | 页码，从 1 开始，默认 1。 |
| data.pageSize | integer | 是 | 最小 0；格式 int64 | 每页数量，默认 20；最大值见字段限制。 |
| data.total | integer | 是 | 最小 0；格式 int64 | 筛选后的总记录数，不是当前页条数。 |

```json
{
  "code": 200,
  "message": "成功",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "instanceId": 101,
        "offerId": 17,
        "status": "active",
        "ip": "203.0.113.10",
        "port": 9000,
        "protocols": [
          "http",
          "socks5"
        ],
        "countryCode": "USA",
        "cityCode": "NYC",
        "ispType": 1,
        "expiresAt": "2026-10-06T08:00:00Z",
        "activatedAt": "2026-10-06T08:00:00Z",
        "capabilities": {
          "purchase": {
            "allowedDays": [
              30
            ]
          },
          "renew": {
            "allowedDays": [
              30
            ]
          },
          "convertTrial": {},
          "trialDays": 0,
          "changeIp": false,
          "selectReplacement": false,
          "customCredentials": true,
          "randomCredentials": true,
          "maxBatchSize": 100
        },
        "groupId": null
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}
```

## 错误与重试

读取请求遇到 429 按 Retry-After 等待；500/503 可有限重试。分组创建结果不明时先查询分组列表；移动同一目标可安全重试。

错误码、HTTP 状态及错误响应字段统一见[错误码与处理建议](/developers/errors/error-codes)。

### 开通时间与批量端口查询

实例 GET 与批量 POST 搜索支持 `activatedFrom`、`activatedTo`，含时区 RFC3339 闭区间，支持单侧查询，反向或无效范围返回 400 / 10700。范围与 IP、端口、订单、分组等取交集。批量 `ips` 支持 `192.0.2.1:18080`、`[2001:db8::4]:18080`；无端口查询匹配全部端口，IPv6 带端口必须使用方括号。

html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}