Ever found yourself staring at your OpenAI API bill, wondering exactly where all those tokens went? It's a common feeling, especially as you integrate powerful AI models into your projects. Thankfully, OpenAI offers tools to shed light on this, and the Usage API is a key player.
Think of the Usage API as your personal dashboard for understanding your AI activity. It's designed to give you a granular view of how you're interacting with OpenAI's services. While it provides detailed usage data, it's worth noting that it might not always perfectly align with your final bill. For financial reconciliation, the Costs endpoint or the Costs tab in the Usage Dashboard are your go-to resources, as they're designed to match your invoices.
Let's dive into the specifics, particularly for 'Completions.' If you're using the API to generate text, code, or any other form of completion, the GET https://api.openai.com/v1/organization/usage/completions endpoint is where you'll find the details. You can query this endpoint to get usage information for a specific time range, defined by start_time (which is required and in Unix seconds) and an optional end_time.
What's really powerful here is the ability to filter and group your usage. You can narrow down results by specific api_key_ids, project_ids, or user_ids. This is incredibly useful if you manage multiple projects or have different teams using your API keys. You can also specify models to see which ones are consuming the most resources, or filter for batch jobs versus non-batch jobs.
Grouping your data is where things get really insightful. You can group_by fields like project_id, user_id, api_key_id, model, batch, or service_tier. Imagine seeing a breakdown of token usage per project, or identifying which API key is generating the most requests. This level of detail can help you optimize costs, identify usage patterns, and even spot potential anomalies.
The bucket_width parameter is another handy feature. You can choose to see your usage broken down by minute (1m), hour (1h), or day (1d). This allows you to zoom in on specific periods or get a broader overview. Just be mindful of the limit parameter, which controls how many buckets you get back, especially when dealing with longer time ranges.
When you make a request, you'll receive a response that's paginated, meaning you might get a next_page cursor if there's more data. Each 'bucket' in the response contains results, which are the aggregated usage details for that specific time period. These results tell you about input_tokens, output_tokens, input_cached_tokens, and importantly, num_model_requests – the actual count of times a model was called. You'll also see the model name, whether it was a batch job, and potentially the project_id, user_id, api_key_id, and service_tier if you grouped by those fields.
It's like having a detailed logbook for your AI interactions. Understanding these metrics isn't just about tracking costs; it's about gaining a deeper appreciation for how your applications are leveraging these advanced AI capabilities. It empowers you to make informed decisions, optimize your AI strategy, and ensure you're getting the most value from your OpenAI API usage.
