{"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 a focus session","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-a-focus-session","__idx":0},"children":["Get a focus session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve a focus session's ready segments, each with a freshly-minted signed playback URL and crossfade metadata, plus a prefetch hint for the next segment."]},{"$$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}/focus/sessions/{session_id}"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll this endpoint to retrieve newly-ready segments while a session is active. Each segment's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["playback_url"]}," is short-lived and re-minted on every request. A session you do not own returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},"."]},{"$$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 session is scoped to. The caller must belong to it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_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 focus session id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mfocus_"]},"-prefixed)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":2},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A focus session object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_id"]}]}," string · Session id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mfocus_"]},"-prefixed)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]}," string · One of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ended"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stopped_cap"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["goal"]}]}," string · The focus goal for the session."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["engine"]}]}," string · Internal engine key the session generates with."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target_minutes"]}]}," integer · Target session length in minutes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_segments"]}]}," integer · Total number of segments planned for the session."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_count"]}]}," integer · Number of segments currently ready to play."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segments"]}]}," array · Ready segment objects. Each 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":["segment_index"]}]}," integer · Zero-based position of the segment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["playback_url"]}]}," string · Short-TTL signed URL for the segment audio."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["measured_duration_seconds"]}]}," number · Measured segment duration in seconds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target_lufs"]}]}," number · Target loudness (LUFS) for crossfade-smooth playback."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fade_in_ms"]}]}," integer · Recommended fade-in duration in milliseconds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fade_out_ms"]}]}," integer · Recommended fade-out duration in milliseconds."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["more_pending"]}]}," boolean · Whether more segments are still being generated."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next_ready_at"]}]}," string · Prefetch hint for when the next segment is expected to be ready (UTC), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$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/focus/sessions/mfocus_7c2a9f4e1b8d\" \\\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\nsession = client.get(\"/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d\")\nfor segment in session[\"segments\"]:\n    print(segment[\"segment_index\"], segment[\"playback_url\"])\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/focus/sessions/mfocus_7c2a9f4e1b8d\",\n    headers={\"X-API-Key\": api_key},\n)\nprint(response.json()[\"ready_count\"])\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(\n  'https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d',\n  { headers: { 'X-API-Key': apiKey } }\n);\n\nconst session = await response.json();\nconsole.log(`${session.ready_count}/${session.total_segments} ready`);\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  \"session_id\": \"mfocus_7c2a9f4e1b8d\",\n  \"status\": \"active\",\n  \"goal\": \"focus\",\n  \"engine\": \"studio\",\n  \"target_minutes\": 60,\n  \"total_segments\": 30,\n  \"ready_count\": 2,\n  \"segments\": [\n    {\n      \"segment_index\": 0,\n      \"playback_url\": \"https://cdn.aitronos.com/music/seg/...signed\",\n      \"measured_duration_seconds\": 120.4,\n      \"target_lufs\": -14.0,\n      \"fade_in_ms\": 1500,\n      \"fade_out_ms\": 1500\n    },\n    {\n      \"segment_index\": 1,\n      \"playback_url\": \"https://cdn.aitronos.com/music/seg/...signed\",\n      \"measured_duration_seconds\": 119.8,\n      \"target_lufs\": -14.0,\n      \"fade_in_ms\": 1500,\n      \"fade_out_ms\": 1500\n    }\n  ],\n  \"more_pending\": true,\n  \"next_ready_at\": \"2026-06-28T10:32:00Z\"\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":"404 Not Found","header":{"title":"404 Not Found","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"RESOURCE_NOT_FOUND\",\n    \"message\": \"The requested resource was not found.\",\n    \"system_message\": \"Focus session not found\",\n    \"type\": \"client_error\",\n    \"status\": 404,\n    \"details\": { \"session_id\": \"mfocus_7c2a9f4e1b8d\" },\n    \"trace_id\": \"req_jkl012mno\",\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/start-focus-session"},"children":["Start a focus session"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/end-focus-session"},"children":["End a focus session"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/promote-focus-segment"},"children":["Promote a focus segment"]}]}]}]},"headings":[{"value":"Get a focus session","id":"get-a-focus-session","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 a focus session","keywords":["focus session","get focus","focus segments","playback url"],"seo":{"title":"Get a focus session"}},"lastModified":"2026-06-28T21:42:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/music/get-focus-session","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}