Skip to main content
POST/analytics/{datasetSlug}/schedules

Create Schedule

Creates a recurring materialization from a collection into this dataset.

Body: fromCollection, intervalSeconds (at least 60) and optional reattestIntervalDays (7, 30, 90 or 365).

Each run reads the collection with its creator's current access.

The schedule keeps running only while it is re-attested within the interval.

Requires the datasets:write permission (PROJECT_ADMIN or PROJECT_AUTHOR by default).

Callers must be members of the project (an organization role alone does not grant access); project service tokens and extension tokens cannot call it.

Parameters
datasetSlug *path

The Dataset's slug.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
fromCollection *string

The collection each run snapshots into the dataset: letters, digits and underscores, not starting with a digit.

Each run reads it as the person who created the schedule, so it writes only the rows they can see.

intervalSeconds *integer

Seconds between runs.

At least 60.

The first run is due as soon as the schedule is created.

reattestIntervalDaysany

How many days each attestation lasts: 7, 30, 90 or 365.

Default 90.

When it runs out, the schedule stops running until someone re-attests it.

One of: 7
or: 30
or: 90
or: 365
Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_REQUEST_SHAPEThe request body does not match the schema.
400K9O_INVALID_FIELD_VALUE`fromCollection`, `intervalSeconds` or `reattestIntervalDays` is invalid.
401K9O_UNAUTHENTICATEDThe caller is not signed in.
403K9O_ACCESS_DENIEDThe caller is not a member of this project; an organization role alone does not grant access.
403K9O_IAM_POLICY_DENIEDThe caller's role or IAM policy does not grant datasets:write.
404K9O_NOT_FOUNDThe project was not found for this caller (project service tokens and extension tokens cannot call this endpoint).
404K9O_DATASET_NOT_FOUNDNo active dataset with this slug exists in the project.
409K9O_PENDING_CHANGE_ALREADY_EXISTSA schedule for this dataset and collection already exists.
Response body (200)
data *object

A materialization schedule: a collection snapshotted into the dataset at a fixed interval.

id *string

The schedule's id (msch_...).

datasetSlug *string

The dataset each run writes to.

sourceCollection *string

The collection each run snapshots.

intervalSeconds *integer

Seconds between runs.

enabled *boolean

Whether the schedule is set to run.

reattestIntervalDays *integer

How many days each attestation lasts: 7, 30, 90 or 365.

attestedAt *string <date-time>

When a person last confirmed the schedule (created or re-attested it).

expiresAt *string <date-time>

attestedAt plus reattestIntervalDays.

After it the schedule stops running until it is re-attested; it isn't deleted.

attestationStatus *"active" | "expiring_soon" | "expired"

expiring_soon within 14 days of expiresAt.

lastRunAt *any

When the schedule last ran.

Null if it has never run.

One of: string <date-time>
or: null
lastRunStatus *any

How the last run ended: ok, error, stale_principal_denied (the person who configured it has lost write access to the dataset) or attestation_expired.

Null if it has never run.

One of: string
or: null
nextRunAt *string <date-time>

When the schedule is next due.

createdAt *string <date-time>

When the schedule was created.

meta *object

Request metadata: cost, timing and correlation ids.

cost *object

Metered usage for this request; empty when nothing was metered.

timing *object
gatewayMs *number
totalMs *number
context *object
requestId *string
traceId *string
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.schedules.create('<datasetSlug>', {})

Showing example in TypeScript

Request example
{
  "fromCollection": "string",
  "intervalSeconds": 0,
  "reattestIntervalDays": 7
}
Response example (200)
{
  "data": {
    "id": "string",
    "datasetSlug": "string",
    "sourceCollection": "string",
    "intervalSeconds": 0,
    "enabled": false,
    "reattestIntervalDays": 0,
    "attestedAt": "string",
    "expiresAt": "string",
    "attestationStatus": "active",
    "lastRunAt": "string",
    "lastRunStatus": "string",
    "nextRunAt": "string",
    "createdAt": "string"
  },
  "meta": {
    "timing": {
      "gatewayMs": 0,
      "totalMs": 0
    },
    "context": {
      "requestId": "string",
      "traceId": "string",
      "projectId": "string"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  }
}

More in Analytics & Intelligence