Receiving model API results

Solving a planning problem with Timefold is an asynchronous operation. Your application submits a dataset and then receives the result when solving is complete, which may take anywhere from seconds to minutes depending on the size and complexity of the problem. Your application doesn’t wait for the solution; it continues working and handles the results when they arrive.

The integration has three steps:

  1. Submit: your application POSTs the planning problem as a JSON dataset to the model API. Timefold returns a dataset ID synchronously.

  2. Wait: Timefold validates, queues, and solves the dataset asynchronously. Your application receives a notification when solving completes (via webhook or SSE), or polls for the status.

  3. Fetch: your application GETs the solution using the dataset ID and processes the result.

Sequence diagram showing the three-step Submit/Wait/Fetch integration pattern between your application and the Timefold Platform

See Model API usage for API key setup and the model API endpoints. See Dataset lifecycle for the full set of dataset statuses.

You have three options for step two of the integration:

  • Webhooks: Timefold calls a URL in your application when solving completes.

  • Server-Sent Events: your application opens a streaming connection to Timefold and receives an event when solving completes.

  • Polling: your application periodically checks Timefold for the status of the dataset until solving completes

Choosing your approach

Webhooks SSE Polling

Recommended for production

Yes

No

No

Recommended for development

No

Yes

No

Requires public endpoint on your side

Yes

No

No

Holds an open connection

No

Yes

No

Real-time progress updates

No

Yes

No

Works in air-gapped / self-hosted

Yes (internal network)

Yes

Yes