---
title: "Create a load"
method: POST
path: "/api/v3/loads"
tags: ["Loads"]
---

# Create a load

`POST /api/v3/loads`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/loads`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `dts_session_id`
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/loads/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new load. A load creation request is composed of Data Table and Destination Connection data.

**Validation rules:**
- When `run_policy` is `"schedule"`, `schedules` must contain at least one entry.
- When `run_policy` is `"after extraction"`, `schedules` must be empty or omitted.

## Request body

- object
  - `data_table_id` integer, required: Data Table ID
  - `destination_connection_id` string, uuid, required: Destination Connection ID (UUID)
  - `destination_table` string, required: Destination Table
  - `run_policy` 'after extraction' | 'schedule', required: When the load runs: - `after extraction` — runs automatically after the related extract finishes. - `schedule` — runs on the recurring schedule(s) defined in `schedules`.
  - `schedules` Scheduling[]: Required when `run_policy` is `schedule`. Must be empty or omitted when `run_policy` is `after extraction`.
    - `days` integer: 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)
    - `hours` integer: Hour at which the run will start (0–23)
    - `minutes` integer: Minute of hour at which the run will start (0–59)
    - `interval` 'hour' | 'day' | 'week' | 'month': Frequency at which the run will be performed: - `hour` — every hour - `day` — once per day - `week` — once per week - `month` — once per month
    - `timezone` string: IANA timezone name (e.g. `UTC`, `America/New_York`) the schedule is interpreted in.
    - `recurrence` integer: How often the schedule repeats within the interval. Defaults to 1.
    - `lookback_window` object: Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.
      - `name` 'default' | 'live' | 'max': Lookback window preset: - `default` — past 30 days from the day of extract - `live` — past 1 day from the day of extract - `max` — past 60 days from the day of extract
  - `load_historical_data` boolean: When `true`, the initial load run will backfill historical data for the data table.

## Response `200`

Create a Load

- Load: Load object
  - `id` integer: Load ID
  - `data_table` DataTable: Data Table object
    - `id` integer: Data Table ID
    - `title` string: Data Table title
    - `datasource_name` string: Data source name
  - `destination_connection` object
    - `id` string, uuid: Destination Connection ID (UUID)
    - `title` string: Destination Connection title
    - `destination_name` string: Destination name
  - `destination_table` string: Destination table name
  - `run_policy` 'after extraction' | 'schedule': Load run policy
  - `schedules` Scheduling[]
    - `days` integer: 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)
    - `hours` integer: Hour at which the run will start (0–23)
    - `minutes` integer: Minute of hour at which the run will start (0–59)
    - `interval` 'hour' | 'day' | 'week' | 'month': Frequency at which the run will be performed: - `hour` — every hour - `day` — once per day - `week` — once per week - `month` — once per month
    - `timezone` string: IANA timezone name (e.g. `UTC`, `America/New_York`) the schedule is interpreted in.
    - `recurrence` integer: How often the schedule repeats within the interval. Defaults to 1.
    - `lookback_window` object: Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.
      - `name` 'default' | 'live' | 'max': Lookback window preset: - `default` — past 30 days from the day of extract - `live` — past 1 day from the day of extract - `max` — past 60 days from the day of extract
  - `status` string: Load status
  - `last_update` string: Last update date
  - `error_text` string: Error text
  - `uploaded_rows_count` integer: Number of uploaded rows

## Other responses

- `401`: Forbidden

---

[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)