Extracts

id

integer

Extract ID

title

string

Extract title

connection_id

integer

Connection ID

account_id

integer

Account ID

account_name

string

Account name

account_entity_id

integer

Internal Improvado account entity ID.

account_embedded_id

integer | null

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

object

created_at

string

Extract creation date

last_sync

string

Last sync date

status

string

Extract status

error_text

string

Error text

schedules_limit

integer

Schedules limit

sync_historical_data

string | null · readOnly

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

GET/api/v3/extracts/{id}

curl --request GET \
  --url https://embedded.improvado.io/api/v3/extracts/:id

shell

Example Responses

{
  "id": 1,
  "title": "Extract 1",
  "connection_id": 1,
  "account_id": 1,
  "account_name": "Account 1",
  "template": {
    "id": 1,
    "title": "Extract Template 1",
    "datasource_name": "google_sheets",
    "data_class": "table",
    "is_wide_template": false
  },
  "data_table": {
    "id": 1,
    "name": "table_1",
    "title": "Table 1"
  },
  "fields": [
    {
      "title": "Field 1",
      "name": "field_1",
      "user_kind": "string",
      "user_type": "string",
      "selected": true,
      "can_edit": true,
      "sql_name": "field_1",
      "format": "string",
      "is_dynamic": false
    }
  ],
  "created_at": "2021-01-01T00:00:00Z",
  "last_sync": "2021-01-01T00:00:00Z",
  "status": "active",
  "error_text": "Error text",
  "schedules_limit": 1,
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "additional_params": [
    {
      "type": "string",
      "name": "param_1",
      "required": true,
      "title": "Param 1",
      "description": "Param 1 description",
      "params": {},
      "initial_value": "value"
    }
  ],
  "sync_historical_data": "2025-02-25"
}

json

application/json

Update an extract

PUT

https://embedded.improvado.io

/api/v3/extracts/{id}

Allows to update scheduling, fields, additional parameters and sync_historical_data attributes values for existing extraction.

Update an extract › path Parameters

id

integer · required

Extract ID

Update an extract › Request Body

fields

string[]

additional_params

object

sync_historical_data

string

Update an extract › Responses

Update an Extract

Extract object

id

integer

Extract ID

title

string

Extract title

connection_id

integer

Connection ID

account_id

integer

Account ID

account_name

string

Account name

account_entity_id

integer

Internal Improvado account entity ID.

account_embedded_id

integer | null

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

object

created_at

string

Extract creation date

last_sync

string

Last sync date

status

string

Extract status

error_text

string

Error text

schedules_limit

integer

Schedules limit

sync_historical_data

string | null · readOnly

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

PUT/api/v3/extracts/{id}

curl --request PUT \
  --url https://embedded.improvado.io/api/v3/extracts/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "fields": [
    "field_name_1",
    "field_name_2"
  ],
  "additional_params": {
    "param1": "value1",
    "param2": "value2"
  },
  "sync_historical_data": "2021-01-01T00:00:00Z"
}
'

shell

Example Request Body

{
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "fields": [
    "field_name_1",
    "field_name_2"
  ],
  "additional_params": {
    "param1": "value1",
    "param2": "value2"
  },
  "sync_historical_data": "2021-01-01T00:00:00Z"
}

json

application/json

Example Responses

{
  "id": 1,
  "title": "Extract 1",
  "connection_id": 1,
  "account_id": 1,
  "account_name": "Account 1",
  "template": {
    "id": 1,
    "title": "Extract Template 1",
    "datasource_name": "google_sheets",
    "data_class": "table",
    "is_wide_template": false
  },
  "data_table": {
    "id": 1,
    "name": "table_1",
    "title": "Table 1"
  },
  "fields": [
    {
      "title": "Field 1",
      "name": "field_1",
      "user_kind": "string",
      "user_type": "string",
      "selected": true,
      "can_edit": true,
      "sql_name": "field_1",
      "format": "string",
      "is_dynamic": false
    }
  ],
  "created_at": "2021-01-01T00:00:00Z",
  "last_sync": "2021-01-01T00:00:00Z",
  "status": "active",
  "error_text": "Error text",
  "schedules_limit": 1,
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "additional_params": [
    {
      "type": "string",
      "name": "param_1",
      "required": true,
      "title": "Param 1",
      "description": "Param 1 description",
      "params": {},
      "initial_value": "value"
    }
  ]
}

json

application/json

Update an extract partially

PATCH

https://embedded.improvado.io

/api/v3/extracts/{id}

Allows to partially update scheduling, fields, additional parameters and sync_historical_data attributes values for existing extraction. Only provided fields will be updated, omitted fields will remain unchanged.

Update an extract partially › path Parameters

id

integer · required

Extract ID

Update an extract partially › Request Body

fields

string[]

additional_params

object

sync_historical_data

string

Update an extract partially › Responses

Partially Update an Extract

Extract object

id

integer

Extract ID

title

string

Extract title

connection_id

integer

Connection ID

account_id

integer

Account ID

account_name

string

Account name

account_entity_id

integer

Internal Improvado account entity ID.

account_embedded_id

integer | null

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

object

created_at

string

Extract creation date

last_sync

string

Last sync date

status

string

Extract status

error_text

string

Error text

schedules_limit

integer

Schedules limit

sync_historical_data

string | null · readOnly

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

PATCH/api/v3/extracts/{id}

curl --request PATCH \
  --url https://embedded.improvado.io/api/v3/extracts/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "fields": [
    "field_name_1",
    "field_name_2"
  ],
  "additional_params": {
    "param1": "value1",
    "param2": "value2"
  },
  "sync_historical_data": "2021-01-01T00:00:00Z"
}
'

shell

Example Request Body

{
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "fields": [
    "field_name_1",
    "field_name_2"
  ],
  "additional_params": {
    "param1": "value1",
    "param2": "value2"
  },
  "sync_historical_data": "2021-01-01T00:00:00Z"
}

json

application/json

Example Responses

{
  "id": 1,
  "title": "Extract 1",
  "connection_id": 1,
  "account_id": 1,
  "account_name": "Account 1",
  "template": {
    "id": 1,
    "title": "Extract Template 1",
    "datasource_name": "google_sheets",
    "data_class": "table",
    "is_wide_template": false
  },
  "data_table": {
    "id": 1,
    "name": "table_1",
    "title": "Table 1"
  },
  "fields": [
    {
      "title": "Field 1",
      "name": "field_1",
      "user_kind": "string",
      "user_type": "string",
      "selected": true,
      "can_edit": true,
      "sql_name": "field_1",
      "format": "string",
      "is_dynamic": false
    }
  ],
  "created_at": "2021-01-01T00:00:00Z",
  "last_sync": "2021-01-01T00:00:00Z",
  "status": "active",
  "error_text": "Error text",
  "schedules_limit": 1,
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "additional_params": [
    {
      "type": "string",
      "name": "param_1",
      "required": true,
      "title": "Param 1",
      "description": "Param 1 description",
      "params": {},
      "initial_value": "value"
    }
  ]
}

json

application/json

Run an extract

POST

https://embedded.improvado.io

/api/v3/extracts/{id}/run

Manual run an extract with custom date range

Run an extract › path Parameters

id

integer · required

Extract ID

Run an extract › Request Body optional

date_from

string · date

Start date for the extract run

date_to

string · date

End date for the extract run

Run an extract › Responses

Run an Extract

Extract object

id

integer

Extract ID

title

string

Extract title

connection_id

integer

Connection ID

account_id

integer

Account ID

account_name

string

Account name

account_entity_id

integer

Internal Improvado account entity ID.

account_embedded_id

integer | null

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

object

created_at

string

Extract creation date

last_sync

string

Last sync date

status

string

Extract status

error_text

string

Error text

schedules_limit

integer

Schedules limit

MigrateWideExtractRequest

sync_historical_data

string | null · readOnly

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

Pause an extract

POST

https://embedded.improvado.io

/api/v3/extracts/{extract_id}/pause

Pauses extract so it wont download data from datasource until it’s unpaused

Pause an extract › path Parameters

extract_id

integer · required

Extract ID

Pause an extract › Responses

Pause an Extract

No data returned

Unpause an extract

POST

https://embedded.improvado.io

/api/v3/extracts/{extract_id}/unpause

Unpauses extract so it starts to download data from datasource

Unpause an extract › path Parameters

extract_id

integer · required

Extract ID

Unpause an extract › Responses

Unpause an Extract

No data returned

Migrate a wide report extract

POST

https://embedded.improvado.io

/api/v3/extracts/migrate-wide

Migrates a wide report extract with changed dimensions to a new extract with a new data table. The new extract is linked to the source extract and the source extract is paused; its data and data table remain queryable. Every omitted template_settings field is pre-filled from the source extract, so only the settings being changed need to be passed. template_id and account are resolved from the source extract when omitted; a data table title is generated when data_table_title is empty.

Migrate a wide report extract › Request Body

Request payload for migrating a wide report extract.

migrated_from_extraction_id

integer · required

ID of the source wide report extract being migrated.

Example: 1443619

object · required

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

template_id

integer

Template ID. Resolved from the source extract when omitted.

Example: 421

account

integer

Account ID. Resolved from the source extract when omitted.

Example: 2330268667

data_table_title

string

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

Example:

Migrate a wide report extract › Responses

The newly created extract detail

Extract object

id

integer

Extract ID

title

string

Extract title

connection_id

integer

Connection ID

account_id

integer

Account ID

account_name

string

Account name

account_entity_id

integer

Internal Improvado account entity ID.

account_embedded_id

integer | null

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

object

created_at

string

Extract creation date

last_sync

string

Last sync date

status

string

Extract status

error_text

string

Error text

schedules_limit

integer

Schedules limit