API Documentation

AI Prompt Cost is an OpenAI-compatible proxy. One URL change gives you full cost visibility.

Overview

AI Prompt Cost forwards your requests to OpenAI, tracks cost and usage metadata, and returns the unmodified OpenAI response. It is designed to be a drop-in replacement — no SDK changes required.

How it works:

Your app sends a standard OpenAI chat completion request to the AI Prompt Cost proxy endpoint
AI Prompt Cost validates your platform API key and forwards the request to OpenAI using your user's provider key
OpenAI's response is returned to your app, unmodified
Usage metadata (model, cost, prompt key, feature tags) is logged asynchronously — never blocking your request

Privacy guarantee: Prompt content and response text are never stored. Only metadata is logged: model name, cost, request count, and your custom identifiers (prompt_key, feature_tags).

Quickstart

Create a team and API key

Open the dashboard and create a team. Generate an API key for that team. This key goes in the Authorization header of every proxy request.

In the dashboard, create prompt records with a prompt_key identifier. You can also add versioned configurations (model, temperature, max_tokens). Prompts are auto-created on first use if you skip this step.

Point your app at the proxy

Replace your OpenAI base URL with the AI Prompt Cost proxy endpoint:

text

https://aipromptcost.com/api/proxy/chat/completions

Add the required headers described below.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer your_ai_prompt_cost_api_key_here — Your AI Prompt Cost platform API key
X-Provider-Key	Yes	sk-xxxxx — Your user's OpenAI API key

Request Body Metadata

Metadata is passed in the request body under the _aipromptcost object:

json

{
  "model": "gpt-4o",
  "messages": [...],
  "_aipromptcost": {
    "prompt_key": "document-summarizer",
    "feature_tags": ["summarization", "documents"],
    "version": 2
  }
}

prompt_key (recommended) — Identifies which prompt this request belongs to

feature_tags (optional) — Array of feature tags for categorization

version (optional) — Specific version number to associate with this request

Code Examples

All examples send the same request — pick your language.

JavaScript / Node.js

const response = await fetch(
  'https://aipromptcost.com/api/proxy/chat/completions',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your_ai_prompt_cost_api_key_here',
      'X-Provider-Key': 'sk-user_openai_key_here',
    },
    body: JSON.stringify({
      model: 'gpt-4o',
      messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        { role: 'user', content: 'Summarize this document...' },
      ],
      temperature: 0.7,
      max_tokens: 500,
      _aipromptcost: {
        prompt_key: 'document-summarizer',
        feature_tags: ['summarization', 'documents'],
        version: 2,
      },
    }),
  }
);

const data = await response.json();
console.log(data.choices[0].message.content);

Python

python

import requests

response = requests.post(
    'https://aipromptcost.com/api/proxy/chat/completions',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your_ai_prompt_cost_api_key_here',
        'X-Provider-Key': 'sk-user_openai_key_here',
    },
    json={
        'model': 'gpt-4o',
        'messages': [
            {'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': 'Summarize this document...'},
        ],
        'temperature': 0.7,
        'max_tokens': 500,
        '_aipromptcost': {
            'prompt_key': 'document-summarizer',
            'feature_tags': ['summarization', 'documents'],
            'version': 2,
        },
    }
)

data = response.json()
print(data['choices'][0]['message']['content'])

OpenAI SDK (Python)

python

from openai import OpenAI

client = OpenAI(
    api_key='your_ai_prompt_cost_api_key_here',
    base_url='https://aipromptcost.com/api/proxy',
    default_headers={
        'X-Provider-Key': 'sk-user_openai_key_here',
    }
)

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello!'}],
    extra_body={
        '_aipromptcost': {
            'prompt_key': 'document-summarizer',
            'feature_tags': ['summarization', 'documents'],
            'version': 2,
        }
    }
)

cURL

bash

curl -X POST https://aipromptcost.com/api/proxy/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_ai_prompt_cost_api_key_here" \
  -H "X-Provider-Key: sk-user_openai_key_here" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "_aipromptcost": {
      "prompt_key": "document-summarizer",
      "feature_tags": ["summarization", "documents"],
      "version": 2
    }
  }'

Dashboard

Usage by Prompt

The "Spend by Prompt" view shows all registered prompt keys ranked by total cost and request count for the selected date range. Use this to identify your most expensive prompts and prioritize optimization efforts.

Usage by Team

The "Spend by Team" view breaks down costs by team name (derived from the API key used). Useful for chargeback reporting or understanding which teams are scaling their AI usage fastest.

Monthly Trend

The monthly trend chart shows cost over time, helping you spot growth patterns or the impact of prompt changes month-over-month.

Date Filtering

All dashboard views support date range filtering. Select a custom range to analyze a specific sprint, release window, or billing period.

Prompt Versioning

Prompt versions let you track configuration changes over time without storing prompt text. Each version records: model name, temperature, max tokens, active/inactive status, and created timestamp.

Creating a version

In the dashboard, navigate to a prompt and click "Add Version". Fill in the model and parameter configuration. Mark a version as active to associate future requests with it automatically.

Version comparison

The Version Comparison chart shows cost and request volume side-by-side across all versions of a prompt. Use this to validate whether a configuration change reduced costs or improved efficiency.

Only one version can be active at a time. Historical versions remain visible for comparison but do not receive new usage associations.

Best Practices

→
Keep prompt_key consistent — Use the same key across all requests for a given prompt. Changing it creates a new prompt record and breaks historical continuity.
→
Use feature_tags for product analytics — Tag requests by feature area to understand AI costs per product surface. Multiple tags allow for flexible categorization.
→
Use separate API keys per team — This enables accurate team-level cost attribution automatically.
→
Keep prompt content on your side — AI Prompt Cost never stores prompt text. Your intellectual property stays in your codebase.
→
Register prompts before going to production — Pre-registering prompts lets you add descriptions and set up versioning before traffic arrives.
→
Store user provider keys securely — The X-Provider-Key header contains your user's OpenAI API key. Store these securely and never log them.

Troubleshooting

Symptom	Likely Cause	Fix
401 Unauthorized	Invalid or revoked platform API key, or missing X-Provider-Key header	Check your AI Prompt Cost API key in the dashboard and ensure X-Provider-Key header is present.
400 Bad Request	Malformed JSON or missing required fields	Ensure the request body is valid JSON with at least model and messages.
502 Bad Gateway	OpenAI API is unreachable, or user's provider key is invalid	Check the X-Provider-Key value and OpenAI service status.
No cost metrics	Missing prompt_key in _aipromptcost	Add _aipromptcost.prompt_key to your request body. Without it, usage is logged under 'unknown'.
Wrong team costs	Using a shared API key	Create a dedicated API key per team in the dashboard.
Version not tracked	No active version set for the prompt	Go to the prompt in the dashboard and mark a version as active.

API Reference

POST/api/proxy/chat/completions

Proxies a chat completion request to OpenAI and logs usage metadata. Returns the unmodified OpenAI response.

Request Body

{
  model: string;
  messages: Array<{ role: string; content: string }>;
  temperature?: number;
  max_tokens?: number;
  _aipromptcost?: {
    prompt_key?: string;
    feature_tags?: string[];
    version?: number;
  };
}

GET/api/aggregations/monthly

Returns total cost for the current or specified period.

Query Params

start, end (ISO date strings)

Response

json

{
  "total_cost": 12.45,
  "period": { "start": "2026-02-01", "end": "2026-02-28" }
}

GET/api/aggregations/by-prompt

Returns cost and request count grouped by prompt key.

Query Params

start, end

Response

json

{
  "prompts": [
    { "prompt_key": "document-summarizer", "total_cost": 4.20, "request_count": 312 },
    { "prompt_key": "chat-assistant", "total_cost": 2.10, "request_count": 890 }
  ]
}

GET/api/aggregations/by-team

Returns cost and request count grouped by team.

Query Params

start, end

Response

json

{
  "teams": [
    { "team_name": "backend", "total_cost": 8.30, "request_count": 540 },
    { "team_name": "frontend", "total_cost": 3.15, "request_count": 220 }
  ]
}

GET/api/aggregations/version-comparison

Returns cost and request count per version for a given prompt.

Query Params

prompt_key (required), start, end

Response

json

{
  "versions": [
    { "version_number": 1, "total_cost": 6.00, "request_count": 400, "avg_cost_per_request": 0.015 },
    { "version_number": 2, "total_cost": 4.20, "request_count": 400, "avg_cost_per_request": 0.0105 }
  ]
}