# 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)

*** ** * ** ***


```
public abstract class WorkRequest.Builder<B extends WorkRequest.Builder<@NonNull B, @NonNull ?>, W extends WorkRequest>
```

<br />

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

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

*** ** * ** ***

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

## Summary

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#addTag(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html tag)` Adds a tag for the work. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull W` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#build()()` Builds a `https://developer.android.com/reference/androidx/work/WorkRequest` based on this `https://developer.android.com/reference/androidx/work/WorkRequest.Builder`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/androidx/work/WorkRequest.Builder#keepResultsForAtLeast(java.time.Duration)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/time/Duration.html duration)` Specifies that the results of this work should be kept for at least the specified amount of time. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#keepResultsForAtLeast(kotlin.Long,java.util.concurrent.TimeUnit)(long duration, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit)` Specifies that the results of this work should be kept for at least the specified amount of time. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,java.time.Duration)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/BackoffPolicy backoffPolicy, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/time/Duration.html duration )` Sets the backoff policy and backoff delay for the work. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setBackoffCriteria(androidx.work.BackoffPolicy,kotlin.Long,java.util.concurrent.TimeUnit)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/BackoffPolicy backoffPolicy, long backoffDelay, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit )` Sets the backoff policy and backoff delay for the work. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `@https://developer.android.com/reference/androidx/work/ExperimentalWorkRequestBuilderApi https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setBackoffForSystemInterruptions()()` Specifies that the backoff policy (as specified via `https://developer.android.com/reference/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. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setConstraints(androidx.work.Constraints)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/Constraints constraints)` Adds constraints to the `https://developer.android.com/reference/androidx/work/WorkRequest`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setExpedited(androidx.work.OutOfQuotaPolicy)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/OutOfQuotaPolicy policy)` Marks the `https://developer.android.com/reference/androidx/work/WorkRequest` as important to the user. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setId(java.util.UUID)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/UUID.html id)` Sets a unique identifier for this unit of work. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull B` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setInitialDelay(java.time.Duration)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/time/Duration.html duration)` Sets an initial delay for the `https://developer.android.com/reference/androidx/work/WorkRequest`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setInitialDelay(kotlin.Long,java.util.concurrent.TimeUnit)(long duration, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit)` Sets an initial delay for the `https://developer.android.com/reference/androidx/work/WorkRequest`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setInputData(androidx.work.Data)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/Data inputData)` Adds input `https://developer.android.com/reference/androidx/work/Data` to the work. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull B` | `https://developer.android.com/reference/androidx/work/WorkRequest.Builder#setTraceTag(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html traceTag)` Specifies the name of the trace span to be used by `https://developer.android.com/reference/androidx/work/WorkManager` when executing the specified `https://developer.android.com/reference/androidx/work/WorkRequest`. |

## Public methods

### addTag

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

```
public final @NonNull B addTag(@NonNull String tag)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html tag` | A tag for identifying the work in queries. |

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

### build

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

```
public final @NonNull W build()
```

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

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

### keepResultsForAtLeast

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

```
@RequiresApi(value = 26)
public final @NonNull B keepResultsForAtLeast(@NonNull Duration duration)
```

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/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/androidx/work/WorkInfo`.

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

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

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

### keepResultsForAtLeast

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

```
public final @NonNull B keepResultsForAtLeast(long duration, @NonNull TimeUnit timeUnit)
```

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/androidx/work/WorkInfo`.

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

| Parameters |
|---|---|
| `long duration` | The minimum duration of time (in `timeUnit` units) to keep the results of this work |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit` | The unit of time for `duration` |

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

### setBackoffCriteria

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

```
@RequiresApi(value = 26)
public final @NonNull B setBackoffCriteria(
    @NonNull BackoffPolicy backoffPolicy,
    @NonNull Duration duration
)
```

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

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

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

### setBackoffCriteria

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

```
public final @NonNull B setBackoffCriteria(
    @NonNull BackoffPolicy backoffPolicy,
    long backoffDelay,
    @NonNull TimeUnit timeUnit
)
```

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/BackoffPolicy backoffPolicy` | The `https://developer.android.com/reference/androidx/work/BackoffPolicy` to use when increasing backoff time |
| `long backoffDelay` | Time to wait before retrying the work in `timeUnit` units |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit` | The `https://developer.android.com/reference/java/util/concurrent/TimeUnit.html` for `backoffDelay` |

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

### setBackoffForSystemInterruptions

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

```
@ExperimentalWorkRequestBuilderApi
public final @NonNull B setBackoffForSystemInterruptions()
```

Specifies that the backoff policy (as specified via `https://developer.android.com/reference/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/androidx/work/ListenableWorker` runs longer than it should, or when constraints defined for a given `https://developer.android.com/reference/androidx/work/ListenableWorker` are unmet.

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

| See also |
|---|---|
| `https://developer.android.com/reference/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)

```
public final @NonNull B setConstraints(@NonNull Constraints constraints)
```

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

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

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

### setExpedited

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

```
public @NonNull B setExpedited(@NonNull OutOfQuotaPolicy policy)
```

Marks the `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/work/OutOfQuotaPolicy policy` | The `https://developer.android.com/reference/androidx/work/OutOfQuotaPolicy` to be used. |

### setId

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

```
public final @NonNull B setId(@NonNull UUID id)
```

Sets a unique identifier for this unit of work.

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

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

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

### setInitialDelay

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

```
@RequiresApi(value = 26)
public @NonNull B setInitialDelay(@NonNull Duration duration)
```

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

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

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull B` | The current `https://developer.android.com/reference/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)

```
public @NonNull B setInitialDelay(long duration, @NonNull TimeUnit timeUnit)
```

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

| Parameters |
|---|---|
| `long duration` | The length of the delay in `timeUnit` units |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/TimeUnit.html timeUnit` | The units of time for `duration` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull B` | The current `https://developer.android.com/reference/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)

```
public final @NonNull B setInputData(@NonNull Data inputData)
```

Adds input `https://developer.android.com/reference/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/androidx/work/InputMerger`.

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

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

### setTraceTag

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

```
public final @NonNull B setTraceTag(@NonNull String traceTag)
```

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

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

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html traceTag` | The name of the trace tag, truncate to a `127` character string if necessary. |

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