Skip to content

Commit a4d7294

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #314018 from craigshoemaker/aca/sessions-api-updates
[Container Apps] Document Sessions Management API: get/list endpoints, error codes
2 parents 3746c10 + e3ef4b2 commit a4d7294

3 files changed

Lines changed: 156 additions & 9 deletions

File tree

‎articles/container-apps/session-pool.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ services: container-apps
55
author: craigshoemaker
66
ms.service: azure-container-apps
77
ms.topic: how-to
8-
ms.date: 04/07/2025
8+
ms.date: 03/31/2026
99
ms.author: cshoe
1010
---
1111

@@ -97,7 +97,7 @@ With the `Timed` lifecycle, a session is deleted after a period of inactivity. A
9797
9898
All requests to the pool management endpoint must include an `Authorization` header with a bearer token. To learn how to authenticate with the pool management API, see [Authentication](sessions-usage.md#authentication).
9999

100-
Each API request must also include the query string parameter `identifier` with the session ID. This unique session ID enables your application to interact with specific sessions. To learn more about session identifiers, see [Session identifiers](./sessions-usage.md#identifiers).
100+
Most API requests also require the query string parameter `identifier` with the session ID. This unique session ID enables your application to interact with specific sessions. Pool-wide operations like listing sessions don't require an identifier. To learn more about session identifiers, see [Session identifiers](./sessions-usage.md#identifiers).
101101

102102
## Image caching
103103

@@ -183,11 +183,15 @@ The following endpoints are available for managing sessions in a pool:
183183
| `files/upload` | `POST` | Upload a file to a session. |
184184
| `files/content/{filename}` | `GET` | Download a file from a session. |
185185
| `files` | `GET` | List the files in a session. |
186+
| `.management/getSession` | `POST` | Get details about a specific session. |
187+
| `.management/listSessions` | `POST` | List all sessions in the pool with pagination. |
186188

187189
You build the full URL for each endpoint by concatenating the pool's management API endpoint with the endpoint path. The query string must include an `identifier` parameter containing the session identifier, and an `api-version` parameter with the value `2024-02-02-preview`. API versions can change, so always confirm the latest version in the REST API docs before using it in production.
188190

189191
For example: `{sessionManagementEndpoint}/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>`
190192

193+
For the `getSession` and `listSessions` endpoints, see [Retrieve session information](./sessions-usage.md#retrieve-session-information) for request and response details.
194+
191195
For REST API references, see [Container Apps data-plane APIs](/rest/api/containerapps/#data-plane-apis) and the [Container Apps data-plane operations overview](/rest/api/data-plane/containerapps/operation-groups).
192196

193197
## Custom container session pool
@@ -204,6 +208,16 @@ For custom container session pools, get the management endpoint from the Azure p
204208

205209
The endpoint is in the format `https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io`.
206210

211+
Custom container pools support the same management endpoints as code interpreter pools, plus custom application endpoints you define:
212+
213+
| Endpoint path | Method | Description |
214+
|----------|--------|-------------|
215+
| `*` (custom paths) | `POST`, `GET` | Custom endpoints defined by your container application. |
216+
| `.management/getSession` | `POST` | Get details about a specific session. |
217+
| `.management/listSessions` | `POST` | List all sessions in the pool with pagination. |
218+
219+
For the `getSession` and `listSessions` endpoints, see [Retrieve session information](./sessions-usage.md#retrieve-session-information) for request and response details.
220+
207221
#### OnContainerExit
208222

209223
With the `OnContainerExit` lifecycle, a session remains active until the container exits on its own or the maximum alive period is reached.

‎articles/container-apps/sessions-usage.md‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ services: container-apps
55
author: craigshoemaker
66
ms.service: azure-container-apps
77
ms.topic: how-to
8-
ms.date: 05/19/2025
8+
ms.date: 03/31/2026
99
ms.author: cshoe
1010
ms.custom: references_regions, ignite-2024
1111
---
@@ -77,10 +77,145 @@ The session identifier is a string you define that is unique within the session
7777

7878
The identifier must be a string that is 4 to 128 characters long and can contain only alphanumeric characters and special characters from this list: `|`, `-`, `&`, `^`, `%`, `$`, `#`, `(`, `)`, `{`, `}`, `[`, `]`, `;`, `<`, and `>`.
7979

80+
## Retrieve session information
81+
82+
You can query your session pool to check session status, get expiration details, and list all active sessions. This capability is useful for monitoring session health, tracking resource usage, and implementing custom cleanup workflows.
83+
84+
### Get a single session
85+
86+
To retrieve details about a specific session, use the `getSession` endpoint:
87+
88+
```text
89+
POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/.management/getSession?identifier=<SESSION_ID>&api-version=2024-02-02-preview
90+
Authorization: Bearer <TOKEN>
91+
```
92+
93+
The `getSession` endpoint returns session metadata including the session identifier, current expiration time, and creation timestamp.
94+
95+
#### SessionView response schema
96+
97+
| Field | Type | Required | Description |
98+
|-------|------|----------|-------------|
99+
| `identifier` | string | Yes | The session identifier you provided |
100+
| `etag` | string | Yes | Opaque version identifier for the session. You can use this identifier for change detection. |
101+
| `expiresAt` | DateTime | Yes | UTC timestamp when the session will be terminated |
102+
| `createdAt` | DateTime | No | Session creation timestamp |
103+
| `lastAccessedAt` | DateTime | No | Timestamp of the last request to this session |
104+
105+
#### Example request and response
106+
107+
```bash
108+
curl -X POST "https://my-pool.env-id.westus2.azurecontainerapps.io/.management/getSession?identifier=user-123&api-version=2024-02-02-preview" \
109+
-H "Authorization: Bearer $TOKEN"
110+
```
111+
112+
Success response (HTTP 200):
113+
114+
```json
115+
{
116+
"identifier": "user-123",
117+
"etag": "a1b2c3d4",
118+
"expiresAt": "2026-04-30T14:30:00Z",
119+
"createdAt": "2026-04-30T13:30:00Z",
120+
"lastAccessedAt": "2026-04-30T14:29:00Z"
121+
}
122+
```
123+
124+
### List all sessions in a pool
125+
126+
To retrieve a list of all sessions in your session pool, use the `listSessions` endpoint:
127+
128+
```text
129+
POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/.management/listSessions?skip=0&api-version=2024-02-02-preview
130+
Authorization: Bearer <TOKEN>
131+
```
132+
133+
#### Pagination
134+
135+
The list endpoint supports skip-based pagination. By default, each page returns up to 300 sessions. Use the `skip` query parameter to navigate through results.
136+
137+
| Parameter | Description |
138+
|-----------|-------------|
139+
| `skip` | Number of sessions to skip from the beginning (default: 0) |
140+
| `nextLink` | Full URL for the next page of results (included in response when more results exist) |
141+
142+
#### ApiCollectionEnvelope response schema
143+
144+
| Field | Type | Description |
145+
|-------|------|-------------|
146+
| `value` | SessionView[] | Array of session objects |
147+
| `count` | integer | Number of sessions in the current page |
148+
| `nextLink` | string | URL for the next page (null if no more results) |
149+
150+
#### Example pagination loop
151+
152+
```bash
153+
POOL_URL="https://my-pool.env-id.westus2.azurecontainerapps.io"
154+
next_url="$POOL_URL/.management/listSessions?skip=0&api-version=2024-02-02-preview"
155+
156+
while [ -n "$next_url" ]; do
157+
response=$(curl -s -X POST "$next_url" \
158+
-H "Authorization: Bearer $TOKEN")
159+
160+
echo "$response" | jq '.value[] | {identifier, expiresAt}'
161+
162+
next_url=$(echo "$response" | jq -r '.nextLink // empty')
163+
done
164+
```
165+
166+
Example response (HTTP 200):
167+
168+
```json
169+
{
170+
"value": [
171+
{
172+
"identifier": "user-123",
173+
"etag": "a1b2c3d4",
174+
"expiresAt": "2026-04-30T14:30:00Z"
175+
},
176+
{
177+
"identifier": "user-456",
178+
"etag": "e5f6a7b8",
179+
"expiresAt": "2026-04-30T14:31:00Z"
180+
}
181+
],
182+
"count": 2,
183+
"nextLink": "https://my-pool.env-id.westus2.azurecontainerapps.io/.management/listSessions?skip=300"
184+
}
185+
```
186+
187+
## Error responses
188+
189+
When an error occurs, the API returns a structured error response with details to help you diagnose the issue.
190+
191+
```json
192+
{
193+
"error": {
194+
"code": "ErrorCode",
195+
"message": "Human-readable error description",
196+
"details": "Optional additional context",
197+
"target": "Field or parameter that caused the error",
198+
"traceId": "Request trace ID for debugging"
199+
}
200+
}
201+
```
202+
203+
### Common error codes
204+
205+
| Error Code | HTTP status | Description | Resolution |
206+
|------------|-------------|-------------|-----------|
207+
| `SessionWithIdentifierNotFound` | 400 | The session identifier doesn't exist in this session pool | Verify the session identifier is correct and the session hasn't expired |
208+
| `SessionRequestValidationFailed` | 400 | The request is missing required fields or has invalid parameters | Check the query parameters (identifier, skip, api-version) are properly formatted |
209+
| `SessionRequestNotSupported` | 400 | The request type isn't recognized by the API | Verify you're using a supported endpoint and method |
210+
| `InternalServerError` | 500 | An unexpected server-side error occurred | Retry the request; if the error persists, check the traceId in logs |
211+
80212
## Session lifecycle in practice
81213

82214
As you continue to make calls to the same session, the session remains [allocated](sessions.md#key-concepts) in the pool. Once there are no requests to the session after the cooldown period has elapsed, the session is automatically destroyed.
83215

216+
> [!NOTE]
217+
> In rare cases, when a session's background TTL-extension request fails (for example, if the container exits unexpectedly), the session is automatically removed from the pool. You'll see a "session not found" error on your next request to that session. This cleanup is automatic and requires no action on your part.
218+
84219
## Security
85220

86221
### Security model

‎articles/container-apps/sessions.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ services: container-apps
55
author: craigshoemaker
66
ms.service: azure-container-apps
77
ms.topic: concept-article
8-
ms.date: 04/07/2025
8+
ms.date: 03/31/2026
99
ms.author: cshoe
1010
ms.custom: references_regions, ignite-2024
1111
---
@@ -41,7 +41,7 @@ Dynamic sessions are useful in a variety of situations, including:
4141

4242
- **Session**: A session is the actual execution environment where your code or container runs. Sessions are ephemeral and isolated, designed for short-lived tasks. When you create a session, it's allocated from the session pool, ensuring fast startup. After the task completes or the cooldown period expires, the session is destroyed and resources are cleaned up.
4343

44-
- **Session lifecycle**: When your application sends a request with a session identifier, the session pool allocates a session automatically. The session stays active as long as requests continue. Once the cooldown period expires with no activity, the session is destroyed and its resources are cleaned up automatically.
44+
- **Session lifecycle**: When your application sends a request with a session identifier, the session pool allocates a session automatically. The session stays active as long as requests continue. Once the cooldown period expires with no activity, the session is destroyed and its resources are cleaned up automatically. You can also programmatically query session status and list all sessions in your pool to monitor health and implement custom management workflows.
4545

4646
- **Request routing and identifiers**: Sessions are accessed through the session pool management endpoint. Requests include an `identifier` query parameter, and the pool routes the request to an existing session or allocates a new one if needed. The request path after the management endpoint is forwarded to the session container.
4747

@@ -96,7 +96,5 @@ Dynamic sessions are designed to run untrusted code in isolated environments. Fo
9696
Custom container sessions are billed based on the resources consumed by the session pool. For more information, see [Azure Container Apps billing](./billing.md#dynamic-sessions).
9797

9898

99-
## Next steps
100-
- Learn how to configure [session pools](./session-pool.md)
101-
- Learn how to use [dynamic sessions](./sessions-usage.md), including security and best practices
102-
99+
## Related content
100+
- Learn how to configure [session pools](./session-pool.md)

0 commit comments

Comments
 (0)