Schemas

Workspace ID

Workspace title

Number of workspaces

URL to the next page

URL to the previous page

Recipe ID

Recipe title

Dashboard ID

Dashboard title

Dashboard Data Type

string identifier of datasource

Data source title

List of categories that the data source belongs to

Number of datasources

URL to the next page

URL to the previous page

Connection ID

Connection UID

Connection title

Data source name

Connection status

Connection creation date

Connection update date

Total number of accounts available on this connection (excluding accounts disabled on the data source side).

Number of accounts on this connection that are selected for extraction. Use this to detect connections that have no accounts enabled and prompt the user to select at least one before setting up extractions or loads.

Accounts status

Last successful accounts update date

Was the last accounts update successful

Number of connections

URL to the next page

URL to the previous page

Account ID

Remote account ID

Account title

Account currency

Connection ID

Data source name

Account creation date

Account update date

Is the account active

Is the account enabled for embedded extraction

Data source-specific account item information

Number of accounts

URL to the next page

URL to the previous page

ID of the parent (global) extraction template to base this template on

Title for the new template (must be unique within the agency)

Description of the template (can be empty)

List of field names to include in the template

Extraction schedule configuration

Additional parameters for the template (e.g. time_granularity)

List of field names to hash (optional)

Limit on historical data depth in days (optional, null for no limit)

Connection ID, required for wide report templates (parent has allow_to_select_dimensions or is_created_from_wide)

Extract Template ID

Extract Template title

Extract Template description

Data class

Data source name

Whether the template is a wide report template

Schedules limit

Number of extract templates

URL to the next page

URL to the previous page

Day offset within the interval, starting from 0. The valid range depends on interval:

• hour, day — must be 0
• week — 0–6 (day of week)
• month — 0–30 (day of month)

Hour at which the run will start (0–23)

Minute of hour at which the run will start (0–59)

Frequency at which the run will be performed:

• hour — every hour
• day — once per day
• week — once per week
• month — once per month

IANA timezone name (e.g. UTC, America/New_York) the schedule is interpreted in.

How often the schedule repeats within the interval. Defaults to 1.

Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.

Field title

Field name

Field kind

Field type

Is the field selected

Can the field be edited

Sql Name of a Field

Hint on how the value is meant to be rendered — not a storage contract. Metrics fall back to float whenever a data source does not declare a format explicitly, so float does not imply the value is fractional, and no decimal precision is guaranteed: values are passed through exactly as the data source returns them, without rounding. New formats may be added over time, so treat an unrecognised value as an unformatted string rather than failing.

Is the field dynamic

Additional Params type

Additional Params name

Is the Additional Params required

Additional Params title

Additional Params description

Additional Params params

Additional Params initial value

Extract ID

Extract title

Connection ID

Account ID

Account name

Internal Improvado account entity ID.

Embedded account ID. Null if the account is not linked to an embedded account.

Extract creation date

Last sync date

Extract status

Error text

Schedules limit

Start date for historical data backfill (ISO date format, e.g. "2025-02-25"). Null if not set.

Number of extracts

URL to the next page

URL to the previous page

string identifier of destination

Destination title

Destination info

Number of destinations

URL to the next page

URL to the previous page

Destination Connection ID

Destination object

Destination Connection title

Destination Connection update date

Destination Connection status

Destination Connection error text

Is the Destination Connection editable

Create load for new tables

Number of destination connections

URL to the next page

URL to the previous page

Data Table ID

Data Table title

Data source name

Field kind

Field title

SQL name

Field type

Hint on how the value is meant to be rendered — not a storage contract. Metrics fall back to float whenever a data source does not declare a format explicitly, so float does not imply the value is fractional, and no decimal precision is guaranteed: values are passed through exactly as the data source returns them, without rounding. New formats may be added over time, so treat an unrecognised value as an unformatted string rather than failing.

Is the field dynamic

Is the field selected

Data Table title

Data Table freshness date

Data source name

Report type

Data class

Workspace ID

SQL name

Auto extract new accounts

Fields object

Number of data tables

URL to the next page

URL to the previous page

Load ID

Data Table object

Destination table name

Load run policy

Load status

Last update date

Error text

Number of uploaded rows

Number of loads

URL to the next page

URL to the previous page

List of Loads

Connection ID to use for the preview.

Custom settings for the extraction.

List of fields to include in the preview.

List of dynamic fields to include.

List of account IDs.

Custom filters to apply. Null if no filters.

Embedded account IDs to validate against the template. Must be non-empty and all accounts must belong to a single connection.

Proposed template settings to validate. Optional.

Extraction template ID.

Data source name.

Whether the template is a wide report template.

Validation error details. Empty string if no errors.

Map of incompatible fields to the list of incompatibility reasons. Empty object if all fields are compatible.

ID of the source wide report extract being migrated.

Template settings for the new extract. May be an empty object — every omitted field is pre-filled from the source extract.

Template ID. Resolved from the source extract when omitted.

Account ID. Resolved from the source extract when omitted.

Title of the new data table. Generated automatically when empty.

Extraction template ID whose custom setting is being resolved.

Connection ID used to resolve credentials and scope accounts.

Remote account IDs from the source platform, scoped by connection_id. These are the same string account IDs used by extraction template preview.

Custom setting name from the extraction template.

Optional case-insensitive search query applied to loaded options.

Page number for paginated options.

Number of options to return per account.

Value that should be submitted as the custom setting value.

Human-readable option label.

Optional extra text that can be shown in the UI.

Remote account ID from the request.

Total number of options after the search filter is applied.

Next page number as a string, or null if this is the last page.

Previous page number as a string, or null if this is the first page.

Page of selectable options for this account.

Whether a non-empty search query was applied.

Custom setting name from the request.

Role ID

Role title (unique within the agency)

Optional human-readable description

True for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.

True for internal-only roles (impersonation, guest viewers). These are never listed in the API.

Permissions grouped by product layer. Layer codes match code in the permissions catalog.

Number of users currently assigned to this role across the agency.

Role title. Must be non-empty and unique within the agency.

Permissions grouped by product layer. Use codes from GET /api/v3/roles/permissions.

Optional description.

ID of the newly created role.

Number of users that were reassigned to the Viewer system role as part of the delete.

Permission code (stable identifier, e.g. view, create, manage_roles).

Human-readable title.

Longer description suitable for tooltips.

Product layer code (stable identifier, e.g. extract, admin).

Human-readable layer name.

Layer description suitable for headers/tooltips.

Ordered list of product layers with their valid permissions.

Display name. Falls back to email if first/last name are blank.

Error message

Data source identifier

Data source display name

Template ID

Template title

Template description

List of data sources used by this template

Template creation timestamp

Template last update timestamp

Total number of templates

URL to the next page

URL to the previous page

Template ID

Template title

Depth in the tree, 0 for the template you requested

Parent template ID. Present on every node inside children; the root object of the detail response carries no parent_id key at all.

Direct children of this node, nested recursively to any depth

Column name in the output table

Physical column type

How the column is used in reporting. Derived from type: string and datetime are dimensions, number and bool are metrics, date is the date key.

Template ID

Template title

Template description

List of data sources used by this template

Depth of this template in its own tree; 0 for a template you can deploy

Templates this one depends on, nested recursively. A recipe created from this template builds every node in the tree.

Schema of the table this template produces, available before you deploy anything. null when the template's output schema cannot be read - treat it as "unknown", not as "no columns".

Number of dependencies in the template

Template creation timestamp

Template last update timestamp

Unique recipe identifier (numeric string)

ID of the template this recipe was created from

Title of the source template

Recipe title

Current recipe state. Ready to work means the last build was built on the extractions that delivered; extractions that could not deliver on their own or in time were left out, so rows of some accounts can be missing. See Build automated recipe.

Workspace ID

Recipe creation timestamp

Recipe last update timestamp

Total number of recipes

URL to the next page

URL to the previous page

Unique recipe identifier (numeric string)

ID of the template this recipe was created from

Recipe title

Initial recipe state, always "Extracting Data". It is the model default written at creation and does not mean that anything is configured or running yet.

ID of the output data table. Resolve the physical table name with GET /api/v3/data-tables/{data_table_id} rather than deriving it from the recipe title.

Error message

Present when a recipe from the same template already exists in this workspace (one recipe per template per workspace). Lists the recipes that already exist - the list can hold more than one id. Treat this response as "already deployed" rather than as a failure, and reuse one of the returned recipes. The detail advises calling resetup: that is POST /api/v3/automated-recipes/{recipe_id}/resetup/, which recreates one of these recipes from the current version of the template.

Present when the output table name derived from the template is already taken in this workspace. Lists the recipes holding that name.

Internal account id, required. Resolve it per workspace with GET /api/v3/connections/{connection_id}/accounts - the same platform account has a different id in every workspace. In a request body this must be an object member - sending a bare string in place of the object returns 400 "Invalid data. Expected a dictionary, but got str."

External account identifier as the platform knows it, for example "act_500105056677763". Optional, and the only identifier that is stable across workspaces - join on it when you deploy one template to many workspaces.

Connection id, scoped to the workspace. The same connector has a different connection_id in every workspace - resolve it per workspace with GET /api/v3/datasources/{datasource_name}/connections.

Data source name for this connection

List of accounts for this connection. Must not be empty.

Human-readable reason, stripped of internal identifiers

Which phase of the build failed. Null on failures recorded without a stage.

Always null today - the public error carries no build context. Reserved.

Unique recipe identifier (numeric string)

ID of the template this recipe was created from

Associated data table ID (null if not yet created)

Recipe title

Current recipe state. Ready to work means the last build was built on the extractions that delivered; extractions that could not deliver on their own or in time were left out, so rows of some accounts can be missing. See Build automated recipe.

List of configured data source names

List of allowed data source names for this recipe

List of configured connections

Start date for data synchronization

Last time the recipe's setup row changed. Despite the name it is not a build stamp: it moves when the configuration is written and on most build state transitions, but not when POST /build/ is accepted and not when a build failure is recorded. Do not use it to decide whether, or when, a build ran.

Why the last build failed. null unless the most recent build failed - the field is cleared when the configuration is written, when a build starts and when a build succeeds. This is the only machine-readable place the failure reason appears: POST /build/ has already returned by the time a build fails.

Recipe creation timestamp

Recipe last update timestamp

List of data source names to include

List of connections with accounts

Start date for data synchronization (YYYY-MM-DD)

Build operation status

Human-readable status message

True when every table in sources exists in the destination. Not a sign that every account has delivered - see the recipe state.

One entry per extraction table the recipe reads, sorted by table name. A data source with more than one table appears once per table, so data_source is not unique - key this list by table. Empty when the recipe's cells reference no extraction tables.

Data source name, e.g. facebook

Name of the extraction table in the workspace destination

Whether that table exists in the destination right now

Extractions the last build used for this data source - the ones it created and the existing ones it reused, including any it did not wait for. Repeated on every table of the same data source, and empty before the first build.

Reset operation status

ID of the recipe that was reset

Machine-readable error code. Branch on this, never on the message.

Human-readable text. Wording may change; it is not part of the contract.

Always present, always an object. Its shape depends on the code; codes that carry no extra data return an empty object. See Errors.

Template identifier. Pass it as template_id when you create a recipe.

Template name. It can be changed in the interface, and the name in force when a recipe is created decides the name of that recipe's output table.

Template description, as entered in the interface. Can be empty.

Data sources this template supports. The data_sources you send when you configure a recipe must be taken from this list.

Categories the template is filed under in the interface, in display order. Empty when the template has none.

Who the template comes from. improvado - a template we provide; agency - a template your agency created by promoting one of its own recipes. Agency templates are the ones the interface shows as custom. New values can be added, so tolerate unknown ones.

How a recipe from this template builds when one data source delivers no data. progressive - that data source is left out, the rest is built and the recipe becomes ready_to_work with degraded: true; if every data source fails, the recipe fails. atomic - a single failing data source fails the whole recipe. In both modes individual accounts that did not deliver never fail the recipe on their own. New values can be added, so tolerate unknown ones.

When the template was created.

When the template was last changed.

Template identifier. Pass it as template_id when you create a recipe.

Template name. It can be changed in the interface, and the name in force when a recipe is created decides the name of that recipe's output table.

Template description, as entered in the interface. Can be empty.

Data sources this template supports. The data_sources you send when you configure a recipe must be taken from this list.

Categories the template is filed under in the interface, in display order. Empty when the template has none.

Who the template comes from. improvado - a template we provide; agency - a template your agency created by promoting one of its own recipes. Agency templates are the ones the interface shows as custom. New values can be added, so tolerate unknown ones.

How a recipe from this template builds when one data source delivers no data. progressive - that data source is left out, the rest is built and the recipe becomes ready_to_work with degraded: true; if every data source fails, the recipe fails. atomic - a single failing data source fails the whole recipe. In both modes individual accounts that did not deliver never fail the recipe on their own. New values can be added, so tolerate unknown ones.

Depth of this template in its own tree; 0 for a template you can deploy.

Templates this one is built on, nested to any depth. A recipe created from this template builds every node of the tree.

How many templates this one depends on, counted over the whole tree.

Columns of the table a recipe from this template produces, available before you deploy anything. An empty list means the schema could not be read - treat it as unknown, not as "no columns".

When the template was created.

When the template was last changed.

Total number of templates matching the request.

Full URL of the next page, or null on the last page.

Full URL of the previous page, or null on the first page.

Templates on this page.

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.

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.

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.

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.

When the failure was recorded, or null when no time was stored with it.

Extra data for this code, always an object; {} for codes that carry none. See Errors for the shape per code.

Data source name, for example facebook.

How this data source ended up in the last build. queued - waiting to start; extracting - collecting data; building - building its tables; ready - built; failed - it did not build, see error; not_built - it was not part of the last build, because it was added to the configuration afterwards or because the recipe has never been built. Run a build to include it. New values can be added, so tolerate unknown ones.

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 page.

How many extractions of this data source did not make it into the last build. This is the full number; not_delivered lists at most 100 of them.

The extractions that did not make it into the last build, ordered by account_id and capped at 100 entries per data source. An empty list means everything this data source was waiting for delivered.

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

The template this recipe was created from.

Current name of that template.

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

The workspace this recipe lives in.

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.

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.

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.

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 page.

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.

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.

When the recipe was created.

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

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

The template this recipe was created from.

Current name of that template.

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

The workspace this recipe lives in.

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.

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.

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

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 page.

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.

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.

When the recipe was created.

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

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

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

The connections and accounts the recipe reads. This is the full set the recipe holds; configuring a recipe always sends the full set, and nothing can be taken away from it.

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

What the last build did with each configured data source. One entry per name in data_sources.

Total number of recipes matching the request.

Full URL of the next page, or null on the last page.

Full URL of the previous page, or null on the first page.

Recipes on this page.

true only when tables is not empty and every table in it exists right now. It does not mean the data is complete: for that read the recipe's state, degraded and sources.

One entry per extraction table the recipe reads. A data source with more than one table appears once per table, so key this list by table, not by data_source. Empty when the recipe reads no extraction tables yet.

Account identifier. This is the only identifier a v3.1 recipe accepts in connections[].accounts[].id, and it is specific to this workspace.

Account name.

The connection this account belongs to.

Data source of the connection, for example facebook.

Whether the account is switched on. Only accounts with is_active: true can be put in a recipe; the rest are rejected when you configure one.

Whether this account is enabled for extraction through the embedded API.

Currency of the account, or null when it has none.

Extra account settings, as set through the accounts update operation. {} when there are none.

When the account was created.

When the account was last changed.

Total number of accounts matching the request.

Full URL of the next page, or null on the last page.

Full URL of the previous page, or null on the first page.

Accounts on this page.

Subscription ID

Name of the event type this subscription receives

Whether the subscription is active

When the subscription was created

Webhook endpoint ID

Receiver URL

Endpoint lifecycle status. unverified endpoints do not receive event deliveries.

Number of consecutive failed deliveries since the last successful delivery

Number of event types this endpoint is subscribed to

64-character hex signing secret

HTTPS URL of the receiver that will accept event deliveries.

Event types this endpoint will subscribe to. See GET /api/v3/webhook_event_types/ for the list of available event names. Duplicates are deduplicated server-side. May be empty.

Identifier of the event type (used in event_types when creating subscriptions)

Email addresses of the external users to generate links for. One link is generated per email; the email identifies the external user.

When true (default), Improvado also emails the generated link to each recipient. Set to false to deliver the links yourself.

Email of the user the links are sent on behalf of. Must be an active user of your agency who is a member of the workspace or an owner of the agency; any other value is rejected with 400. The user is shown as the sender on the link page and in the invitation email, and receives the confirmation email once the connection is created. The confirmation is skipped if the user has lost access to the workspace by then.

When omitted, the link page and the invitation show your whitelabel title instead of a person, and no confirmation email is sent.

Email of the external user the link was generated for

One-time authentication link to share with the external user

Timestamp when the link expires (14 days after creation)

External authentication link ID

Data source name

Human-readable data source title

Current status of the link

When the link was generated

Email of the external user the link was generated for

Email of the user who generated the link

When the link was revoked, if it was

Email of the user who revoked the link; empty string if not revoked

Number of external authentication links

URL to the next page

URL to the previous page

Generated links, one per successfully processed email

Emails for which link creation failed