Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
  • Platform
Try models
  • Timefold Platform
  • How-tos
  • Dataset lifecycle

Timefold Platform

    • Introduction
    • Planning AI concepts
    • Getting started with the Timefold Platform
    • Platform concepts
    • Models
      • Model catalog and documentation
      • Model versioning and maturity
      • Trialing Timefold models
    • How-tos
      • Dataset lifecycle
      • Interpreting dataset results
      • Configuration parameters and profiles
      • Searching and categorizing datasets for auditability
      • Member management and roles
      • Using the maps service
      • Comparing datasets (preview)
      • Real-time planning with /from-patch (preview)
    • Job-oriented guides
      • Balancing different optimization goals
      • Validating an optimized plan with Explainable AI
      • Uncovering inefficiencies in operational planning
      • Responding to disruptions with real-time planning
      • Designing better routing plans with (just enough) traffic awareness
    • API integration
      • API usage
      • Webhooks
    • Changelog
    • Feature requests
    • Self-Hosted
      • Self-Hosted vs. Timefold Cloud Platform
      • Installation instructions
      • Troubleshooting
    • Trust
      • Risk profile
      • Product security
      • Data security
      • Legal and privacy
      • AI legislation compliance
      • Trust center

Dataset lifecycle

In this document you will learn about the statuses during solving and the solving lifecycle. (The dataset status is indicated on the top right in the sidebar in the Platform UI, or by the solverStatus field in the API.)

Dataset statuses

A dataset can be in one of several states:

Status Description API value

Dataset created

A new dataset has been created from a new input dataset or a patch to an existing dataset.

DATASET_CREATED

Dataset validated

The dataset has been validated.

DATASET_VALIDATED

Dataset invalid

The submitted dataset was invalid.

DATASET_INVALID

Dataset computed

The score analysis and KPIs for the dataset have been computed before solving. This can be useful for datasets that already include partial solutions (e.g. employees assigned to shifts, vehicles assigned to visits).

DATASET_COMPUTED

Scheduled

The data is in the queue to be solved.

SOLVING_SCHEDULED

Started

The input dataset is being converted into the planning problem and augmented with additional information, such as distance matrix (if applicable).

SOLVING_STARTED

Solving

The planning problem is currently being solved.

SOLVING_ACTIVE

Incomplete

A full solution was not found before the run was terminated.

SOLVING_INCOMPLETE

Completed

Solving has completed and no further solution will be generated.

SOLVING_COMPLETED

Failed

An error has occurred and solving was unsuccessful.

SOLVING_FAILED

Typical lifecycle

When you submit a dataset you can specify if solving should start (?operation=SOLVE) or not (?operation=NONE), by appending the query parameter to the API endpoint. If omitted, SOLVE is the default.

The solving status can become "Failed" because of errors at any stage.

The "Dataset created" and "Solving scheduling" (when solving is requested) occur synchronously and are triggered by the API call.

The other statuses occur asynchronously as resources become available.

There are 3 possible scenarios:

1. Submit the dataset and do not solve

  • Synchronously.

    1. Dataset created.

  • Asynchronously

    1. Dataset validated.

    2. Dataset computed.

2. Submit the dataset and start solving

  • Synchronously.

    1. Dataset created.

    2. Solving scheduled.

  • Asynchronously

    1. Dataset validated.

    2. Dataset computed.

    3. Solving started.

    4. Solving active.

    5. Solving completed.

3. Submit the dataset and do not solve followed by a second call to start solving

First operation "NONE":

  • Synchronously.

    1. Dataset created.

    2. Dataset validated.

  • Asynchronously

    1. Dataset computed.

Second operation "SOLVE":

  • Synchronously.

    1. Solving scheduled.

  • Asynchronously

    1. Solving started.

    2. Solving active.

    3. Solving completed.

Actions

Cancelling a solve: When a dataset that is being solved is Cancelled (via the Platform UI or the API) it goes from the current state to either "Incomplete" or "Completed".

Solving restarted

Sometimes solving may need to restart because of an error or the availability of resources.

When this happens, you can expect the following:

  • Logs will show the appended logs of the previous solving process (unless the previous log is unavailable).

  • The "submitted time" or "active time" of the solve is not reset to the time of the restart. The original times are preserved.

  • The score graph will include events produced by all of the solves.

Webhooks

Our platform supports webhook events. Events are sent during the lifecycle of a dataset. See Webhooks for details.

  • © 2025 Timefold BV
  • Timefold.ai
  • Documentation
  • Changelog
  • Send feedback
  • Privacy
  • Legal
    • Light mode
    • Dark mode
    • System default