> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.ideogram.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server. # Get usage and spend GET https://api.ideogram.ai/v2/account/usage Returns your organization's billed API usage as dense time buckets of line items. Every line item carries the billed dollar amount; products billed per item also carry `billed_units` (unit, quantity, and unit price, where `quantity × unit_price = cost_total`). Usage-priced products (billed by metered provider usage) report `cost_total` only. Buckets cover the requested range completely — a bucket with no line items means no billed usage in that window. Line items are unique per bucket on (`product`, `dimensions`, `api_key.id`, unit price). Usage billed without an API key (requests authenticated as a user session) is included with `api_key` absent, so totals always reconcile with your invoices. `product` and `endpoint` are stable identifiers safe to aggregate on; `description` is display text and may be reworded at any time. Usage data may lag live traffic by a few minutes, and responses may be cached briefly, so this endpoint is for reporting rather than real-time monitoring. Requires an API key whose owner is an organization admin. Keys owned by other members receive a 404. Reference: https://developer.ideogram.ai/api-reference/account/usage ## Authentication - `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\" ## Request ### Query parameters - `start_time` (datetime, required) — Start of the reporting range (RFC 3339). Snapped down to the containing bucket boundary (UTC). - `end_time` (datetime, optional) — End of the reporting range (RFC 3339), exclusive. Snapped up to the next bucket boundary (UTC). Defaults to now. - `bucket_width` (enum, optional, default: 1d) — Bucket granularity. `1d` allows ranges up to 92 days per request; `1h` allows up to 168 hours. Page through longer histories by moving `start_time` back across successive requests. - Allowed values: `1d`, `1h` - `sources` (list of enum, optional, default: ["api","app"]) — Which billing sources to include. `api` is usage from API requests; `app` is web-app usage, attributed to the member who generated it. Defaults to both, so report totals reconcile with invoices. - Allowed values: `api`, `app` ## Response ### 200 Bucketed usage for the requested range. - `buckets` (list of AccountUsageBucket, required) — Dense, chronological buckets covering the requested range. ## Errors ### 400 Bad Request Error Invalid time range, bucket width, or filters. - `any` ### 401 Unauthorized Error Unauthorized. - `any` ### 404 Not Found Error No organization with billing access was found for this credential. - `any` ### 429 Too Many Requests Error Too many requests. - `any` ## Types ### AccountUsageBucket - `start_time` (datetime, required) — Start of the bucket window (inclusive, UTC). - `end_time` (datetime, required) — End of the bucket window (exclusive, UTC). - `line_items` (list of AccountUsageLineItem, required) — Usage billed in this window. Empty when nothing was billed. ### AccountUsageLineItem One billed rate for one billing actor within one time bucket. - `product` (string, required) — Stable identifier of the public pricing catalog entry this charge was billed under, at the granularity the pricing page prices it (for example one entry per quality and resolution). `unknown` when a historical charge can no longer be attributed; its cost is still included. - `endpoint` (string, required) — The API endpoint path this product belongs to. - `description` (string, required) — Name of the public pricing catalog entry, as shown on the pricing page. Not an identifier. - `cost_total` (string, required) — Total billed amount in `currency_code`, as a decimal string. - `currency_code` (string, required) — ISO 4217 currency code of the amounts on this line item. - `source` (enum, required) — Which billing surface the usage came through. `api` usage is attributed to an API key when one was used; `app` usage is attributed to the member who generated it. - Allowed values: `api`, `app` - `dimensions` (map from string to string, optional) — Pricing dimensions this line item was billed under, for products priced per dimension (for example rendering speed). - `api_key` (AccountUsageApiKey, optional) — The API key the usage was billed to, in redacted form. - `user_email` (string, optional, nullable) — Email address of the member who generated the usage. Only present on `app` usage. - `billed_units` (AccountUsageBilledUnits, optional) — Per-unit detail for products billed per item. `quantity × unit_price` always equals the line item's `cost_total`. ### AccountUsageApiKey The API key the usage was billed to, in redacted form. - `id` (string, required) — The API key's id, as listed by `GET /v2/account/api-keys`. - `redacted_key` (string, optional, nullable) — The first characters of the key followed by bullets. - `label` (string, optional, nullable) — The key's user-supplied label, when one is set. ### AccountUsageBilledUnits Per-unit detail for products billed per item. `quantity × unit_price` always equals the line item's `cost_total`. - `unit` (string, required) — What one billed unit is (for example `image`). - `quantity` (string, required) — Number of units billed, as a decimal string. - `unit_price` (string, required) — Price per unit in `currency_code`, as a decimal string. ## Examples **Response** ```json { "buckets": [ { "start_time": "2024-01-15T09:30:00Z", "end_time": "2024-01-15T09:30:00Z", "line_items": [ { "product": "ideogram_v4_generation", "endpoint": "/v2/image/generate/ideogram-4", "description": "Ideogram v4 Generation", "cost_total": "84.00", "currency_code": "USD", "source": "api", "dimensions": { "rendering_speed": "TURBO" }, "api_key": { "id": "JRPVD7jWR1aTBYiJ0UFVOg", "redacted_key": "ATG5•••••••••••••", "label": "Live production environment" }, "billed_units": { "unit": "image", "quantity": "2100", "unit_price": "0.04" } }, { "product": "gpt_image_2_edit", "endpoint": "/v2/image/generate/gpt-image-2", "description": "GPT Image 2 Edit", "cost_total": "3.47", "currency_code": "USD", "source": "api", "api_key": { "id": "JRPVD7jWR1aTBYiJ0UFVOg", "redacted_key": "ATG5•••••••••••••", "label": "Live production environment" } } ] } ] } ``` **SDK Code** ```python account_get_account_usage_example import requests url = "https://api.ideogram.ai/v2/account/usage" querystring = {"start_time":"start_time"} headers = {"Api-Key": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript account_get_account_usage_example const url = 'https://api.ideogram.ai/v2/account/usage?start_time=start_time'; const options = {method: 'GET', headers: {'Api-Key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go account_get_account_usage_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ideogram.ai/v2/account/usage?start_time=start_time" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Api-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby account_get_account_usage_example require 'uri' require 'net/http' url = URI("https://api.ideogram.ai/v2/account/usage?start_time=start_time") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Api-Key"] = '' response = http.request(request) puts response.read_body ``` ```java account_get_account_usage_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ideogram.ai/v2/account/usage?start_time=start_time") .header("Api-Key", "") .asString(); ``` ```php account_get_account_usage_example request('GET', 'https://api.ideogram.ai/v2/account/usage?start_time=start_time', [ 'headers' => [ 'Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp account_get_account_usage_example using RestSharp; var client = new RestClient("https://api.ideogram.ai/v2/account/usage?start_time=start_time"); var request = new RestRequest(Method.GET); request.AddHeader("Api-Key", ""); IRestResponse response = client.Execute(request); ``` ```swift account_get_account_usage_example import Foundation let headers = ["Api-Key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/v2/account/usage?start_time=start_time")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```