IMimprovado
Automated Recipes

Start a recipe build

Starts a build of a configured recipe and answers 202 straight away with the recipe, whose last_build_at is the moment the build started. The request has no body.

The build runs in the background. Poll GET /api/v3.1/automated-recipes/{recipe_id}/ until state is ready_to_work or failed. There is no hard limit on how long a build takes, but in practice it finishes within 120 minutes; if there is still no outcome well after that, contact support with the x-im-trace-id of one of your requests.

ready_to_work means built, not built completely: a build runs on the extractions that delivered, so read degraded and sources as well. A recipe that has not been configured with PUT cannot be built and answers 409 recipe_not_configured. Starting a second build while one is running answers 409 build_already_running.

Use this operation again after a failed build, once the reason in error has been dealt with, and to pick up data that arrived late.

post/api/v3.1/automated-recipes/{recipe_id}/build/

Request

Path parameters

recipe_idstring required

Recipe identifier, as returned when the recipe was created. A string of digits.

Response

The build was accepted and is running. The recipe comes back as it stands right now, with last_build_at set to the moment the build started.

recipe_idstring

Recipe identifier. A string, even though it is made of digits.

template_idinteger

The template this recipe was created from.

template_titlestring

Current name of that template.

titlestring

Recipe name. When you create a recipe without a title, the template supplies the default.

workspace_idinteger

The workspace this recipe lives in.

state'extracting_data' | 'building_dependencies' | 'ready_to_work' | 'failed'

Where the recipe stands. extracting_data - data is being collected; building_dependencies - the tables are being built; ready_to_work - the last build finished and the output table can be queried; failed - the last build failed, see error. ready_to_work means built, not built completely: it is built from the extractions that delivered, and how complete that is shown by degraded and sources. New values can be added, so tolerate unknown ones.

degradedboolean nullable

Whether the last build was incomplete. Only meaningful while state is ready_to_work: in every other state, a failed recipe and a running build included, it is false. true - the build left something out, either a whole data source or some extractions; see not_delivered_reasons and sources. false - everything in the build delivered. null - the completeness of the last build is unknown because that build ran before version 3.1.

not_delivered_reasonsstring[]

The distinct reasons behind an incomplete last build, sorted and deduplicated across all data sources. Empty when degraded is false or null.

datatable_idinteger nullable

The recipe's output data table, or null while none is registered. Resolve the physical table name with GET /api/v3/data-tables/{data_table_id} instead of deriving it from a title.

last_build_atstring date-time nullable

When the last build of this recipe was started, no matter what started it. null means the recipe has never been built. For recipes last built before version 3.1 this is an approximation: the time the recipe record last changed, which is often the end of that build rather than its start.

created_atstring date-time

When the recipe was created.

updated_atstring date-time

When the recipe itself last changed. It says nothing about builds - for those use last_build_at and state.

data_sourcesstring[]

Data source names the recipe is configured for, sorted. Empty on a recipe that has been created but not configured yet.

allowed_data_sourcesstring[]

Data source names the template allows, sorted. Everything in data_sources has to come from this list.

sync_from_datestring date

The date the recipe collects data from. Always set in a response, even though it may be omitted from a configuration request.

Changes

No recorded changes to this operation across all 1 revision of this API.