Improvado Embedded API v3

Extracts

Endpointhttps://embedded.improvado.io

Create and manage data extraction orders that pull data from connected sources.

An extract represents a configured instance of data extraction with specific settings:

Which connection and account to extract from
Which extract template to use
Custom field selections and filters
Schedule and date range configuration
Where to store the extracted data (data table)

Extract workflow:

Create extract with desired configuration
Extraction runs automatically on schedule or on-demand
Data is stored in the associated data table
Monitor extraction status and history

List extracts

GET

https://embedded.improvado.io

/api/v3/extracts

List extracts

List extracts › query Parameters

extraction_ids

string

Extraction IDs

Example: 123,456

List extracts › Responses

Get a list of Extracts

object[]

count

integer

Number of extracts

next

string

URL to the next page

previous

string

URL to the previous page

object[]

GET/api/v3/extracts

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

shell

Example Responses

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Extract 1",
      "connection_id": 1,
      "account_id": 1,
      "account_name": "Account 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
        }
      ],
      "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"
        }
      ],
      "template": {
        "id": 1,
        "title": "Extract Template 1",
        "datasource_name": "google_sheets",
        "data_class": "table"
      },
      "data_table": {
        "id": 1,
        "name": "table_1",
        "title": "Table 1"
      },
      "created_at": "2021-01-01T00:00:00Z",
      "last_sync": "2021-01-01T00:00:00Z",
      "status": "active",
      "error_text": "Error text",
      "sync_historical_data": "2025-02-25"
    },
    {
      "id": 2,
      "title": "Extract 2",
      "connection_id": 2,
      "account_id": 2,
      "account_name": "Account 2",
      "template": {
        "id": 2,
        "title": "Extract Template 2",
        "datasource_name": "google_ads",
        "data_class": "table"
      },
      "data_table": {
        "id": 2,
        "name": "table_2",
        "title": "Table 2"
      },
      "created_at": "2021-01-01T00:00:00Z",
      "last_sync": "2021-01-01T00:00:00Z",
      "status": "active",
      "error_text": "Error text",
      "sync_historical_data": null
    }
  ]
}

json

application/json

Create extract

POST

https://embedded.improvado.io

/api/v3.1/extracts/

Request to this endpoint setups a new extracts. New extract creation request is composed of Connection, Account and Extract Template data.

Create extract › Request Body

data_table_title

string

Data Table Title

template_id

integer

Template ID

object

Template settings

accounts

integer[]

Create extract › Responses

Create an Extract

object[]

POST/api/v3.1/extracts/

curl --request POST \
  --url https://embedded.improvado.io/api/v3.1/extracts/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "data_table_title": "Table 1",
  "template_id": 1,
  "template_settings": {
    "fields": [
      "field_1",
      "field_2"
    ],
    "additional_params": {
      "lookback_window": "default"
    },
    "sync_historical_data": "2021-01-01",
    "scheduling": {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "day",
      "timezone": "UTC",
      "lookback_window": "default"
    }
  },
  "accounts": [
    1,
    2
  ]
}
'

shell

Example Request Body

{
  "data_table_title": "Table 1",
  "template_id": 1,
  "template_settings": {
    "fields": [
      "field_1",
      "field_2"
    ],
    "additional_params": {
      "lookback_window": "default"
    },
    "sync_historical_data": "2021-01-01",
    "scheduling": {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "day",
      "timezone": "UTC",
      "lookback_window": "default"
    }
  },
  "accounts": [
    1,
    2
  ]
}

json

application/json

Example Responses

{
  "created_orders": [
    {
      "id": 1,
      "account": {
        "id": 1,
        "name": "Account 1"
      },
      "extraction_order_template_name": "Template 1",
      "data_table_id": 1
    }
  ],
  "conflicted_orders": [
    {
      "id": 2,
      "account": {
        "id": 2,
        "name": "Account 2"
      },
      "extraction_order_template_name": "Template 2",
      "data_table_id": 2
    }
  ]
}

json

application/json

Get an extract

GET

https://embedded.improvado.io

/api/v3/extracts/{id}

Get detailed info about extract

Get an extract › path Parameters

id

integer · required

Extract ID

Get an extract › Responses

Get 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

object

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

object[]

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"
  },
  "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

object[]

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

object

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

object[]

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"
  },
  "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

object[]

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

object

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

object[]

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"
  },
  "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

object

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

object[]

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

Extraction templates Data tables

List extracts

GET

https://embedded.improvado.io

/api/v3/extracts

List extracts

List extracts › query Parameters

extraction_ids

string

Extraction IDs

Example: 123,456

List extracts › Responses

Get a list of Extracts

object[]

count

integer

Number of extracts

next

string

URL to the next page

previous

string

URL to the previous page

object[]

Create extract

POST

https://embedded.improvado.io

/api/v3.1/extracts/

Request to this endpoint setups a new extracts. New extract creation request is composed of Connection, Account and Extract Template data.

Create extract › Request Body

data_table_title

string

Data Table Title

template_id

integer

Template ID

object

Template settings

accounts

integer[]

Create extract › Responses

Create an Extract

object[]

Get an extract

GET

https://embedded.improvado.io

/api/v3/extracts/{id}

Get detailed info about extract

Get an extract › path Parameters

id

integer · required

Extract ID

Get an extract › Responses

Get 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

object

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

object[]

sync_historical_data

string | null · readOnly

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

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

object[]

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

object

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

object[]

sync_historical_data

string | null · readOnly

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

Update an extract partially

PATCH

https://embedded.improvado.io

/api/v3/extracts/{id}

Update an extract partially › path Parameters

id

integer · required

Extract ID

Update an extract partially › Request Body

object[]

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

object

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

object[]

sync_historical_data

string | null · readOnly

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

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

object

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

object[]

sync_historical_data

string | null · readOnly

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