View all methods

aiToolMetrics.push

Add daily usage data for bespoke AI tools by email, date, and tool combinations.

Facts

Method	POST https://yourinstance.getdx.net/api/aiToolMetrics.push

Arguments

Required arguments

Name	Type	Description
token	Token	Auth token passed as an HTTP header.
email	String	User email address.
date	String	Metrics recording date.
is_active	Boolean	User activity flag.
tool	String	AI tool name.

Optional arguments

Name	Type	Description
metrics	JSON Object	Usage data object.
input_tokens	Integer	Number of input tokens consumed.
output_tokens	Integer	Number of output tokens generated.
cache_write_tokens	Integer	Number of tokens written to cache.
cache_read_tokens	Integer	Number of tokens read from cache.
spend_cents	Integer	Amount spent in cents.
model_breakdowns	Array	Optional usage breakdowns by model. See Model breakdowns.

Model breakdowns

model_breakdowns is an optional array of objects containing usage by model for the record’s email, date, and tool. Each object supports these fields:

Name	Type	Description
model	String	Required. Non-empty model name, unique within this record’s model_breakdowns array.
input_tokens	Integer	Optional. Uncached input tokens consumed. Must be non-negative.
output_tokens	Integer	Optional. Output tokens generated. Must be non-negative.
cache_write_tokens	Integer	Optional. Tokens written to the prompt cache. Must be non-negative.
cache_read_tokens	Integer	Optional. Tokens read from the prompt cache. Must be non-negative.
spend_cents	Integer	Optional. Amount spent in US cents. Must be non-negative.
credits_used	Number	Optional. Credits consumed, including fractional credits. Must be non-negative.

Send cumulative daily values for each model. Resubmitting a model replaces its usage values for that email, date, and tool; omitted usage fields for a submitted model become null. Models omitted from the array retain their existing values. Omitting model_breakdowns, sending null, or sending "model_breakdowns": [] leaves existing breakdowns unchanged.

Model breakdowns are supplemental and do not replace or contribute to the top-level daily totals. Supply daily totals separately using the top-level token and spend fields. Breakdowns are stored in bespoke_ai_tool_model_breakdowns, linked to bespoke_ai_tool_daily_metrics by daily_user_metric_id, and are not included in the API response.

Invalid model breakdowns return HTTP 422 without writing any records from the request.

Usage info

AI Tool Metrics API methods can be used to add daily usage data for bespoke AI tools to your Data Cloud instance. It allows you to store metrics by email, date, and tool combinations with flexible JSON data. An additional is_active flag can be provided for each record. The records are stored in the bespoke_ai_tool_daily_metrics table that is queryable in Data Studio alongside all of your other Data Cloud data. This data can also be used to automatically generate usage attributes for users, as outlined in AI usage attributes.

For more information about the supported SQL operators and functions available for querying the JSON values please reference the PostgreSQL documentation.

Response

Name	Type	Description
id	String	Generated unique ID for the record.
email	String	User email address.
date	String	Metrics recording date.
is_active	Boolean	User activity flag.
tool	String	AI tool name.
metrics	JSON Object	Usage data object.
input_tokens	Integer	Number of input tokens consumed.
output_tokens	Integer	Number of output tokens generated.
cache_write_tokens	Integer	Number of tokens written to cache.
cache_read_tokens	Integer	Number of tokens read from cache.
spend_cents	Integer	Amount spent in cents.

Example request

This is a typical request:

curl -X POST https://yourinstance.getdx.net/api/aiToolMetrics.push \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "email": "test@example.com",
    "date": "2025-01-15",
    "is_active": true,
    "tool": "tabnine",
    "metrics": {"usage": 100},
    "input_tokens": 10000,
    "output_tokens": 500,
    "cache_write_tokens": 2000,
    "cache_read_tokens": 1000,
    "spend_cents": 100,
    "model_breakdowns": [
      {
        "model": "custom-model",
        "input_tokens": 10000,
        "output_tokens": 500,
        "cache_write_tokens": 2000,
        "cache_read_tokens": 1000,
        "spend_cents": 100,
        "credits_used": 1.25
      }
    ]
  }'