--- title: "List recipes" method: GET path: "/api/v3.1/automated-recipes/" tags: ["Automated Recipes"] --- # List recipes `GET /api/v3.1/automated-recipes/` ## Request - Base URL: `https://embedded.improvado.io` - URL: `https://embedded.improvado.io/api/v3.1/automated-recipes/` - Auth: one of: - HTTP bearer - API key in cookie `dts_session_id` - TypeScript: (a function with typed inputs; its response is checked against the schema) Lists the automated recipes of the workspace the request is authenticated for, the most recently changed first. Every field you need to triage a fleet is already here: `state`, `degraded`, `not_delivered_reasons` and `error`. Read the detail of a recipe only when you need its configuration or the per-data-source breakdown. The page holds 20 recipes by default and 100 at most; `next` and `previous` are full v3.1 URLs. ## Query parameters - `template_id` integer - `state` 'extracting_data' | 'building_dependencies' | 'ready_to_work' | 'failed' - `page` integer - `page_size` integer ## Response `200` One page of recipes - RecipePageV31: One page of recipes. - `count` integer: Total number of recipes matching the request. - `next` string, nullable: Full URL of the next page, or `null` on the last page. - `previous` string, nullable: Full URL of the previous page, or `null` on the first page. - `results` RecipeListItemV31[]: Recipes on this page. - `recipe_id` string: Recipe identifier. A string, even though it is made of digits. - `template_id` integer: The template this recipe was created from. - `template_title` string: Current name of that template. - `title` string: Recipe name. When you create a recipe without a title, the template supplies the default. - `workspace_id` integer: 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. - `degraded` boolean, 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_reasons` string[]: The distinct reasons behind an incomplete last build, sorted and deduplicated across all data sources, so that you can triage a fleet of recipes from the list alone. Empty when `degraded` is `false` or `null`. - `error` RecipeBuildErrorV31, nullable: Why a build failed. On a recipe this is not `null` if and only if `state` is `failed`; on an entry of `sources` it is not `null` if and only if that entry's `status` is `failed`. Build error codes are a namespace of their own, separate from the codes of HTTP error responses - a few names appear in both. The catalogue is on the [Errors](/errors) page. - `code` string: Machine-readable build error code, for example `no_data_delivered` or `sql_object_not_found`. Branch on this, never on the message. New codes can be added, so tolerate unknown ones. - `message` string: Public human-readable text: a fixed sentence for our own codes, and the cleaned-up message of the database for SQL failures. It never carries raw internal output, and its wording is not part of the contract. - `stage` 'extraction' | 'transformation_build' | 'final_build' | 'null', nullable: Which phase of the build failed: `extraction` while data was being collected, `transformation_build` while an intermediate step was built, `final_build` while the output table was built. `null` when the failure was recorded without a phase. - `data_source` string, nullable: The data source this failure belongs to, or `null` when it belongs to no single one. Inside `sources` it always matches that entry's `data_source`. - `occurred_at` string, date-time, nullable: When the failure was recorded, or `null` when no time was stored with it. - `details` object: Extra data for this code, always an object; `{}` for codes that carry none. See [Errors](/errors) for the shape per code. - `datatable_id` integer, 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_at` string, 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_at` string, date-time: When the recipe was created. - `updated_at` string, date-time: When the recipe itself last changed. It says nothing about builds - for those use `last_build_at` and `state`. ## Other responses - `400`: A query parameter has a value this operation does not accept, or the request could not be processed at all. `bad_request` is the catch-all code for a 4xx that has no code of its own, so the same envelope can arrive with another 4xx status, for example 415. - `401`: The bearer token is missing, invalid or expired - `403`: The caller is authenticated but this operation is not available to them - `405`: The HTTP method is not supported on this path - `500`: Something failed on our side. The request was not served; retry later. - `503`: Temporarily unavailable. The response carries the header `Retry-After: 30`, so wait 30 seconds and repeat the request. --- [API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)