# Pausable tracks
{% hint style="info" %}
## This feature is currently in closed beta. We're not currently accepting new beta customers. When the closed beta period has ended, and we're able to onboard more customers, we will update this status.
{% endhint %}
## Requirements
#### Supported Resources
The track must use only virtual machines (no containers or website services)
| Resource Type | Pausable | Notes |
| ---------------- | ---------- | ---------------------------------------- |
| Virtual Machines | ✅ Yes | Fully supported - VMs suspend and resume |
| Containers | ❌ No | Not supported - prevents pausability |
| Website Services | ❌ No | Not supported - prevents pausability |
| Cloud Accounts | ⚠️ Partial | Remain active while paused (incur costs) |
## How to use
Using the Instruqt UI or CLI, you can configure pausable tracks:
* **Per track**: Enable pausing for the entire track
* **Per invite or landing page**: Override the track setting when sharing content (This is only possible if the original track has pausing enabled and it meets the requirements above)
{% tabs %}
{% tab title="🌐 Web UI" %}
**For the track:**
1. Select the track you wish to make pausable
2. Navigate to the **Settings** page
3. In the **Track Details** section, locate **"Users can pause track"**
4. Toggle the switch to enable pausing
5. Set the **Maximum pause duration** (1-60 days, default is 7)
6. Click **Save**
**For invites and landing pages:**
See the [Track invites](/tracks/share/track-invite-links.md) and [Landing pages](/tracks/share/landing-pages.md) documentation for configuring pausable tracks when sharing content.
{% endtab %}
{% tab title="💻 Instruqt CLI" %}
1. If you have not already done so, pull the track you wish to make pausable:
```bash
instruqt track pull
```
2. Open the `track.yml` file and add the pausable parameters:
```yaml
pausable:
pausable_ttl: # in seconds
```
* Set `pausable` to `true` to enable pausing
* Set `pausable_ttl` to the maximum pause duration in seconds (e.g., 604800 for 7 days)
As an example, the file might look like the following:
```yaml
slug: example-track
id: xnlauwy2zewf
title: Example Track
...
pausable: true
pausable_ttl: 604800 # 7 days in seconds
```
3. From within the track directory, push the update to Instruqt:
```bash
instruqt track push
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
**Cloud Account Costs**: Cloud accounts (AWS, Azure, GCP) remain active while paused and continue to incur costs. Plan accordingly and communicate this to learners.
{% endhint %}
## Learner Experience
#### Pausing a Track
When learners are in a pausable track, they will see a **"Pause and exit"** button in the track interface.
1. Learner clicks "Pause and exit" button
2. The track enters the "pausing" state (this takes a few minutes)
3. Virtual machines are suspended
4. Progress and state are preserved
5. The learner is redirected to the splash screen
#### Resuming a Track
1. Access the track URL or navigate from an invite or landing page
2. Click the **"Resume"** button on the splash screen
3. The track enters the "resuming" state
4. Virtual machines are restored
5. Continue from the last accessed challenge
{% hint style="info" %}
**Resume Time**: Resuming typically takes 1-3 minutes as VMs are restored to their previous state.
{% endhint %}
### Automatic Pausing on Idle
For pausable tracks, the idle timeout system automatically pauses tracks instead of stopping them when learners become inactive:
* **Idle Detection**: When a pausable track exceeds its idle timeout without activity
* **Automatic Pause**: The system pauses the track rather than stopping it completely
* **Resource Optimization**: VMs are suspended to save resources while preserving state
* **Resume on Return**: Learners can resume from where they left off when they return
**Required Settings for Automatic Idle Pausing:**
1. **Track must be pausable**: Set `pausable: true` in track configuration
2. **Pause TTL must be configured**: Set `pausable_ttl` > 0 (e.g., 604800 for 7 days)
3. **Idle timeout must be set**: Configure `idle_timeout` in track settings (in seconds)
4. **Track must use only VMs**: No containers or website services
When all these conditions are met, the idle service will automatically pause the track instead of stopping it when the idle timeout is exceeded.
### Pause Duration Reset Behavior
When you pause a track after resuming it, the pause duration timer resets to the full maximum configured value. This means:
* **Fresh timer on each pause**: Every time you pause, you get the full pause duration allowance
* **Example**: If the maximum pause duration is set to 7 days:
* You pause for 3 days, then resume
* When you pause again, you have another full 7 days available (not the remaining 4 days)
* **TTL limitation**: While each pause resets the duration, you are still bound by the overall track Time-To-Live (TTL)
* If you repeatedly pause and resume, the track will eventually expire based on its total TTL
### Track States
Pausable tracks introduce additional states:
| State | Description |
| ---------- | ------------------------------------------ |
| `pausing` | Track is being paused (VMs are suspending) |
| `paused` | Track is paused and can be resumed |
| `resuming` | Track is being resumed (VMs are restoring) |
### FAQs
Can all tracks be made pausable?
No, only tracks that exclusively use virtual machines can be made pausable. Tracks containing containers or website services cannot be paused due to technical limitations. Cloud accounts can be used, but they will remain active while paused.
What happens to cloud accounts when a track is paused?
Cloud accounts (AWS, Azure, GCP) remain active while paused and continue to incur costs. Only the virtual machines are suspended. Communicate this to learners, and consider using lifecycle scripts to minimize resource usage while paused.
How long can a track remain paused?
You can configure the maximum pause duration (TTL) from 1 to 60 days. The default is 7 days. After the TTL expires, the track will be automatically cleaned up and the learner will need to start over.
Can learners pause tracks in embed mode?
No, the pause/resume functionality is not available in embed mode. Learners must access the track through a direct link, invite, or landing page to use the pause feature.
## Limitations
#### Technical Limitations
* **Container-based tracks** cannot be paused
* **Website services** prevent pausability
* **Embed mode** does not support pause/resume
* **Maximum pause duration** is 60 days
## Troubleshooting
#### Common Issues
**"Users can pause track" toggle is disabled**
* Check whether the track contains containers or website services
* Remove non-VM resources to enable pausability
**Pause button not appearing**
* Verify that the track is configured as pausable
* Check that the user is not in embed mode
**Resume fails or takes too long**
* Check whether the pause TTL has expired
* Verify that VM resources are available
## API Reference
For programmatic access to the pausable tracks functionality, see the [Instruqt GraphQL API documentation](/settings/platform/api.md).
Key operations include:
* **Query track pausability**: Check if a track is pausable and its configuration
* **Pause play mutation**: Pause a learner's track progress
* **Resume play mutation**: Resume a paused track
* **Track status**: Monitor track states including `pausing`, `paused`, and `resuming`
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.instruqt.com/tracks/manage/pausable-tracks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.