{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","api-content","endpoint","api-examples","tabs","tab","code-group"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Get music usage","description":"Complete API reference and documentation for Freddy AI-powered backend system by Aitronos","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"get-music-usage","__idx":0},"children":["Get music usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the caller's music generation spend for an organization, summarized over rolling day, week, and month windows with a per-engine breakdown."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"ApiContent","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"GET","path":"https://api.aitronos.com/v1/music/{organization_id}/usage"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this to see how much headroom remains before the organization's spend cap rejects a generation. Each window reports the current spend and the configured cap (if any)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"path-parameters","__idx":1},"children":["Path parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The organization the usage is scoped to. The caller must belong to it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":2},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A usage summary object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization_id"]}]}," string · The organization the usage is scoped to."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["windows"]}]}," array · One entry per rolling window. Each window contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window"]}]}," string · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["day"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["week"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["month"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window_start"]}]}," string · Start of the window (UTC)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cost_chf"]}]}," number · Spend within the window, in CHF."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit_chf"]}]}," number · The organization's configured spend cap for the window, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," if none."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["by_engine"]}]}," array · Per-engine breakdown, each with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["engine"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["track_count"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cost_chf"]},"."]}]}]},{"$$mdtype":"Tag","name":"ApiExamples","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"dropdown"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl \"https://api.aitronos.com/v1/music/org_abc123/usage\" \\\n  -H \"X-API-Key: $FREDDY_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python SDK","header":{"title":"Python SDK","controls":{"copy":{}}},"source":"from aitronos import Aitronos  # pip install aitronos-sdk\n\nclient = Aitronos(api_key=\"your-api-key\")\n\nusage = client.get(\"/v1/music/org_abc123/usage\")\nfor window in usage[\"windows\"]:\n    print(window[\"window\"], window[\"cost_chf\"], window[\"limit_chf\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import os\nimport requests\n\napi_key = os.environ[\"FREDDY_API_KEY\"]\n\nresponse = requests.get(\n    \"https://api.aitronos.com/v1/music/org_abc123/usage\",\n    headers={\"X-API-Key\": api_key},\n)\nfor window in response.json()[\"windows\"]:\n    print(f\"{window['window']}: {window['cost_chf']} CHF\")\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const apiKey = process.env.FREDDY_API_KEY;\n\nconst response = await fetch('https://api.aitronos.com/v1/music/org_abc123/usage', {\n  headers: { 'X-API-Key': apiKey }\n});\n\nconst usage = await response.json();\nusage.windows.forEach(w => console.log(`${w.window}: ${w.cost_chf} CHF`));\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"200 OK","header":{"title":"200 OK","controls":{"copy":{}}},"source":"{\n  \"organization_id\": \"org_abc123\",\n  \"windows\": [\n    {\n      \"window\": \"day\",\n      \"window_start\": \"2026-06-28T00:00:00Z\",\n      \"cost_chf\": 2.40,\n      \"limit_chf\": 10.00,\n      \"by_engine\": [\n        { \"engine\": \"studio\", \"track_count\": 6, \"cost_chf\": 2.40 }\n      ]\n    },\n    {\n      \"window\": \"week\",\n      \"window_start\": \"2026-06-22T00:00:00Z\",\n      \"cost_chf\": 11.20,\n      \"limit_chf\": 50.00,\n      \"by_engine\": [\n        { \"engine\": \"studio\", \"track_count\": 28, \"cost_chf\": 11.20 }\n      ]\n    },\n    {\n      \"window\": \"month\",\n      \"window_start\": \"2026-06-01T00:00:00Z\",\n      \"cost_chf\": 38.60,\n      \"limit_chf\": null,\n      \"by_engine\": [\n        { \"engine\": \"studio\", \"track_count\": 96, \"cost_chf\": 38.60 }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Errors","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"401 Unauthorized","header":{"title":"401 Unauthorized","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"AUTHENTICATION_REQUIRED\",\n    \"message\": \"Authentication required. Please provide a valid API key.\",\n    \"system_message\": \"Missing or invalid authorization header\",\n    \"type\": \"authentication_error\",\n    \"status\": 401,\n    \"details\": {},\n    \"trace_id\": \"req_abc123xyz\",\n    \"timestamp\": \"2026-06-28T10:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"403 Forbidden","header":{"title":"403 Forbidden","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INSUFFICIENT_PERMISSIONS\",\n    \"message\": \"You do not have permission to access this resource.\",\n    \"system_message\": \"USE_MUSIC_GENERATION capability required\",\n    \"type\": \"authorization_error\",\n    \"status\": 403,\n    \"details\": {},\n    \"trace_id\": \"req_def456uvw\",\n    \"timestamp\": \"2026-06-28T10:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":3},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/create-generation"},"children":["Create a generation job"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/assets/get-pricing.1269854a1f55d539f852daed275c801b2537623a4e2a270307a2239a4f87a659.4236153a.md"},"children":["Get pricing sheet"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/introduction"},"children":["Music Studio overview"]}]}]}]},"headings":[{"value":"Get music usage","id":"get-music-usage","depth":1},{"value":"Path parameters","id":"path-parameters","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Get music usage","keywords":["music usage","music spend","usage windows","spend cap"],"seo":{"title":"Get music usage"}},"lastModified":"2026-06-28T21:42:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/music/get-usage","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}