# WorkRequest.Builder

Artifact: [androidx.work:work-runtime](https://developer.android.com/jetpack/androidx/releases/work) [View Source](https://cs.android.com/search?q=file:androidx/work/WorkRequest.kt+class:androidx.work.WorkRequest.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

*** ** * ** ***


```
abstract class WorkRequest.Builder<B : WorkRequest.Builder<B, *>, W : WorkRequest>
```

<br />

Known direct subclasses [OneTimeWorkRequest.Builder](https://developer.android.com/reference/kotlin/androidx/work/OneTimeWorkRequest.Builder), [PeriodicWorkRequest.Builder](https://developer.android.com/reference/kotlin/androidx/work/PeriodicWorkRequest.Builder)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/work/OneTimeWorkRequest.Builder` | Builder for `https://developer.android.com/reference/kotlin/androidx/work/OneTimeWorkRequest`s. |
| `https://developer.android.com/reference/kotlin/androidx/work/PeriodicWorkRequest.Builder` | Builder for `https://developer.android.com/reference/kotlin/androidx/work/PeriodicWorkRequest`s. |

*** ** * ** ***

A builder for `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`s. There are two concrete implementations of this class: `https://developer.android.com/reference/kotlin/androidx/work/OneTimeWorkRequest.Builder` and `https://developer.android.com/reference/kotlin/androidx/work/PeriodicWorkRequest.Builder`.

## Summary

| ### Public functions |
|---|---|
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#addTag(kotlin.String)(tag: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Adds a tag for the work. |
| `W` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#build()()` Builds a `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest` based on this `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder`. |
| `B` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#keepResultsForAtLeast(java.time.Duration)(duration: https://developer.android.com/reference/java/time/Duration.html)` Specifies that the results of this work should be kept for at least the specified amount of time. |
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#keepResultsForAtLeast(kotlin.Long,java.util.concurrent.TimeUnit)(duration: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html)` Specifies that the results of this work should be kept for at least the specified amount of time. |
| `B` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,java.time.Duration)(backoffPolicy: https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy, duration: https://developer.android.com/reference/java/time/Duration.html)` Sets the backoff policy and backoff delay for the work. |
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,kotlin.Long,java.util.concurrent.TimeUnit)( backoffPolicy: https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy, backoffDelay: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html )` Sets the backoff policy and backoff delay for the work. |
| `B` | `@https://developer.android.com/reference/kotlin/androidx/work/ExperimentalWorkRequestBuilderApi https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setBackoffForSystemInterruptions()()` Specifies that the backoff policy (as specified via `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,kotlin.Long,java.util.concurrent.TimeUnit)`) will be applied when work is interrupted by the system without the app requesting it. |
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setConstraints(androidx.work.Constraints)(constraints: https://developer.android.com/reference/kotlin/androidx/work/Constraints)` Adds constraints to the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`. |
| `open B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setExpedited(androidx.work.OutOfQuotaPolicy)(policy: https://developer.android.com/reference/kotlin/androidx/work/OutOfQuotaPolicy)` Marks the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest` as important to the user. |
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setId(java.util.UUID)(id: https://developer.android.com/reference/java/util/UUID.html)` Sets a unique identifier for this unit of work. |
| `open B` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setInitialDelay(java.time.Duration)(duration: https://developer.android.com/reference/java/time/Duration.html)` Sets an initial delay for the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`. |
| `open B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setInitialDelay(kotlin.Long,java.util.concurrent.TimeUnit)(duration: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html)` Sets an initial delay for the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`. |
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setInputData(androidx.work.Data)(inputData: https://developer.android.com/reference/kotlin/androidx/work/Data)` Adds input `https://developer.android.com/reference/kotlin/androidx/work/Data` to the work. |
| `B` | `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setTraceTag(kotlin.String)(traceTag: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Specifies the name of the trace span to be used by `https://developer.android.com/reference/kotlin/androidx/work/WorkManager` when executing the specified `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`. |

## Public functions

### addTag

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
fun addTag(tag: String): B
```

Adds a tag for the work. You can query and cancel work by tags. Tags are particularly useful for modules or libraries to find and operate on their own work.

| Parameters |
|---|---|
| `tag: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | A tag for identifying the work in queries. |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### build

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
fun build(): W
```

Builds a `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest` based on this `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder`.

| Returns |
|---|---|
| `W` | A `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest` based on this `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### keepResultsForAtLeast

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
@RequiresApi(value = 26)
fun keepResultsForAtLeast(duration: Duration): B
```

Specifies that the results of this work should be kept for at least the specified amount of time. After this time has elapsed, the results may be pruned at the discretion of WorkManager when this WorkRequest has reached a finished state (see `https://developer.android.com/reference/kotlin/androidx/work/WorkInfo.State#isFinished()`) and there are no pending dependent jobs.

When the results of a work are pruned, it becomes impossible to query for its `https://developer.android.com/reference/kotlin/androidx/work/WorkInfo`.

Specifying a long duration here may adversely affect performance in terms of app storage and database query time.

| Parameters |
|---|---|
| `duration: https://developer.android.com/reference/java/time/Duration.html` | The minimum duration of time to keep the results of this work |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### keepResultsForAtLeast

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
fun keepResultsForAtLeast(duration: Long, timeUnit: TimeUnit): B
```

Specifies that the results of this work should be kept for at least the specified amount of time. After this time has elapsed, the results **may** be pruned at the discretion of WorkManager when there are no pending dependent jobs.

When the results of a work are pruned, it becomes impossible to query for its `https://developer.android.com/reference/kotlin/androidx/work/WorkInfo`.

Specifying a long duration here may adversely affect performance in terms of app storage and database query time.

| Parameters |
|---|---|
| `duration: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The minimum duration of time (in `timeUnit` units) to keep the results of this work |
| `timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html` | The unit of time for `duration` |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### setBackoffCriteria

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
@RequiresApi(value = 26)
fun setBackoffCriteria(backoffPolicy: BackoffPolicy, duration: Duration): B
```

Sets the backoff policy and backoff delay for the work. The default values are `https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy#EXPONENTIAL` and WorkRequest#DEFAULT_BACKOFF_DELAY_MILLIS, respectively. `duration` will be clamped between `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest#MIN_BACKOFF_MILLIS()` and `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest#MAX_BACKOFF_MILLIS()`.

| Parameters |
|---|---|
| `backoffPolicy: https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy` | The `https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy` to use when increasing backoff time |
| `duration: https://developer.android.com/reference/java/time/Duration.html` | Time to wait before retrying the work |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### setBackoffCriteria

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
fun setBackoffCriteria(
    backoffPolicy: BackoffPolicy,
    backoffDelay: Long,
    timeUnit: TimeUnit
): B
```

Sets the backoff policy and backoff delay for the work. The default values are `https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy#EXPONENTIAL` and WorkRequest#DEFAULT_BACKOFF_DELAY_MILLIS, respectively. `backoffDelay` will be clamped between `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest#MIN_BACKOFF_MILLIS()` and `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest#MAX_BACKOFF_MILLIS()`.

| Parameters |
|---|---|
| `backoffPolicy: https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy` | The `https://developer.android.com/reference/kotlin/androidx/work/BackoffPolicy` to use when increasing backoff time |
| `backoffDelay: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | Time to wait before retrying the work in `timeUnit` units |
| `timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html` | The `https://developer.android.com/reference/java/util/concurrent/TimeUnit.html` for `backoffDelay` |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### setBackoffForSystemInterruptions

Added in [2.11.0](https://developer.android.com/jetpack/androidx/releases/work#2.11.0)

```
@ExperimentalWorkRequestBuilderApi
fun setBackoffForSystemInterruptions(): B
```

Specifies that the backoff policy (as specified via `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,kotlin.Long,java.util.concurrent.TimeUnit)`) will be applied when work is interrupted by the system without the app requesting it. This might happen when the `https://developer.android.com/reference/kotlin/androidx/work/ListenableWorker` runs longer than it should, or when constraints defined for a given `https://developer.android.com/reference/kotlin/androidx/work/ListenableWorker` are unmet.

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,kotlin.Long,java.util.concurrent.TimeUnit)` |   |

### setConstraints

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
fun setConstraints(constraints: Constraints): B
```

Adds constraints to the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`.

| Parameters |
|---|---|
| `constraints: https://developer.android.com/reference/kotlin/androidx/work/Constraints` | The constraints for the work |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### setExpedited

Added in [2.7.0](https://developer.android.com/jetpack/androidx/releases/work#2.7.0)

```
open fun setExpedited(policy: OutOfQuotaPolicy): B
```

Marks the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest` as important to the user. In this case, WorkManager provides an additional signal to the OS that this work is important.

Note that although the execution time of this work won't be counted against your app's quota while your app is in the foreground, if the expedited work continues in the background, you are susceptible to quota. However, power management restrictions, such as Battery Saver and Doze, are less likely to affect expedited work. Because of this, expedited work is best suited for short tasks which need to start immediately and are important to the user or user-initiated.

| Parameters |
|---|---|
| `policy: https://developer.android.com/reference/kotlin/androidx/work/OutOfQuotaPolicy` | The `https://developer.android.com/reference/kotlin/androidx/work/OutOfQuotaPolicy` to be used. |

### setId

Added in [2.8.0](https://developer.android.com/jetpack/androidx/releases/work#2.8.0)

```
fun setId(id: UUID): B
```

Sets a unique identifier for this unit of work.

The id can be useful when retrieving `https://developer.android.com/reference/kotlin/androidx/work/WorkInfo` by `id` or when trying to update an existing work. For example, using `https://developer.android.com/reference/kotlin/androidx/work/WorkManager#updateWork(androidx.work.WorkRequest)` requires that the work has an id.

| Parameters |
|---|---|
| `id: https://developer.android.com/reference/java/util/UUID.html` | The unique identifier for this unit of work. |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### setInitialDelay

Added in [2.1.0](https://developer.android.com/jetpack/androidx/releases/work#2.1.0)

```
@RequiresApi(value = 26)
open fun setInitialDelay(duration: Duration): B
```

Sets an initial delay for the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`.

| Parameters |
|---|---|
| `duration: https://developer.android.com/reference/java/time/Duration.html` | The length of the delay |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the given initial delay will push the execution time past `Long.MAX_VALUE` and cause an overflow |

### setInitialDelay

Added in [2.1.0](https://developer.android.com/jetpack/androidx/releases/work#2.1.0)

```
open fun setInitialDelay(duration: Long, timeUnit: TimeUnit): B
```

Sets an initial delay for the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`.

| Parameters |
|---|---|
| `duration: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The length of the delay in `timeUnit` units |
| `timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html` | The units of time for `duration` |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the given initial delay will push the execution time past `Long.MAX_VALUE` and cause an overflow |

### setInputData

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/work#1.0.0)

```
fun setInputData(inputData: Data): B
```

Adds input `https://developer.android.com/reference/kotlin/androidx/work/Data` to the work. If a worker has prerequisites in its chain, this Data will be merged with the outputs of the prerequisites using an `https://developer.android.com/reference/kotlin/androidx/work/InputMerger`.

| Parameters |
|---|---|
| `inputData: https://developer.android.com/reference/kotlin/androidx/work/Data` | key/value pairs that will be provided to the worker |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |

### setTraceTag

Added in [2.10.0](https://developer.android.com/jetpack/androidx/releases/work#2.10.0)

```
fun setTraceTag(traceTag: String): B
```

Specifies the name of the trace span to be used by `https://developer.android.com/reference/kotlin/androidx/work/WorkManager` when executing the specified `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest`.

`https://developer.android.com/reference/kotlin/androidx/work/WorkManager` uses the simple name of the `https://developer.android.com/reference/kotlin/androidx/work/ListenableWorker` class truncated to a `127` character string, as the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setTraceTag(kotlin.String)` by default.

You should override the `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder#setTraceTag(kotlin.String)`, when you are using `https://developer.android.com/reference/kotlin/androidx/work/ListenableWorker` delegation via a `https://developer.android.com/reference/kotlin/androidx/work/WorkerFactory`.

| Parameters |
|---|---|
| `traceTag: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the trace tag, truncate to a `127` character string if necessary. |

| Returns |
|---|---|
| `B` | The current `https://developer.android.com/reference/kotlin/androidx/work/WorkRequest.Builder` |