Read task billing

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

Retrieve the whole-task billing summary and one ordered page of permanent billing events.

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

#AuthorizationstringRequired

Bearer, a space and your API key. A missing or invalid key returns 401 authentication_failed.

#X-Request-IDstring

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

#task_idstringRequired

ID of the video task to retrieve

Query parameters

#cursorstring

Opaque value for fetching the next page of permanent billing events.

Length1–256

#page_sizeinteger

Maximum number of billing events in this page.

Default50Range1–100

Request

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

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)

// 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;

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)
}

ReturnsHTTP 200

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

#objectstringRequired

Identifies this object as task billing.

Alwaysvideo.task.billing

#task_idstringRequired

ID of the task owned by your team.

Length4–128CharactersA–Z a–z 0–9 _ -

#request_idstringRequired

Request ID associated with the task.

Length4–128CharactersA–Z a–z 0–9 _ -

#billing_correlation_idstringRequired

ID used to correlate this task's billing.

Length4–128CharactersA–Z a–z 0–9 _ -

#modelstringRequired

Model used for this task.

dreamina-seedance-2-0-260128Seedance 2.0

dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast

dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini

#task_statusstringRequired

Progress of task execution.

queuedQueued

processingProcessing

succeededSucceeded

failedFailed

cancelledCancelled

#settlement_statusstringRequired

Progress of billing settlement for this task.

reservedReserved

pendingPending

reconciliation_requiredUnder review

settledSettled

settled_with_receivableSettled - amount due

#currencystringRequired

Currency of the amounts: USD.

AlwaysUSD

#reserved_amountstringRequired

Amount reserved for the task.

Format6 decimal places

#charged_amountstringRequired

Charge recorded for the task.

Format6 decimal places

#collected_liability_amountstringRequired

Amount collected toward the charge.

Format6 decimal places

#funding_debit_amountstringRequired

Amount debited from balance.

Format6 decimal places

#refunded_liability_amountstringRequired

Amount of the charge refunded.

Format6 decimal places

#funding_refund_amountstringRequired

Amount refunded to balance.

Format6 decimal places

#outstanding_receivablestringRequired

Amount due that has not been collected. Zero for settled tasks that failed or were cancelled.

Format6 decimal places

#final_actual_coststringRequiredNullable

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.

Format6 decimal places

#eventsarrayRequired

Permanent billing events in this page.

Items≤ 100

25 child fields

#billing_event_idstringRequired

ID of this billing event.

Length4–128CharactersA–Z a–z 0–9 _ -

#task_idstringRequired

Task to which this event belongs.

Length4–128CharactersA–Z a–z 0–9 _ -

#request_idstringRequired

Request ID associated with the event.

Length4–128CharactersA–Z a–z 0–9 _ -

#billing_correlation_idstringRequired

ID used to correlate billing records.

Length4–128CharactersA–Z a–z 0–9 _ -

#event_typestringRequired

Kind of billing event recorded.

hold_createdReserved

hold_increasedReservation increased

hold_reducedReservation reduced

charge_capturedCharged

supplemental_chargeAdditional charge

receivable_createdAmount due recorded

receivable_paymentAmount due paid

receivable_reducedAmount due reduced

hold_releasedReservation released

refund_postedRefunded

charge_waivedCharge waived

manual_adjustmentManual adjustment

#billing_componentstringRequired

Part of the service being billed.

generation_outputVideo generation

reference_videoReference video

reference_imageReference image

reference_audioReference audio

web_searchWeb search

otherOther billing component

#amountstringRequired

Amount of this event. Zero for charge_waived and greater than zero for hold_reduced.

Format6 decimal places

#charge_amountstringRequired

Charge amount recorded by this event.

Format6 decimal places

#refund_amountstringRequired

Refund amount recorded by this event.

Format6 decimal places

#collected_liability_amountstringRequired

Amount collected in this event.

Format6 decimal places

#funding_debit_amountstringRequired

Amount this event debited from balance.

Format6 decimal places

#funding_refund_amountstringRequired

Amount this event refunded to balance.

Format6 decimal places

#receivable_amountstringRequired

Change in the amount due recorded by this event.

Format6 decimal places

#receivable_directionstringRequiredNullable

increase for receivable_created; decrease for receivable_payment or receivable_reduced. Null for other event types.

One ofincreasedecreasenull

#adjustment_directionstringRequiredNullable

debit or credit for manual_adjustment; null otherwise.

One ofdebitcreditnull

#audit_reasonstringRequiredNullable

Audit explanation, present for manual_adjustment and null for other events.

Length1–1024

#component_detail_codestringRequiredNullable

Required detail code when billing_component is other; null for other components.

Length1–96Charactersa–z 0–9 _

#currencystringRequired

Currency of the amounts: USD.

AlwaysUSD

#settlement_statusstringRequired

Settlement state recorded by this event.

reservedReserved

pendingPending

reconciliation_requiredUnder review

settledSettled

settled_with_receivableSettled - amount due

#created_atintegerRequired

Time the event was created, in whole Unix seconds.

Range≥ 0

#billing_operation_idstring

ID of the billing operation, required for hold_reduced.

Length4–128CharactersA–Z a–z 0–9 _ -

#quote_revision_beforeinteger

Quote revision before the operation, required for hold_reduced.

Range≥ 0

#quote_revision_afterinteger

Quote revision after the operation, required for hold_reduced.

Range≥ 1

#reservation_revision_beforeinteger

Reservation revision before the operation, required for hold_reduced.

Range≥ 0

#reservation_revision_afterinteger

Reservation revision after the operation, required for hold_reduced.

Range≥ 1

#next_cursorstringRequiredNullable

Value for continuing to the next page, or null.

Length1–256

#reconciliationobjectRequiredNullable

Review summary when settlement is reconciliation_required. Null for reserved, pending, settled and settled_with_receivable.

4 child fields

#case_idstringRequired

ID of the review case.

Length4–128CharactersA–Z a–z 0–9 _ -

#reason_codestringRequired

Code explaining why billing needs review.

missing_billable_usageBillable usage is missing

usage_schema_driftThe recorded usage shape has changed

unknown_usage_unitThe usage unit is not recognized

price_rule_not_uniqueA single applicable price rule could not be determined

output_unavailableResult unavailable

#missing_metersarrayRequired

Missing usage measurements, without duplicates. At least one is listed for missing_billable_usage.

Items≤ 16

#customer_action_requiredbooleanRequired

Whether you need to take any action.

Response headers

#X-Request-IDstringRequired

The identifier of this request: the valid value you sent, or its replacement.

Response

{
  "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
}

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

{
  "error": {
    "code": "task_not_found",
    "message": "task was not found"
  },
  "trace_id": "trace_error_example"
}

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

Status codes

Each error.code and what to do about it is on Error codes.

Status	Meaning and 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

Reconcile charges How billing works

Read task billing

Headers

Path parameters

Query parameters

ReturnsHTTP 200

Response headers

Status codes

Related guides