# Get a focus session

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.

Poll this endpoint to retrieve newly-ready segments while a session is active. Each segment's `playback_url` is short-lived and re-minted on every request. A session you do not own returns `404`.

## Path parameters

**`organization_id`** string required

The organization the session is scoped to. The caller must belong to it.

**`session_id`** string required

The focus session id (`mfocus_`-prefixed).

## Returns

A focus session object.

**`session_id`** string · Session id (`mfocus_`-prefixed).

**`status`** string · One of `active`, `ended`, or `stopped_cap`.

**`goal`** string · The focus goal for the session.

**`engine`** string · Internal engine key the session generates with.

**`target_minutes`** integer · Target session length in minutes.

**`total_segments`** integer · Total number of segments planned for the session.

**`ready_count`** integer · Number of segments currently ready to play.

**`segments`** array · Ready segment objects. Each contains:

- **`segment_index`** integer · Zero-based position of the segment.
- **`playback_url`** string · Short-TTL signed URL for the segment audio.
- **`measured_duration_seconds`** number · Measured segment duration in seconds.
- **`target_lufs`** number · Target loudness (LUFS) for crossfade-smooth playback.
- **`fade_in_ms`** integer · Recommended fade-in duration in milliseconds.
- **`fade_out_ms`** integer · Recommended fade-out duration in milliseconds.


**`more_pending`** boolean · Whether more segments are still being generated.

**`next_ready_at`** string · Prefetch hint for when the next segment is expected to be ready (UTC), or `null`.

Example

```bash cURL
curl "https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

session = client.get("/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d")
for segment in session["segments"]:
    print(segment["segment_index"], segment["playback_url"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d",
    headers={"X-API-Key": api_key},
)
print(response.json()["ready_count"])
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch(
  'https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d',
  { headers: { 'X-API-Key': apiKey } }
);

const session = await response.json();
console.log(`${session.ready_count}/${session.total_segments} ready`);
```

**Response:**


```json 200 OK
{
  "session_id": "mfocus_7c2a9f4e1b8d",
  "status": "active",
  "goal": "focus",
  "engine": "studio",
  "target_minutes": 60,
  "total_segments": 30,
  "ready_count": 2,
  "segments": [
    {
      "segment_index": 0,
      "playback_url": "https://cdn.aitronos.com/music/seg/...signed",
      "measured_duration_seconds": 120.4,
      "target_lufs": -14.0,
      "fade_in_ms": 1500,
      "fade_out_ms": 1500
    },
    {
      "segment_index": 1,
      "playback_url": "https://cdn.aitronos.com/music/seg/...signed",
      "measured_duration_seconds": 119.8,
      "target_lufs": -14.0,
      "fade_in_ms": 1500,
      "fade_out_ms": 1500
    }
  ],
  "more_pending": true,
  "next_ready_at": "2026-06-28T10:32:00Z"
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "system_message": "Focus session not found",
    "type": "client_error",
    "status": 404,
    "details": { "session_id": "mfocus_7c2a9f4e1b8d" },
    "trace_id": "req_jkl012mno",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [Start a focus session](/docs/api-reference/music/start-focus-session)
- [End a focus session](/docs/api-reference/music/end-focus-session)
- [Promote a focus segment](/docs/api-reference/music/promote-focus-segment)