Lacak biaya dan penggunaan

​

Pahami penggunaan token

• TypeScript menyediakan breakdown token per-step pada setiap pesan asisten (message.message.id, message.message.usage), biaya per-model melalui modelUsage pada pesan hasil, dan total kumulatif pada pesan hasil.
• Python menyediakan breakdown token per-step pada setiap pesan asisten sebagai message.usage dan message.message_id, biaya per-model melalui model_usage pada pesan hasil, dan total kumulatif pada pesan hasil sebagai total_cost_usd.

• query() call: satu invokasi dari fungsi query() SDK. Satu panggilan dapat melibatkan beberapa langkah: Claude merespons, menggunakan tools, mendapatkan hasil, dan merespons lagi. Setiap panggilan menghasilkan satu pesan result di akhir, kecuali dalam mode input streaming, di mana satu panggilan query() membawa beberapa giliran pengguna dan setiap giliran memancarkan pesan result miliknya sendiri.
• Step: satu siklus request/response dalam panggilan query(). Setiap langkah menghasilkan pesan asisten dengan penggunaan token.
• Session: serangkaian panggilan query() yang terhubung oleh ID sesi melalui opsi resume. Hasil panggilan yang dilanjutkan melaporkan pengeluaran seluruh sesi, bukan hanya panggilan itu sendiri. Lihat Accumulate costs across multiple calls untuk cara total dibawa ke depan.

​

Lacak biaya dalam mode input streaming

• usage: mencakup hanya giliran itu, dan di dalamnya hanya loop agen utama, bukan subagen apa pun yang dijalankannya.
• total_cost_usd dan modelUsage, atau model_usage dalam Python: membawa total berjalan untuk seluruh panggilan sejauh ini, ditambah pengeluaran apa pun yang dipulihkan ketika panggilan melanjutkan sesi.

• Hasil giliran /clear itu sendiri: mencakup hanya apa yang telah berjalan sejak pengaturan ulang, dan membawa session_id baru.
• Setiap hasil kemudian: terus menghitung dari pengaturan ulang itu.
• Hasil terakhir sebelum setiap /clear: menyimpan total untuk giliran sejak pengaturan ulang sebelumnya.

​

Dapatkan total biaya dari sebuah query

• Di Python bidang ini diketik sebagai opsional, jadi periksa bahwa itu bukan None sebelum Anda membacanya.
• Hasil sukses dan kesalahan keduanya membawanya, meskipun hasil akhir dari kerusakan sesi mungkin membawanya dengan nilai nol.

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "result") {
      console.log(`Total cost: $${message.total_cost_usd}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, it still carried total_cost_usd and the
  // branch above has already run; connection or process failures yield
  // no result message.
  console.error(`Session ended with an error: ${error}`);
}

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, ResultMessage):
                print(f"Total cost: ${message.total_cost_usd or 0}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the branch above has already run;
        # connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

​

Lacak penggunaan per-langkah dan per-model

​

Lacak penggunaan per-langkah

import { query } from "@anthropic-ai/claude-agent-sdk";

const seenIds = new Set<string>();
let totalInputTokens = 0;
let resultOutputTokens = 0;

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant" && !message.parent_tool_use_id) {
      const msgId = message.message.id;

      // Parallel tool calls share the same ID, only count once
      if (!seenIds.has(msgId)) {
        seenIds.add(msgId);
        totalInputTokens += message.message.usage.input_tokens;
      }
    }
    if (message.type === "result") {
      // Per-step output_tokens is a placeholder; the result message
      // carries the accumulated output total.
      resultOutputTokens = message.usage.output_tokens;
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result, so the
  // input total below still reflects the steps that ran before the failure.
  console.error(`Session ended with an error: ${error}`);
}

console.log(`Steps: ${seenIds.size}`);
console.log(`Input tokens: ${totalInputTokens}`);
console.log(`Output tokens: ${resultOutputTokens}`);

​

Rincian penggunaan per model

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type !== "result") continue;

    for (const [modelName, usage] of Object.entries(message.modelUsage)) {
      console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
      console.log(`  Input tokens: ${usage.inputTokens}`);
      console.log(`  Output tokens: ${usage.outputTokens}`);
      console.log(`  Cache read: ${usage.cacheReadInputTokens}`);
      console.log(`  Cache creation: ${usage.cacheCreationInputTokens}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the per-model breakdown above has already
  // printed; connection or process failures yield no result message.
  console.error(`Session ended with an error: ${error}`);
}

​

Akumulasi biaya di seluruh beberapa panggilan

• Panggilan independen, tanpa opsi resume atau continue: setiap hasil hanya mencakup panggilan miliknya sendiri, jadi tambahkan totalnya sendiri, seperti yang dilakukan contoh di bawah ini.
• Panggilan yang melanjutkan sesi yang sama: Claude Code menyimpan total sesi ke transcript ketika proses keluar secara normal dan memulihkannya ketika panggilan nanti melanjutkan atau memisahkan sesi. Setiap hasil sudah mencakup pengeluaran awal sesi. Baca hasil terbaru untuk total sesi; menjumlahkan hasil menghitung dua kali pengeluaran yang dipulihkan. Sebelum v2.1.277, sesi yang Anda lanjutkan melalui SDK atau claude -p memulai totalnya di nol, jadi hasil setiap panggilan hanya mencakup panggilan itu.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Track cumulative cost across multiple query() calls
let totalSpend = 0;

const prompts = [
  "Read the files in src/ and summarize the architecture",
  "List all exported functions in src/auth.ts"
];

for (const prompt of prompts) {
  try {
    for await (const message of query({ prompt })) {
      if (message.type === "result") {
        totalSpend += message.total_cost_usd;
        console.log(`This call: $${message.total_cost_usd}`);
      }
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result. If the
    // failure was an error result, this call's cost was already counted;
    // connection or process failures yield no result message. Continue
    // with the next prompt.
    console.error(`Call failed: ${error}`);
  }
}

console.log(`Total spend: $${totalSpend.toFixed(4)}`);

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    # Track cumulative cost across multiple query() calls
    total_spend = 0.0

    prompts = [
        "Read the files in src/ and summarize the architecture",
        "List all exported functions in src/auth.ts",
    ]

    for prompt in prompts:
        try:
            async for message in query(prompt=prompt):
                if isinstance(message, ResultMessage):
                    cost = message.total_cost_usd or 0
                    total_spend += cost
                    print(f"This call: ${cost}")
        except Exception as error:
            # A single-shot query() raises after yielding an error result. If
            # the failure was an error result, this call's cost was already
            # counted; connection or process failures yield no result message.
            # Continue with the next prompt.
            print(f"Call failed: {error}")

    print(f"Total spend: ${total_spend:.4f}")


asyncio.run(main())

​

Menangani kesalahan, caching, dan jumlah token output

​

Baca token output dari pesan hasil

​

Lacak biaya pada percakapan yang gagal

• error_during_execution setelah kerusakan sesi: setiap bidang biaya dapat dinolkan.
• error_max_budget_usd: usage menghilangkan respons yang melampaui anggaran, sementara total_cost_usd dan modelUsage menyertakannya.

​

Pulihkan total setelah kerusakan sesi

1. Gunakan hasil giliran sebelum kerusakan. Dalam mode input streaming, ia menyimpan total berjalan yang dijelaskan dalam Track costs in streaming input mode. Lanjutkan ke langkah 2 sebagai gantinya ketika hasil itu tidak dapat membantu Anda:
   • Panggilan adalah single-shot, jadi tidak ada hasil sebelumnya.
   • Kerusakan terjadi pada giliran pertama.
   • Giliran sebelum kerusakan adalah /clear itu sendiri, jadi hasilnya hanya mencakup reset.
2. Jumlahkan usage pada pesan asisten sebagai gantinya, menghitung setiap respons API sekali, seperti yang dilakukan contoh Track per-step usage. Dalam mode single-shot, jumlahkan semuanya; dalam mode input streaming, jumlahkan yang tiba setelah hasil terakhir. Ini memberi Anda token input dan cache loop utama. Penggunaan subagent tidak dapat dipulihkan dengan cara ini, begitu juga token output atau biaya USD, karena per-step output_tokens adalah placeholder.

​

Lacak token cache

• cache_creation_input_tokens: token yang digunakan untuk membuat entri cache baru (dikenakan biaya pada tingkat lebih tinggi daripada token input standar).
• cache_read_input_tokens: token yang dibaca dari entri cache yang ada (dikenakan biaya pada tingkat berkurang).

​

Perpanjang TTL cache prompt ke satu jam

from claude_agent_sdk import ClaudeAgentOptions, query
import asyncio


async def main():
    options = ClaudeAgentOptions(
        env={
            "CLAUDE_CODE_USE_BEDROCK": "1",
            "ENABLE_PROMPT_CACHING_1H": "1",
        },
    )

    async for message in query(prompt="Summarize this project", options=options):
        print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

const options = {
  env: {
    ...process.env,
    CLAUDE_CODE_USE_BEDROCK: "1",
    ENABLE_PROMPT_CACHING_1H: "1",
  },
};

for await (const message of query({ prompt: "Summarize this project", options })) {
  console.log(message);
}

• Percakapan utama: variabel lingkungan CLAUDE_CODE_PROMPT_CACHE_TTL, atau pengaturan promptCacheTtl
• Segalanya: variabel lingkungan CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, atau pengaturan subagentPromptCacheTtl

​

Dokumentasi terkait

• Referensi SDK TypeScript - Dokumentasi API lengkap
• Ikhtisar SDK - Memulai dengan SDK
• Izin SDK - Mengelola izin alat