---
title: "JobClient.query"
description: "Query jobs in the specified interval."
image: "https://tilebox.com/images/tilebox-docs-social-preview.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://tilebox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JobClient.query

import { Fragment } from "astro/jsx-runtime";

import ApiReference from "@docs/components/ApiReference.astro";

import ParamField from "@docs/components/ParamField.astro";

```python
def JobClient.query(
    temporal_extent: TimeIntervalLike | IDIntervalLike,
    automation_ids: UUID | list[UUID] | None = None,
    job_states: JobState | list[JobState] | None = None,
    name: str | None = None,
    task_states: TaskState | list[TaskState] | None = None,
    clusters: Cluster | str | list[Cluster | str] | None = None,
) -> list[Job]
```

Query jobs in the specified interval.

## Parameters

**temporal_extent**

type: TimeIntervalLike | IDIntervalLike

required: true

The temporal extent to filter jobs by. If an `IDInterval` is given, jobs are filtered by their job id instead of their creation time.
It can be specified in the following ways:
- TimeInterval: interval -> Use the time interval as its given
- DatetimeScalar: [time, time] -> Construct a TimeInterval with start and end time set to the given
value and the end time inclusive
- tuple of two DatetimeScalar: [start, end) -> Construct a TimeInterval with the given start and
end time
- `IDInterval`: interval -> Use the ID interval as its given
- tuple of two UUIDs: [start, end) -> Construct an `IDInterval` with the given start and end id
- tuple of two strings: [start, end) -> Construct an `IDInterval` with the given start and end id
parsed from the strings
**automation_ids**

type: UUID | list[UUID] | None

One automation ID or a list of automation IDs to filter jobs by. If not provided, jobs from all automations are returned.
**job_states**

type: JobState | list[JobState] | None

A job state or list of job states to filter by. If specified, only jobs in any of the given states are returned.
**name**

type: str | None

A name to filter jobs by. If specified, only jobs with a matching name are returned. The name is matched using case-insensitive fuzzy search.
**task_states**

type: TaskState | list[TaskState] | None

A task state or list of task states to filter jobs by. If specified, only jobs that have at least one task in any of the given states are returned. Useful for finding jobs with [optional](/docs/workflows/concepts/tasks#optional-tasks) task failures, e.g. `task_states=TaskState.FAILED_OPTIONAL`.
**clusters**

type: Cluster | str | list[Cluster | str] | None

A cluster or list of clusters to filter jobs by. Pass actual cluster slugs or cluster objects. `None` and `[]` apply no cluster filter. Empty string cluster slugs are not accepted.

## Returns

A list of jobs.

<h2 id="request-example">Usage example</h2>

```python
jobs = job_client.query(
    ("2025-01-01", "2025-02-01")
)
jobs_on_cluster = job_client.query(
    ("2025-01-01", "2025-02-01"),
    clusters="production",
)
```

Source: https://tilebox.com/docs/api-reference/python/tilebox.workflows/JobClient.query/index.mdx