Documentation | Datasets › List Datasets

Datasets

datasets

Methods

Create A Dataset ->

post/v5/datasets

Create a dataset and populate it with its initial items in a single call.

Use this when the dataset does not exist yet: it creates the dataset and seeds it with the items you provide. To add more items to a dataset that already exists, use POST /v5/dataset-items/batch instead. A name is required, and the request must include at least one item in data; the optional files field associates files with the created items. The provided items are inserted as dataset items as a side effect of creation, and any tags are attached to the dataset. The returned dataset is at version 1.

List Datasets -> CursorPage<

Dataset

get/v5/datasets

Return a paginated list of the account's datasets.

Archived datasets are excluded unless include_archived is set to true. Results can be narrowed by tags and by the standard filterable parameters; a name filter matches as a case-insensitive substring rather than an exact match.

query Parameters

ending_before: string

Optional

include_archived: boolean

Optional

limit: number

Optional

(maximum: 10000, minimum: 1, default: 100)

name: string

Optional

sort_by: string

Optional

sort_order:

SortOrder

Optional

starting_after: string

Optional

tags: Array<string>

Optional

Response fields

has_more: boolean

Whether there are more items left to be fetched.

items: Array<

Dataset

total: number

The total of items that match the query. This is greater than or equal to the number of items returned.

limit: number

Optional

(default: 100)

The maximum number of items to return.

object: "list"

Optional

(default: "list")

Request example

curl https://api.egp.scale.com/v5/datasets \
    -H "x-api-key: $SGP_API_KEY"

200Example

{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "current_version_num": 0,
      "name": "name",
      "tags": [
        "string"
      ],
      "archived_at": "2019-12-27T18:11:19.117Z",
      "description": "description",
      "object": "dataset"
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}

Archive A Dataset -> { id, deleted, object }

delete/v5/datasets/{dataset_id}

Soft-delete a dataset by archiving it; the row is retained and can be restored later.

This sets the dataset's archived_at timestamp rather than permanently removing it, and cascades the same archival to the dataset's items and versions. Archiving is not idempotent: if the dataset is already archived the call fails. The dataset can be brought back with the PATCH restore request. The response reports the dataset id with deleted set to true.

Update Or Restore A Dataset ->

Dataset

patch/v5/datasets/{dataset_id}

Update a dataset's fields, or restore a previously archived dataset.

The request body is a union discriminated by its contents: a body of {"restore": true} triggers a restore, and any other body is treated as a partial update of the dataset's name, description, and tags. Restore clears archived_at on the dataset and cascades the un-archival to its items and versions; restoring a dataset that is not archived returns it unchanged. A partial update on an archived dataset fails, since archived datasets cannot be modified.

Get A Dataset ->

Dataset

get/v5/datasets/{dataset_id}

Retrieve a single dataset by its id.

By default an archived dataset is not returned; set include_archived to true to fetch a dataset regardless of whether it has been archived.

Domain types

Dataset = { id, created_at, created_by, 6 more... }

DatasetArchiveResponse = { id, deleted, object }