# Sessions

> Source: https://developers.cloud66.com/v3/endpoints/sessions/

## Get Container Session

URL: https://developers.cloud66.com/v3/endpoints/sessions/#fetch
Endpoint: GET /stacks/:stack_id/sessions/fetch
OAuth scope: redeploy

# Get Container Session

Retrieves container session information for debugging and troubleshooting purposes. Returns either a specific session by ID or the most recent session for a specified service.

## Session Lookup

The endpoint supports two lookup methods:
- **By Session ID** - Use `session_id` parameter to get a specific session
- **By Service Name** - Use `service_name` parameter to get the most recent session for that service

If both parameters are provided, `session_id` takes precedence.

## Container Sessions

Sessions allow users to establish interactive connections to running containers for:
- **Debugging applications** - Inspect running processes and logs
- **Troubleshooting issues** - Examine container filesystem and configuration  
- **Interactive shell access** - Execute commands inside containers
- **Performance monitoring** - Monitor container resource usage

## Access Requirements

- **SSH Key Download Permission** - User must have SSH key download permissions on the stack
- **Container Stacks Only** - Sessions are only available for container-based stacks
- **Active Sessions** - Returns information about currently active sessions

## Connection Information

The response includes connection details needed to establish the session:
- Connection host and port
- Authentication credentials
- Container and service identifiers
- Session status and metadata

<Callout type="warning" title="Container Stacks Only">
This endpoint only works with container-based stacks. Traditional server stacks do not support container sessions.
</Callout>

## Error Responses

<ResponseCodes 
  codes={[400]} 
  overrides={{
    400: [
      "Insufficient permissions - User lacks SSH key download permissions",
      "Invalid stack type - Stack is not container-based",
      "Invalid session - Session not found or inaccessible"
    ]
  }}
/>

**Related models:** Session, Stack, Service

### Parameters

- `stack_id` (string, optional) — Stack UID
- `session_id` (string, optional) — Database ID for a specific session
- `service_name` (string, optional) — Service name to get the most recent session for

### Response

```json
{
  "id": 123,
  "service_name": "web",
  "container_name": "web-container-abc123",
  "status": "active",
  "connection_info": {
    "host": "session.cloud66.com",
    "port": 22,
    "username": "session_user"
  },
  "created_at": "2023-01-15T10:30:00Z",
  "updated_at": "2023-01-15T10:30:00Z"
}
```

---

## Create Container Session

URL: https://developers.cloud66.com/v3/endpoints/sessions/#create
Endpoint: POST /stacks/:stack_id/sessions
OAuth scope: redeploy

# Create Container Session

Creates a new interactive container session for the specified service. This enables debugging and troubleshooting by providing shell access to running containers.

## Session Creation Process

1. **Validation** - Verifies user permissions and stack type
2. **Service Verification** - Confirms the service exists and is running
3. **Session Limits** - Checks current session count (max 15 per service)
4. **Async Creation** - Starts session creation as a background task
5. **Connection Setup** - Establishes secure connection to container

## Session Management

- **Session Limits** - Maximum of 15 concurrent sessions per service
- **Automatic Cleanup** - Oldest sessions are stopped when limit is exceeded
- **Background Processing** - Session creation is handled asynchronously
- **Secure Access** - Sessions use secure authentication mechanisms

## Use Cases

- **Application Debugging** - Inspect running applications and processes
- **Log Investigation** - Examine application and system logs directly
- **Configuration Changes** - Temporary configuration modifications for testing
- **Performance Analysis** - Monitor resource usage and system performance
- **Troubleshooting** - Diagnose issues in production environments

## Session Lifecycle

1. **Pending** - Session creation initiated but not yet ready
2. **Active** - Session is established and ready for use
3. **Stopped** - Session has been terminated or expired
4. **Failed** - Session creation or maintenance failed

## Access Requirements

- **SSH Key Download Permission** - User must have SSH key download permissions
- **Container Stacks Only** - Sessions are only supported on container-based stacks
- **Valid Service** - Specified service must exist in the active rollout variant

<Callout type="info" title="Asynchronous Operation">
Session creation is performed asynchronously. Monitor the returned AsyncAction to track session creation progress.
</Callout>

## Error Responses

<ResponseCodes 
  codes={[400]} 
  overrides={{
    400: [
      "Insufficient permissions - User lacks SSH key download permissions",
      "Invalid stack type - Stack is not container-based", 
      "Invalid service - Service not found in active rollout variant",
      "Too many session open! - Maximum concurrent sessions exceeded",
      "Invalid session - Session creation failed"
    ]
  }}
/>

**Related models:** Session, AsyncAction, Stack, Service

### Parameters

- `stack_id` (string, optional) — Stack UID
- `service_name` (string, optional) — Name of the service to create a session for

### Request body

```json
{
  "service_name": "web"
}
```

### Response

```json
{
  "id": 456,
  "user_id": 123,
  "resource_type": "stack",
  "action": "create_session",
  "status": "pending",
  "started_at": "2023-01-15T10:30:00Z",
  "finished_at": null,
  "created_at": "2023-01-15T10:30:00Z",
  "updated_at": "2023-01-15T10:30:00Z"
}
```