Costs API

The Costs API allows you to track, analyze, and optimize the costs associated with your AI workflows on the Lumea platform.

Overview

The Costs API provides visibility into the expenses incurred by your AI operations. It enables you to track costs at both individual workflow run level and across multiple runs, helping you optimize resource utilization and budget planning.

Note: Each customer receives a custom deployment with a unique API endpoint. The endpoints described in this documentation should be prefixed with your organization's specific API URL provided during onboarding.

Data Models

ServiceCost Object

Field	Type	Description
id	string	Unique identifier for the cost entry
run_id	string	ID of the workflow run that incurred the cost
service	string	The service used (e.g., "openai", "anthropic")
group	string	Optional grouping (e.g., model name within service)
amount	float	The cost amount in USD
created_at	string	Timestamp when the cost was recorded

CostResponse Object

Field	Type	Description
total_cost	float	Total cost sum across all services
costs_by_service	object	Costs aggregated by service name
costs_by_group	object	Costs grouped by service and then by group

Endpoints

Get Run Costs

Retrieves cost information for a specific workflow run.

URL: /costs/runs/{run_id}

Method: GET

URL Parameters:

Parameter	Description
run_id	The unique ID of the workflow run

Query Parameters:

Parameter	Required	Description
include_children	No	Whether to include costs from child runs recursively (default: false)

Success Response:

• Code: 200 OK
• Content:

{
  "total_cost": 0.45,
  "costs_by_service": {
    "openai": 0.35,
    "anthropic": 0.1
  },
  "costs_by_group": {
    "openai": {
      "gpt-4": 0.25,
      "gpt-3.5-turbo": 0.1
    },
    "anthropic": {
      "claude-3-opus": 0.1
    }
  }
}

Error Response:

• Code: 500 Internal Server Error
  • Content: {"detail": "Error message"}

Get Multiple Runs Costs

Retrieves aggregated cost information for multiple workflow runs with optional filtering.

URL: /costs/runs

Method: GET

Query Parameters:

Parameter	Required	Description
workflow_id	No	Filter costs by workflow ID
start_date	No	Filter costs by start date (ISO format)
end_date	No	Filter costs by end date (ISO format)
include_children	No	Whether to include costs from child runs recursively (default: false)

Success Response:

• Code: 200 OK
• Content:

{
  "total_cost": 1.25,
  "costs_by_service": {
    "openai": 0.85,
    "anthropic": 0.3,
    "cohere": 0.1
  },
  "costs_by_group": {
    "openai": {
      "gpt-4": 0.65,
      "gpt-3.5-turbo": 0.2
    },
    "anthropic": {
      "claude-3-opus": 0.2,
      "claude-3-sonnet": 0.1
    },
    "cohere": {
      "command": 0.1
    }
  }
}

Error Response:

• Code: 500 Internal Server Error
  • Content: {"detail": "Error message"}