---
title: "Get task cost and usage"
method: GET
path: "/v1/tasks/{task_id}/cost"
tags: ["Tasks"]
---

# Get task cost and usage

`GET /v1/tasks/{task_id}/cost`

## Request

- Base URL: `https://api.sandbase.ai`
- URL: `https://api.sandbase.ai/v1/tasks/{task_id}/cost`
- Auth: HTTP bearer

Returns the settlement status, final user cost, estimated cost, and token usage for a recent task.
Public API keys can retrieve only tasks originally created by that same API key, even when another key belongs to the same organization.
This lookup remains available after the key reaches its spending limit, but expired, revoked, or scoped keys are still rejected.
When `settled` is false, `cost` is not final and must not be used for billing or reconciliation.
Use `estimated_cost` only as a display estimate until final settlement completes.
Older task execution records may be archived after the retention window and then return 404.
Use billing records or billing exports for long-term reconciliation.

## Path parameters

- `task_id` string, required

## Response `200`

Task cost and usage

- TaskCostResponse
  - `id` string, required: SandBase task ID.
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'timeout', required
  - `settled` boolean, required: Whether final cost settlement has completed.
  - `currency` 'USD', required
  - `cost` string, required: USD amount with six decimal places. Not final while settled is false.
  - `estimated_cost` string, required: Best-effort USD estimate with six decimal places. Informational while settled is false; matches cost once settled is true.
  - `usage` TaskCostUsage, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `cached_tokens` integer, required
    - `cache_creation_tokens` integer, required
    - `reasoning_tokens` integer, required
  - `pricing` TaskCostPricing: Present only after settlement when a discount breakdown was recorded. original_cost minus discount_amount equals cost.
    - `original_cost` string, required: USD cost before discounts, with six decimal places.
    - `discount_amount` string, required: USD discount applied, with six decimal places.
    - `discount_percent` number, required: Discount percentage, for example 25 for 25 percent off.
    - `discount_type` string: Kind of discount applied. Omitted when not recorded.

## Other responses

- `401`: Missing or invalid API key
- `403`: API key scope does not authorize this endpoint
- `404`: Task does not exist or is not accessible with the current API key

---

[API](https://skmtc.dev/sandbase/apis/sandbase-api.md) · [All operations](https://skmtc.dev/sandbase/apis/sandbase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sandbase/apis/sandbase-api/revisions/d40df2467ba2?raw)