# List team tasks

`GET /v1/video/tasks`

Returns tasks across your team, including those created with other API keys. Newer tasks come first, with Task ID breaking ties. Teams with no tasks receive an empty list. List items contain IDs, model, status, timestamps and cancellation details when a cancellation exists. Fetch task details for usage, billing, result files and errors.

- Put your API key after `Authorization: Bearer` in the request header.
- Lists all of your team's tasks, whichever API key created them, newest first.
- Page with `next_cursor`; it is null on the last page.
- Read usage, charges, results and errors from the task by its ID.

## Headers

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Required | Bearer, a space and your API key. A missing or invalid key returns 401 authentication_failed. |
| `X-Request-ID` | string | Optional | Your own request identifier. An invalid or repeated value is replaced; the value used comes back in the X-Request-ID response header. |

## Query parameters

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `cursor` | string | Optional | Use next_cursor from the preceding page. A value not issued for this team's task list returns invalid_request. Length: 1–256. |
| `page_size` | integer | Optional | Maximum number of tasks to return on this page. Default: 50. Range: 1–100. |

## Returns · HTTP 200

One page of the current team's tasks.

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `object` | string | Required | Identifies the kind of object returned. Always: list. |
| `data` | array | Required | Task entries included in this page. Items: ≤ 100. |
| `data.id` | string | Required | ID of the task in this list entry. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `data.request_id` | string | Required | Request ID used to correlate this task. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `data.billing_correlation_id` | string | Required | Billing correlation ID for this task. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `data.model` | string | Required | ID of the model used for this request. `dreamina-seedance-2-0-260128`: Seedance 2.0; `dreamina-seedance-2-0-fast-260128`: Seedance 2.0 Fast; `dreamina-seedance-2-0-mini-260615`: Seedance 2.0 Mini; |
| `data.status` | string | Required | Current state; see the value notes for its meaning. `queued`: Queued; `processing`: Processing; `succeeded`: Succeeded; `failed`: Failed; `cancelled`: Cancelled; |
| `data.phase` | string | Required, nullable | Current execution phase, or null when no phase applies. `preparing_assets`: Preparing inputs; `waiting_route`: Waiting; `submitting`: Starting; `provider_processing`: Generating; `reconciling`: Confirming the result; `finalizing`: Finishing; `settlement_pending`: Awaiting settlement; `null`: Null value; |
| `data.delivery_status` | string | Required | Progress of result file delivery. `pending`: Not yet delivered; `materializing`: Preparing the download; `available`: Ready to download; `output_unavailable`: Result unavailable; |
| `data.settlement_status` | string | Required | Current progress of billing settlement. `reserved`: Reserved; `pending`: Pending; `reconciliation_required`: Under review; `settled`: Settled; `settled_with_receivable`: Settled - amount due; |
| `data.created_at` | integer | Required | Creation time as whole seconds since the Unix epoch. Range: ≥ 0. |
| `data.started_at` | integer | Required, nullable | Time the task started, or null before it starts. Range: ≥ 0. |
| `data.completed_at` | integer | Required, nullable | Time the task finished, or null while unfinished. Range: ≥ 0. |
| `data.cancellation` | object | Optional, nullable | Stable Cancellation ID, status and reason code when a cancellation operation exists. Omitted otherwise. |
| `data.cancellation.cancel_operation_id` | string | Required | Stable ID of the cancellation operation. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `data.cancellation.status` | string | Required | Current state; see the value notes for its meaning. `requested`: Requested; `effective`: Cancelled; `not_effective`: Not cancelled; `failed`: Failed; |
| `data.cancellation.reason_code` | string | Required, nullable | Reason cancellation did not take effect or failed. Null when requested or effective. Length: 1–96. Characters: a–z 0–9 _. |
| `next_cursor` | string | Required, nullable | Value for requesting the next page, or null on the last page. Length: 1–256. |

### Response headers

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `X-Request-ID` | string | Required | The identifier of this request: the valid value you sent, or its replacement. |

## Status codes

Each `error.code` and what to do about it is on [Error codes](./api-docs-en-api-errors.md).

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | One page of the current team's tasks. |  |
| 400 | The submitted request is not valid. | invalid_request |
| 401 | The API key is missing or invalid. Response headers: `WWW-Authenticate` | authentication_failed |
| 429 | The request rate limit blocks this read operation. Response headers: `Retry-After` | rate_limited |
| 500 | Internal error. | internal_error |
| 503 | The service is temporarily unavailable. | dependency_unavailable |

## Related guides

- [Task status and results](./api-docs-en-video-tasks.md)
- [Request conventions](./api-docs-en-conventions.md)

## Request examples

```bash
curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}"
```

```python
import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
path = "/v1/video/tasks"
request = urllib.request.Request(base + path, data=None, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)
```

```javascript
// Needs Node.js 20 or later; save it as a .mjs file and run it.
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const path = "/v1/video/tasks";
const response = await fetch(base.replace(/\/$/, "") + path, {method: "GET", headers, body: undefined});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	path := "/v1/video/tasks"
	request, err := http.NewRequest("GET", base+path, nil)
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}
```

## Response examples

200

```json
{
  "object": "list",
  "data": [
    {
      "id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "model": "dreamina-seedance-2-0-260128",
      "status": "succeeded",
      "phase": null,
      "delivery_status": "available",
      "settlement_status": "settled",
      "created_at": 1793167380,
      "started_at": 1793167381,
      "completed_at": 1793167382
    }
  ],
  "next_cursor": null
}
```

400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "request parameters are invalid"
  },
  "trace_id": "trace_error_example"
}
```

401

```json
{
  "error": {
    "code": "authentication_failed",
    "message": "authentication failed"
  },
  "trace_id": "trace_error_example"
}
```

429

```json
{
  "error": {
    "code": "rate_limited",
    "message": "request rate limit exceeded"
  },
  "trace_id": "trace_error_example"
}
```

500

```json
{
  "error": {
    "code": "internal_error",
    "message": "internal server error"
  },
  "trace_id": "trace_error_example"
}
```

503

```json
{
  "error": {
    "code": "dependency_unavailable",
    "message": "service is not ready"
  },
  "trace_id": "trace_error_example"
}
```