> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pathors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查詢外撥活動清單

> 列出專案底下的外撥活動，最新的在前

列出某個專案底下的外撥活動，依建立時間由新到舊排序。用來找出您要拉取明細的那個活動。唯讀。

## 請求

```bash theme={null}
GET https://api.pathors.com/v1/campaigns?project_id={project_id}
```

### 標頭

<ParamField header="Authorization" type="string" required>
  使用您的 Developer Key（`dk_...`）進行 Bearer 令牌認證。
</ParamField>

### 查詢參數

<ParamField query="project_id" type="string" required>
  要列出活動的專案。Developer Key 必須有此專案的存取權。
</ParamField>

<ParamField query="status" type="string">
  以活動狀態篩選，逗號分隔（例如 `active,completed`）。傳入無法識別的值會回傳 `400`，而非靜默回傳空結果。
</ParamField>

<ParamField query="limit" type="integer">
  回傳筆數。預設 `20`，上限 `100`。只要最新的那一個活動就傳 `limit=1`。
</ParamField>

### 範例

```bash theme={null}
curl -H "Authorization: Bearer dk_your_key" \
  "https://api.pathors.com/v1/campaigns?project_id=proj_your_project_id&limit=1"
```

## 回應

<ResponseField name="data" type="array">
  <Expandable title="欄位">
    <ResponseField name="campaign_id" type="string">傳給明細端點使用</ResponseField>
    <ResponseField name="name" type="string">活動名稱，即後台設定的名稱</ResponseField>
    <ResponseField name="status" type="string">`draft`（尚未開撥）、`active`（排程器撥號中）或 `completed`</ResponseField>
    <ResponseField name="stopped_reason" type="string | null">提前停止撥號的原因，例如 `insufficient_credits`。未提前停止時為 `null`</ResponseField>
    <ResponseField name="created_at" type="string">活動建立時間（ISO 8601，UTC）— 即排序依據</ResponseField>
    <ResponseField name="updated_at" type="string">活動最後更新時間</ResponseField>
    <ResponseField name="total_contacts" type="integer">名單總筆數</ResponseField>
    <ResponseField name="dispatched_contacts" type="integer">已交給撥號器的筆數</ResponseField>
    <ResponseField name="completed_contacts" type="integer">派送已完成的筆數</ResponseField>
    <ResponseField name="connected_contacts" type="integer">實際接通的筆數 — 即接通數</ResponseField>
  </Expandable>
</ResponseField>

### 範例

```json theme={null}
{
  "data": [
    {
      "campaign_id": "cmp_example001",
      "name": "八月會員回訪",
      "status": "completed",
      "stopped_reason": null,
      "created_at": "2026-08-14T08:00:00.000Z",
      "updated_at": "2026-08-14T10:30:00.000Z",
      "total_contacts": 500,
      "dispatched_contacts": 500,
      "completed_contacts": 487,
      "connected_contacts": 312
    }
  ]
}
```

## 錯誤

| 狀態碼 | 時機                                              |
| --- | ----------------------------------------------- |
| 400 | 缺少 `project_id`、`status` 含無法識別的值，或 `limit` 超出範圍 |
| 401 | 缺少或無效的 Developer Key                            |
| 403 | 此 Developer Key 無權存取該專案                         |
| 500 | 內部伺服器錯誤                                         |

## 說明

* **排序依據**：`created_at` 由新到舊，不是 `updated_at`。排程器在撥號過程中會持續改寫活動，若以最後更新排序，一個上週建立、今天還在撥的活動會蓋過今天剛建立的。
* **判斷要不要拉明細**：比較 `completed_contacts` 與 `total_contacts` 就知道活動撥完了沒，不必先去抓[明細](/zh-Hant/api-reference/v1/campaigns/list-dispatches)。
* **不分頁**：一個專案的活動是幾十筆等級，`limit` 已足夠，沒有提供游標。
* **權限範圍**：只會列出 Developer Key 有權存取之專案底下的活動，不提供跨專案查詢。