# Read task billing

`GET /v1/video/tasks/{task_id}/billing`

Retrieve the whole-task billing summary and one ordered page of permanent billing events. Use cursor and page_size to continue. The summary always covers the task, rather than only the current event page. An unknown task or one outside your team returns task_not_found.

- Put your API key after `Authorization: Bearer` in the request header.
- The summary covers the whole task, never a subtotal of the current page.
- Page through permanent billing events with `cursor` and `page_size`.
- Amounts are USD strings with six decimal places.

## 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. |

## Path parameters

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `task_id` | string | Required | ID of the video task to retrieve |

## Query parameters

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `cursor` | string | Optional | Opaque value for fetching the next page of permanent billing events. Length: 1–256. |
| `page_size` | integer | Optional | Maximum number of billing events in this page. Default: 50. Range: 1–100. |

## Returns · HTTP 200

A whole-task billing summary with one ordered page of permanent events.

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `object` | string | Required | Identifies this object as task billing. Always: video.task.billing. |
| `task_id` | string | Required | ID of the task owned by your team. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `request_id` | string | Required | Request ID associated with the task. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `billing_correlation_id` | string | Required | ID used to correlate this task's billing. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `model` | string | Required | Model used for this task. `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; |
| `task_status` | string | Required | Progress of task execution. `queued`: Queued; `processing`: Processing; `succeeded`: Succeeded; `failed`: Failed; `cancelled`: Cancelled; |
| `settlement_status` | string | Required | Progress of billing settlement for this task. `reserved`: Reserved; `pending`: Pending; `reconciliation_required`: Under review; `settled`: Settled; `settled_with_receivable`: Settled - amount due; |
| `currency` | string | Required | Currency of the amounts: USD. Always: USD. |
| `reserved_amount` | string | Required | Amount reserved for the task. Format: 6 decimal places. |
| `charged_amount` | string | Required | Charge recorded for the task. Format: 6 decimal places. |
| `collected_liability_amount` | string | Required | Amount collected toward the charge. Format: 6 decimal places. |
| `funding_debit_amount` | string | Required | Amount debited from balance. Format: 6 decimal places. |
| `refunded_liability_amount` | string | Required | Amount of the charge refunded. Format: 6 decimal places. |
| `funding_refund_amount` | string | Required | Amount refunded to balance. Format: 6 decimal places. |
| `outstanding_receivable` | string | Required | Amount due that has not been collected. Zero for settled tasks that failed or were cancelled. Format: 6 decimal places. |
| `final_actual_cost` | string | Required, nullable | Final charge. Null while queued or processing, or while settlement is reserved, pending or reconciliation_required. An amount is provided for settled or settled_with_receivable. Settled tasks that failed or were cancelled have a zero final charge. Format: 6 decimal places. |
| `events` | array | Required | Permanent billing events in this page. Items: ≤ 100. |
| `events.billing_event_id` | string | Required | ID of this billing event. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `events.task_id` | string | Required | Task to which this event belongs. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `events.request_id` | string | Required | Request ID associated with the event. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `events.billing_correlation_id` | string | Required | ID used to correlate billing records. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `events.event_type` | string | Required | Kind of billing event recorded. `hold_created`: Reserved; `hold_increased`: Reservation increased; `hold_reduced`: Reservation reduced; `charge_captured`: Charged; `supplemental_charge`: Additional charge; `receivable_created`: Amount due recorded; `receivable_payment`: Amount due paid; `receivable_reduced`: Amount due reduced; `hold_released`: Reservation released; `refund_posted`: Refunded; `charge_waived`: Charge waived; `manual_adjustment`: Manual adjustment; |
| `events.billing_component` | string | Required | Part of the service being billed. `generation_output`: Video generation; `reference_video`: Reference video; `reference_image`: Reference image; `reference_audio`: Reference audio; `web_search`: Web search; `other`: Other billing component; |
| `events.amount` | string | Required | Amount of this event. Zero for charge_waived and greater than zero for hold_reduced. Format: 6 decimal places. |
| `events.charge_amount` | string | Required | Charge amount recorded by this event. Format: 6 decimal places. |
| `events.refund_amount` | string | Required | Refund amount recorded by this event. Format: 6 decimal places. |
| `events.collected_liability_amount` | string | Required | Amount collected in this event. Format: 6 decimal places. |
| `events.funding_debit_amount` | string | Required | Amount this event debited from balance. Format: 6 decimal places. |
| `events.funding_refund_amount` | string | Required | Amount this event refunded to balance. Format: 6 decimal places. |
| `events.receivable_amount` | string | Required | Change in the amount due recorded by this event. Format: 6 decimal places. |
| `events.receivable_direction` | string | Required, nullable | increase for receivable_created; decrease for receivable_payment or receivable_reduced. Null for other event types. `increase`: Increase in amount due; `decrease`: Decrease in amount due; `null`: Null value; |
| `events.adjustment_direction` | string | Required, nullable | debit or credit for manual_adjustment; null otherwise. `debit`: Debit direction; `credit`: Credit direction; `null`: Null value; |
| `events.audit_reason` | string | Required, nullable | Audit explanation, present for manual_adjustment and null for other events. Length: 1–1024. |
| `events.component_detail_code` | string | Required, nullable | Required detail code when billing_component is other; null for other components. Length: 1–96. Characters: a–z 0–9 _. |
| `events.currency` | string | Required | Currency of the amounts: USD. Always: USD. |
| `events.settlement_status` | string | Required | Settlement state recorded by this event. `reserved`: Reserved; `pending`: Pending; `reconciliation_required`: Under review; `settled`: Settled; `settled_with_receivable`: Settled - amount due; |
| `events.created_at` | integer | Required | Time the event was created, in whole Unix seconds. Range: ≥ 0. |
| `events.billing_operation_id` | string | Optional | ID of the billing operation, required for hold_reduced. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `events.quote_revision_before` | integer | Optional | Quote revision before the operation, required for hold_reduced. Range: ≥ 0. |
| `events.quote_revision_after` | integer | Optional | Quote revision after the operation, required for hold_reduced. Range: ≥ 1. |
| `events.reservation_revision_before` | integer | Optional | Reservation revision before the operation, required for hold_reduced. Range: ≥ 0. |
| `events.reservation_revision_after` | integer | Optional | Reservation revision after the operation, required for hold_reduced. Range: ≥ 1. |
| `next_cursor` | string | Required, nullable | Value for continuing to the next page, or null. Length: 1–256. |
| `reconciliation` | object | Required, nullable | Review summary when settlement is reconciliation_required. Null for reserved, pending, settled and settled_with_receivable. |
| `reconciliation.case_id` | string | Required | ID of the review case. Length: 4–128. Characters: A–Z a–z 0–9 _ -. |
| `reconciliation.reason_code` | string | Required | Code explaining why billing needs review. `missing_billable_usage`: Billable usage is missing; `usage_schema_drift`: The recorded usage shape has changed; `unknown_usage_unit`: The usage unit is not recognized; `price_rule_not_unique`: A single applicable price rule could not be determined; `output_unavailable`: Result unavailable; |
| `reconciliation.missing_meters` | array | Required | Missing usage measurements, without duplicates. At least one is listed for missing_billable_usage. Items: ≤ 16. |
| `reconciliation.customer_action_required` | boolean | Required | Whether you need to take any action. |

### 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 | A whole-task billing summary with one ordered page of permanent events. |  |
| 400 | The submitted request is not valid. | invalid_request |
| 401 | The API key is missing or invalid. Response headers: `WWW-Authenticate` | authentication_failed |
| 404 | No task with this ID is visible to your team. | task_not_found |
| 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

- [Reconcile charges](./api-docs-en-billing-reconcile.md)
- [How billing works](./api-docs-en-billing.md)

## Request examples

```bash
curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks/${TASK_ID}/billing" \
  --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}
TASK_ID = os.environ["TASK_ID"]
path = "/v1/video/tasks/{task_id}/billing".replace("{task_id}", urllib.parse.quote(TASK_ID, safe=""))
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 TASK_ID = process.env.TASK_ID;
if (!TASK_ID) throw new Error("Set TASK_ID");
const path = "/v1/video/tasks/{task_id}/billing".replace("{task_id}", encodeURIComponent(TASK_ID));
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"
	"net/url"
	"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")
	}
	taskID := os.Getenv("TASK_ID")
	if taskID == "" {
		fail("Set TASK_ID")
	}
	path := strings.Replace("/v1/video/tasks/{task_id}/billing", "{task_id}", url.PathEscape(taskID), 1)
	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": "video.task.billing",
  "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
  "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
  "model": "dreamina-seedance-2-0-260128",
  "task_status": "succeeded",
  "settlement_status": "settled",
  "currency": "USD",
  "reserved_amount": "0.782453",
  "charged_amount": "0.361564",
  "collected_liability_amount": "0.361564",
  "funding_debit_amount": "0.361564",
  "refunded_liability_amount": "0.000000",
  "funding_refund_amount": "0.000000",
  "outstanding_receivable": "0.000000",
  "final_actual_cost": "0.361564",
  "events": [
    {
      "billing_event_id": "bevt_example_hold_0001",
      "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "event_type": "hold_created",
      "billing_component": "generation_output",
      "amount": "0.782453",
      "charge_amount": "0.000000",
      "refund_amount": "0.000000",
      "collected_liability_amount": "0.000000",
      "funding_debit_amount": "0.000000",
      "funding_refund_amount": "0.000000",
      "receivable_amount": "0.000000",
      "receivable_direction": null,
      "adjustment_direction": null,
      "audit_reason": null,
      "component_detail_code": null,
      "currency": "USD",
      "settlement_status": "reserved",
      "created_at": 1793167380
    },
    {
      "billing_event_id": "bevt_example_capture_0001",
      "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "event_type": "charge_captured",
      "billing_component": "generation_output",
      "amount": "0.361564",
      "charge_amount": "0.361564",
      "refund_amount": "0.000000",
      "collected_liability_amount": "0.361564",
      "funding_debit_amount": "0.361564",
      "funding_refund_amount": "0.000000",
      "receivable_amount": "0.000000",
      "receivable_direction": null,
      "adjustment_direction": null,
      "audit_reason": null,
      "component_detail_code": null,
      "currency": "USD",
      "settlement_status": "settled",
      "created_at": 1793167382
    },
    {
      "billing_event_id": "bevt_example_release_0001",
      "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "event_type": "hold_released",
      "billing_component": "generation_output",
      "amount": "0.420889",
      "charge_amount": "0.000000",
      "refund_amount": "0.000000",
      "collected_liability_amount": "0.000000",
      "funding_debit_amount": "0.000000",
      "funding_refund_amount": "0.000000",
      "receivable_amount": "0.000000",
      "receivable_direction": null,
      "adjustment_direction": null,
      "audit_reason": null,
      "component_detail_code": null,
      "currency": "USD",
      "settlement_status": "settled",
      "created_at": 1793167383
    }
  ],
  "next_cursor": null,
  "reconciliation": 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"
}
```

404

```json
{
  "error": {
    "code": "task_not_found",
    "message": "task was not found"
  },
  "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"
}
```