Cost tracking ↗

    from langsmith import traceable, get_current_run_tree

    inputs = [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "I'd like to book a table for two."},
    ]

    @traceable(
        run_type="llm",
        metadata={"ls_provider": "my_provider", "ls_model_name": "my_model"}
    )
    def chat_model(messages: list):
        # Imagine this is the real model output format your application expects
        assistant_message = {
            "role": "assistant",
            "content": "Sure, what time would you like to book the table for?"
        }

        # Token usage you compute or receive from the provider
        token_usage = {
            "input_tokens": 27,
            "output_tokens": 13,
            "total_tokens": 40,
            "input_token_details": {"cache_read": 10}
        }

        # Attach token usage to the LangSmith run
        run = get_current_run_tree()
        run.set(usage_metadata=token_usage)

        return assistant_message

    chat_model(inputs)
    ```

```typescript
    import { traceable, getCurrentRunTree } from "langsmith/traceable";

    const inputs = [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "I'd like to book a table for two." },
    ];

    const chatModel = traceable(
      async ({ messages }) => {
        // The output your application expects
        const assistantMessage = {
          role: "assistant",
          content: "Sure, what time would you like to book the table for?",
        };

        // Token usage you compute or receive from the provider
        const tokenUsage = {
          input_tokens: 27,
          output_tokens: 13,
          total_tokens: 40,
          input_token_details: { cache_read: 10 },
        };

        // Attach usage to the LangSmith run
        const runTree = getCurrentRunTree();
        runTree.metadata.usage_metadata = tokenUsage;

        return assistantMessage;
      },
      {
        run_type: "llm",
        name: "chat_model",
        metadata: {
          ls_provider: "my_provider",
          ls_model_name: "my_model",
        },
      }
    );

    await chatModel({ messages: inputs });
    ```
  
</Accordion>

<Accordion title="B. Return a `usage_metadata` field in your traced function's outputs.">
  Include the `usage_metadata` key directly within the object returned by your traced function. LangSmith will extract it from the output.

  
```python
    from langsmith import traceable

    inputs = [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "I'd like to book a table for two."},
    ]
    output = {
        "choices": [
            {
                "message": {
                    "role": "assistant",
                    "content": "Sure, what time would you like to book the table for?"
                }
            }
        ],
        "usage_metadata": {
            "input_tokens": 27,
            "output_tokens": 13,
            "total_tokens": 40,
            "input_token_details": {"cache_read": 10}
        },
    }

    @traceable(
        run_type="llm",
        metadata={"ls_provider": "my_provider", "ls_model_name": "my_model"}
    )
    def chat_model(messages: list):
        return output

    chat_model(inputs)
    ```

```typescript
    import { traceable } from "langsmith/traceable";

    const messages = [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "I'd like to book a table for two." }
    ];
    const output = {
        choices: [
            {
                message: {
                    role: "assistant",
                    content: "Sure, what time would you like to book the table for?",
                },
            },
        ],
        usage_metadata: {
            input_tokens: 27,
            output_tokens: 13,
            total_tokens: 40,
        },
    };

    const chatModel = traceable(
        async ({
            messages,
        }: {
            messages: { role: string; content: string }[];
            model: string;
        }) => {
            return output;
        },
        {
            run_type: "llm",
            name: "chat_model",
            metadata: {
                ls_provider: "my_provider",
                ls_model_name: "my_model"
            }
        }
    );

    await chatModel({ messages });
    ```
  
</Accordion>

In either case, the usage metadata should contain a subset of the following LangSmith-recognized fields:

<Accordion title="Usage Metadata Schema and Cost Calculation">
  The following fields in the `usage_metadata` dict are recognized by LangSmith. You can view the full [Python types](https://github.com/langchain-ai/langsmith-sdk/blob/e705fbd362be69dd70229f94bc09651ef8056a61/python/langsmith/schemas.py#L1196-L1227) or [TypeScript interfaces](https://github.com/langchain-ai/langsmith-sdk/blob/e705fbd362be69dd70229f94bc09651ef8056a61/js/src/schemas.ts#L637-L689) directly.

  <ParamField path="input_tokens" type="number">
Number of tokens used in the model input. Sum of all input token types.
  </ParamField>

  <ParamField path="output_tokens" type="number">
Number of tokens used in the model response. Sum of all output token types.
  </ParamField>

  <ParamField path="total_tokens" type="number">
Number of tokens used in the input and output. Optional, can be inferred. Sum of input\_tokens + output\_tokens.
  </ParamField>

  <ParamField path="input_token_details" type="object">
Breakdown of input token types. Keys are token-type strings, values are counts. Example `{"cache_read": 5}`.

Known fields include: `audio`, `text`, `image`, `cache_read`, `cache_creation`. Additional fields are possible depending on the model or provider.
  </ParamField>

  <ParamField path="output_token_details" type="object">
Breakdown of output token types. Keys are token-type strings, values are counts. Example `{"reasoning": 5}`.

Known fields include: `audio`, `text`, `image`, `reasoning`. Additional fields are possible depending on the model or provider.
  </ParamField>

  <ParamField path="input_cost" type="number">
Cost of the input tokens.
  </ParamField>

  <ParamField path="output_cost" type="number">
Cost of the output tokens.
  </ParamField>

  <ParamField path="total_cost" type="number">
Cost of the tokens. Optional, can be inferred.  Sum of input\_cost + output\_cost.
  </ParamField>

  <ParamField path="input_cost_details" type="object">
Details of the input cost. Keys are token-type strings, values are cost amounts.
  </ParamField>

  <ParamField path="output_cost_details" type="object">
Details of the output cost. Keys are token-type strings, values are cost amounts.
  </ParamField>

  **Cost Calculations**

  The cost for a run is computed greedily from most-to-least specific token type. Suppose you set a price of \$2 per 1M input tokens with a detailed price of \$1 per 1M `cache_read` input tokens, and \$3 per 1M output tokens. If you uploaded the following usage metadata:

  ```python
  {
    "input_tokens": 20,
    "input_token_details": {"cache_read": 5},
    "output_tokens": 10,
    "total_tokens": 30,
  }

# Notice that LangSmith computes the cache_read cost and then for any
# remaining input_tokens, the default input price is applied.
input_cost = 5 * 1e-6 + (20 - 5) * 2e-6  # 3.5e-5
output_cost = 10 * 3e-6  # 3e-5
total_cost = input_cost + output_cost  # 6.5e-5

from langsmith import traceable, get_current_run_tree

inputs = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "I'd like to book a table for two."},
]

@traceable(
    run_type="llm",
    metadata={"ls_provider": "my_provider", "ls_model_name": "my_model"}
)
def chat_model(messages: list):
    llm_output = {
        "choices": [
            {
                "message": {
                    "role": "assistant",
                    "content": "Sure, what time would you like to book the table for?"
                }
            }
        ],
        "usage_metadata": {
            # Specify cost (in dollars) for the inputs and outputs
            "input_cost": 1.1e-6,
            "input_cost_details": {"cache_read": 2.3e-7},
            "output_cost": 5.0e-6,
        },
    }
    run = get_current_run_tree()
    run.set(usage_metadata=llm_output["usage_metadata"])
    return llm_output["choices"][0]["message"]

chat_model(inputs)

import { traceable, getCurrentRunTree } from "langsmith/traceable";

const messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "I'd like to book a table for two." }
];

const chatModel = traceable(
  async (messages: { role: string; content: string }[]) => {
    const llmOutput = {
      choices: [
        {
          message: {
            role: "assistant",
            content: "Sure, what time would you like to book the table for?",
          },
        },
      ],
      // Specify cost (in dollars) for the inputs and outputs
      usage_metadata: {
        input_cost: 1.1e-6,
        input_cost_details: { cache_read: 2.3e-7 },
        output_cost: 5.0e-6,
      },
    };

    // Attach usage metadata to the run
    const runTree = getCurrentRunTree();
    runTree.metadata.usage_metadata = llmOutput.usage_metadata;

    // Return only the assistant message
    return llmOutput.choices[0].message;
  },
  {
    run_type: "llm",
    name: "chat_model",
    metadata: {
      ls_provider: "my_provider",
      ls_model_name: "my_model",
    },
  }
);

await chatModel(messages);