# 会话

查看网关产品上活跃的粘性会话。适合监控长时采集与提前清理超量会话。

> ISP 没有会话 API——ISP 每个 IP 本身就永久稳定，不存在临时会话状态。

## 端点

| 方法       | 路径                         | 用途         |
| -------- | -------------------------- | ---------- |
| `GET`    | `/residential/sessions`    | 列出活跃住宅粘性会话 |
| `GET`    | `/mobile/sessions`         | 列出活跃移动粘性会话 |
| `GET`    | `/{product}/sessions/{id}` | 获取单个会话详情   |
| `DELETE` | `/{product}/sessions/{id}` | 提前终止会话     |

## 列出

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/sessions?subuser=sub_01HX2K3PQ4M5"
```

响应：

```json
{
  "data": [
    {
      "id":               "ses_01HX2K3PQ4M5",
      "subuser":          "sub_01HX2K3PQ4M5",
      "session_id":       "job1",
      "region":           "us",
      "state":            "ca",
      "city":             "la",
      "asn":              7922,
      "exit_ip":          "198.51.100.42",
      "started_at":       "2026-05-28T07:00:00Z",
      "expires_at":       "2026-05-28T07:30:00Z",
      "bytes_used":       3145728,
      "requests":         42,
      "repinned":         false
    }
  ],
  "next_cursor": null
}
```

筛选参数：`subuser`、`session_id`、`region`、`asn`、`repinned=true|false`。

### 字段

* `session_id` 是用户在用户名中自定义的部分（如 `-session-job1-sesstime-30` 的 `job1`）。
* `repinned` 为 `true` 表示上游 IP 在会话中途被重分配。
* `expires_at` = `started_at + sesstime`。

## 获取单个

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/sessions/ses_01HX2K3PQ4M5"
```

字段同列表，并附最近 10 条请求样本。

## 终止

```bash
curl -X DELETE -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/sessions/ses_01HX2K3PQ4M5"
```

之后使用同一用户名的请求会获得**新**出口 IP，效果与 `sesstime` 自然到期相同。会话记录保留 24 小时供审计，状态变为 `terminated`。

终止场景：

* worker 崩溃，希望明确清理状态——影响微小，因为 helodata 到 `expires_at` 也会自动到期
* 改变了主意要换 geo，比等到期更快
* 事故响应的一部分

## 并发提示

`session_id` 可复用；相同 `session_id` 配不同 geo/子账号被视为**不同会话**。**完整用户名**才是会话键。

## 错误

| 状态码   | code                     | 含义                     |
| ----- | ------------------------ | ---------------------- |
| `404` | `session_not_found`      | 会话不存在或已过期              |
| `403` | `subuser_scope_mismatch` | Token scope 不覆盖该子账号的产品 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/api-can-kao/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.