---
title: "Job queue SDK reference"
description: "Customer-hosted cloud features"
---

# Job queue SDK reference

#### Customer-hosted cloud features

:::note
Some features are only available on customer-hosted clouds. Reach out to [support@anyscale.com](mailto:support@anyscale.com) for info.
:::

## Job queue SDK

### `anyscale.job_queue.list`

List job queues or fetch a single job queue by ID.

**Arguments**

-   **`job_queue_id` (str | None) = None**: If provided, fetches only the job queue with this ID.
-   **`name` (str | None) = None**: Filter by job queue name.
-   **`creator_id` (str | None) = None**: Filter by the user ID of the creator.
-   **`cloud` (str | None) = None**: Filter by cloud name.
-   **`project` (str | None) = None**: Filter by project name.
-   **`cluster_status` (str | None) = None**: Filter by the state of the associated cluster.
-   **`tags_filter` (Dict\[str, List\[str\]\] | None) = None**: Filter by tags. Accepts dict\[key\] -> List\[values\] or list\['key:value'\] entries.
-   **`page_size` (int | None) = None**: Number of items per API request page.
-   **`max_items` (int | None) = None**: Maximum total number of items to return.
-   **`sorting_directives` (List\[str\] | None) = None**: List of directives to sort the results.
-   **`include_archived` (bool) = False**: If True, include archived job queues in the search. Ignored when using job\_queue\_id.

**Returns**: ResultIterator\[[JobQueueStatus](#jobqueuestatus)\]

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Example: List the first 50 job queues
for jq in anyscale.job_queue.list(max_items=50):
    print(jq.id, jq.name, jq.state)
```
:::

::::

### `anyscale.job_queue.status`

Get the status and details for a specific job queue.

**Arguments**

-   **`job_queue_id` (str | None) = None**: The unique ID of the job queue.
-   **`name` (str | None) = None**: The name of the job queue (alternative to job\_queue\_id).
-   **`project` (str | None) = None**: The project name to filter by when using name.
-   **`cloud` (str | None) = None**: The cloud name to filter by when using name.
-   **`include_archived` (bool) = False**: If True, include archived job queues when searching by name. Ignored when using job\_queue\_id.

**Returns**: [JobQueueStatus](#jobqueuestatus)

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Get status by ID
status = anyscale.job_queue.status(job_queue_id="jobq_abc123")
print(status)

# Get status by name
status = anyscale.job_queue.status(name="my-queue")
print(status)
```
:::

::::

### `anyscale.job_queue.update`

Update a job queue.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to update.
-   **`job_queue_name` (str | None) = None**: Name of the job queue to update (alternative to ID).
-   **`project` (str | None) = None**: Project name (required when using job\_queue\_name).
-   **`cloud` (str | None) = None**: Cloud name (required when using job\_queue\_name).
-   **`max_concurrency` (int | None) = None**: New maximum concurrency value.
-   **`idle_timeout_s` (int | None) = None**: New idle timeout in seconds.

**Returns**: [JobQueueStatus](#jobqueuestatus)

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

updated_jq = anyscale.job_queue.update(job_queue_id="jobq_abc123", max_concurrency=5)
print(updated_jq)
```
:::

::::

### `anyscale.job_queue.archive`

Archive (seal) a job queue. No new jobs can be submitted.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to archive (alternative to name).
-   **`name` (str | None) = None**: Name of the job queue to archive (alternative to ID).
-   **`project` (str | None) = None**: Project name (required when using name).
-   **`cloud` (str | None) = None**: Cloud name (required when using name).

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Archive by ID
anyscale.job_queue.archive(job_queue_id="jq_abc123")

# Archive by name (requires project and cloud)
anyscale.job_queue.archive(name="my-queue", project="my-project", cloud="my-cloud")
```
:::

::::

### `anyscale.job_queue.terminate`

Terminate a job queue and all its pending/running jobs.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to terminate (alternative to name).
-   **`name` (str | None) = None**: Name of the job queue to terminate (alternative to ID).
-   **`project` (str | None) = None**: Project name (required when using name).
-   **`cloud` (str | None) = None**: Cloud name (required when using name).
-   **`include_archived` (bool) = False**: If True, include archived job queues when searching by name. Ignored when using job\_queue\_id.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Terminate by ID
anyscale.job_queue.terminate(job_queue_id="jq_abc123")

# Terminate by name (requires project and cloud)
anyscale.job_queue.terminate(name="my-queue", project="my-project", cloud="my-cloud")
```
:::

::::

### `anyscale.job_queue.delete`

Delete a job queue.

Jobs previously submitted to the queue remain accessible. The job queue must have all jobs in terminal state and no running clusters. This action cannot be undone.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to delete (alternative to name).
-   **`name` (str | None) = None**: Name of the job queue to delete (alternative to ID).
-   **`project` (str | None) = None**: Project name (required when using name).
-   **`cloud` (str | None) = None**: Cloud name (required when using name).
-   **`include_archived` (bool) = False**: If True, include archived job queues when searching by name. Ignored when using job\_queue\_id.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Delete by ID
anyscale.job_queue.delete(job_queue_id="jq_abc123")

# Delete by name (requires project and cloud)
anyscale.job_queue.delete(name="my-queue", project="my-project", cloud="my-cloud")
```
:::

::::

### `anyscale.job_queue.add_tags`

Upsert tags for a job queue.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to tag (alternative to name).
-   **`name` (str | None) = None**: Name of the job queue to tag (alternative to ID).
-   **`tags` (Dict\[str, str\])**: Key/value tags to upsert as a map {key: value}.

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

anyscale.job_queue.add_tags(job_queue_id="jobq_abc123", tags={"team": "mlops"})
```
:::

::::

### `anyscale.job_queue.remove_tags`

Remove tags by key from a job queue.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to modify (alternative to name).
-   **`name` (str | None) = None**: Name of the job queue to modify (alternative to ID).
-   **`keys` (List\[str\])**: List of tag keys to remove.

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

anyscale.job_queue.remove_tags(job_queue_id="jobq_abc123", keys=["team"])
```
:::

::::

### `anyscale.job_queue.list_tags`

List tags for a job queue as a key/value mapping.

**Arguments**

-   **`job_queue_id` (str | None) = None**: ID of the job queue to read tags (alternative to name).
-   **`name` (str | None) = None**: Name of the job queue to read tags (alternative to ID).

**Returns**: Dict\[str, str\]

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

tags: dict[str, str] = anyscale.job_queue.list_tags(name="my-queue")
```
:::

::::

## Job queue models

### `JobQueueStatus`

Represents the status and details of a Job Queue.

#### Fields

-   **`id` (str)**: Unique ID of the job queue.
-   **`state` (str)**: Current state of the job queue.
-   **`name` (str | None)**: Name of the job queue.
-   **`creator_email` (str | None)**: Email of the user who created the job queue.
-   **`project_id` (str | None)**: ID of the project this job queue belongs to.
-   **`created_at` (datetime | None)**: Timestamp when the job queue was created.
-   **`max_concurrency` (int | None)**: Maximum number of jobs allowed to run concurrently.
-   **`idle_timeout_s` (int | None)**: Idle timeout in seconds before the queue's cluster may shut down.
-   **`user_provided_id` (str | None)**: User provided identifier of the job queue.
-   **`execution_mode` (str | None)**: The execution mode of the job queue.
-   **`creator_id` (str | None)**: Identifier of user who created the job queue.
-   **`cloud_id` (str | None)**: The cloud ID associated with the job queue.
-   **`total_jobs` (int | None)**: Total number of jobs in the job queue.
-   **`successful_jobs` (int | None)**: Number of successful jobs in the job queue.
-   **`failed_jobs` (int | None)**: Number of failed jobs in the job queue.
-   **`active_jobs` (int | None)**: Number of active jobs in the job queue.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.job_queue.models import JobQueueStatus

status = JobQueueStatus(
    id="jq_123",
    state="ACTIVE",
    name="my-queue",
    max_concurrency=5,
    idle_timeout_s=300,
)
```
:::

::::

### `JobQueueState`

Current state of a job queue.

#### Values

-   **`ACTIVE`**: The job queue is active and accepting jobs.
-   **`SEALED`**: The job queue is sealed and not accepting new jobs. It may still be processing existing jobs.
-   **`UNKNOWN`**: The state of the job queue is unknown or could not be determined.

### `ExecutionMode`

Execution mode of a job queue.

#### Values

-   **`FIFO`**: FIFO execution mode.
-   **`LIFO`**: LIFO execution mode.
-   **`PRIORITY`**: Priority-based execution mode.
-   **`UNKNOWN`**: Unknown execution mode.

### `ClusterState`

Possible states for a cluster.

#### Values

-   **`RUNNING`**: The cluster is running.
-   **`TERMINATED`**: The cluster is terminated.
-   **`PENDING`**: The cluster is pending creation.
-   **`UNKNOWN`**: The state of the cluster is unknown.

### `JobQueueSortField`

Fields available for sorting job queues.

#### Values

-   **`ID`**: Sort by Job Queue ID.
-   **`NAME`**: Sort by Job Queue name.
-   **`CREATED_AT`**: Sort by creation timestamp.
-   **`CREATOR_ID`**: Sort by the ID of the creator.
-   **`CREATOR_EMAIL`**: Sort by the email of the creator.
-   **`PROJECT_ID`**: Sort by the Project ID.
-   **`CLOUD_ID`**: Sort by the Cloud ID.
-   **`QUEUE_STATE`**: Sort by the Job Queue's state (ACTIVE, SEALED).
-   **`CLUSTER_STATE`**: Sort by the state of the associated cluster.

### `JobQueueSortDirective`

Directive for sorting job queue results.

#### Fields

-   **`sort_field` ([JobQueueSortField](#jobqueuesortfield) | str)**: The field to sort by.
-   **`sort_order` ([SortOrder](#sortorder) | str)**: The sort order (ASC or DESC).

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from anyscale.job_queue.models import JobQueueSortDirective, JobQueueSortField, SortOrder

# Create a sort directive
sort_directive = JobQueueSortDirective(
    sort_field=JobQueueSortField.CREATED_AT,
    sort_order=SortOrder.DESC
)
```
:::

::::

### `SortOrder`

Sort order for queries.

#### Values

-   **`ASC`**: Ascending order.
-   **`DESC`**: Descending order.

### `SessionState`

State of a cluster/session.

#### Values

-   **`Stopped`**: The cluster is stopped.
-   **`Terminated`**: The cluster is terminated.
-   **`StartingUp`**: The cluster is starting up.
-   **`StartupErrored`**: The cluster encountered an error during startup.
-   **`Running`**: The cluster is running.
-   **`Updating`**: The cluster is being updated.
-   **`UpdatingErrored`**: The cluster encountered an error during update.
-   **`Stopping`**: The cluster is stopping.
-   **`Terminating`**: The cluster is terminating.
-   **`AwaitingStartup`**: The cluster is awaiting startup.
-   **`AwaitingFileMounts`**: The cluster is awaiting file mounts.
-   **`TerminatingErrored`**: The cluster encountered an error during termination.
-   **`StoppingErrored`**: The cluster encountered an error while stopping.

---

Previous: [Image](/reference/sdk/image.md) | Next: [Job](/reference/sdk/job.md)