---
title: "Schedule a task for an entity."
method: POST
path: "/management/v1/warehouse/{warehouse_id}/task-queue/expire_snapshots/schedule"
tags: ["tasks"]
---

# Schedule a task for an entity.

`POST /management/v1/warehouse/{warehouse_id}/task-queue/expire_snapshots/schedule`

## Request

- Base URL: `https://localhost`
- URL: `https://localhost/management/v1/warehouse/{warehouse_id}/task-queue/expire_snapshots/schedule`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api/docs/management/v1/warehouse/:warehouse_id/task-queue/expire_snapshots/schedule/post.ts> (a function with typed inputs; its response is checked against the schema)

Pre-checks run against the warehouse config and target entity
properties before the task is enqueued. A failure surfaces as `400`
with a specific error code (see the operator guide for the full set
of pre-check codes).

When a task is already active for the same (warehouse, entity,
queue) triple, the call returns `409 TaskAlreadyActive` with the
existing `task-id` in the body — chain to `POST /task/control`
with `run-now` or `run-at` to retime it without an extra
`task/list` round-trip.

## Path parameters

- `warehouse_id` string, uuid, required

## Request body

- ScheduleExpireSnapshotsTaskRequest: Request body for scheduling a task.
  - `entity` union, required
    - object
      - `table-id` string, uuid, required
      - `type` 'table', required
    - object
      - `type` 'view', required
      - `view-id` string, uuid, required
    - object
      - `generic-table-id` string, uuid, required
      - `type` 'generic-table', required
  - `scheduled-for` string, date-time, nullable: When the task should run. Omit (or pass `null`) to run on the next worker poll. RFC 3339 / ISO 8601 format. Must be within roughly one year of now; further-out values return `400 ScheduledForTooFarInFuture`.

## Response `200`

Task scheduled

- ScheduleTaskResponse: Response returned on a successful schedule call.
  - `task-id` string, uuid, required: The id of the newly scheduled task.

## Other responses

- `400`: Pre-check failed (e.g. scheduling disabled at the warehouse, entity opted out, unsupported entity type) or the request violates a shape limit (e.g. scheduled-for too far in the future).
- `404`: Target entity not found in this warehouse.
- `409`: A task is already active for this (warehouse, entity, queue). The error message includes the existing task-id; retime or cancel via POST /task/control.
- `4XX`

---

[API](https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api.md) - [All operations](https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api/revisions/c5cb9a12a98c?raw)