> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Datasets SDK Reference

> SDK reference for the Datasets API, available in Node.js and Python.

## Datasets

### List Datasets

Retrieves a paginated list of datasets for the current workspace. Results can be paginated using cursor-based pagination.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.list(limit=10)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.list({});

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "search": Optional[str],
        "updated_by": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      search?: string;
      updatedBy?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Literal["list"],
        "data": {
            "id": str,
            "display_name": str,
            "project_id": str,
            "workspace_id": str,
            "metadata": {
                "total_versions": float,
                "datapoints_count": float,
            },
            "created_by_id": OptionalNullable[str],
            "updated_by_id": OptionalNullable[str],
            "created": date,
            "updated": date,
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        displayName: string;
        projectId: string;
        workspaceId: string;
        metadata: {
          totalVersions: number;
          datapointsCount: number;
        };
        createdById?: string;
        updatedById?: string;
        created?: Date;
        updated?: Date;
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Dataset

Creates a new dataset in the specified project.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.create(request={
          "display_name": "Neva.Raynor10",
          "path": "Default",
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.create({
      displayName: "Neva.Raynor10",
      path: "Default",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "display_name": str,  # required
        "path": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      displayName: string;  // required
      path: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "display_name": str,
        "project_id": str,
        "workspace_id": str,
        "metadata": {
            "total_versions": float,
            "datapoints_count": float,
        },
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      displayName: string;
      projectId: string;
      workspaceId: string;
      metadata: {
        totalVersions: number;
        datapointsCount: number;
      };
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Dataset

Retrieves a specific dataset by its unique identifier

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.retrieve(dataset_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.retrieve({
      datasetId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "display_name": str,
        "project_id": str,
        "workspace_id": str,
        "metadata": {
            "total_versions": float,
            "datapoints_count": float,
        },
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      displayName: string;
      projectId: string;
      workspaceId: string;
      metadata: {
        totalVersions: number;
        datapointsCount: number;
      };
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Dataset

Update a dataset

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.update(dataset_id="<id>", path="Default")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.update({
      datasetId: "<id>",
      requestBody: {
        path: "Default",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
        "display_name": Optional[str],
        "project_id": Optional[str],
        "path": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
      requestBody?: {
        displayName?: string;
        projectId?: string;
        path?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "display_name": str,
        "project_id": str,
        "workspace_id": str,
        "metadata": {
            "total_versions": float,
            "datapoints_count": float,
        },
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      displayName: string;
      projectId: string;
      workspaceId: string;
      metadata: {
        totalVersions: number;
        datapointsCount: number;
      };
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Dataset

Permanently deletes a dataset and all its datapoints. This action is irreversible.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.datasets.delete(dataset_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.datasets.delete({
      datasetId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### List Datapoints

Retrieves a paginated list of datapoints from a specific dataset.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.list_datapoints(dataset_id="<id>", limit=10)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.listDatapoints({
      datasetId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Literal["list"],
        "data": {
            "id": str,
            "workspace_id": str,
            "inputs": Dict[str, Any],
            "messages": Union[ListDatasetDatapointsMessagesSystemMessage, ListDatasetDatapointsMessagesDeveloperMessage, ListDatasetDatapointsMessagesUserMessage, ListDatasetDatapointsMessagesAssistantMessage, ListDatasetDatapointsMessagesToolMessage],
            "expected_output": Optional[str],
            "evaluations": Union[ListDatasetDatapointsEvaluations1, ListDatasetDatapointsEvaluations2, ListDatasetDatapointsEvaluations3],
            "dataset_id": str,
            "snapshot_version": Optional[str],
            "created_by_id": OptionalNullable[str],
            "updated_by_id": OptionalNullable[str],
            "created": date,
            "updated": date,
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        workspaceId: string;
        inputs?: Record<string, any>;
        messages?: string;
        expectedOutput?: string;
        evaluations?: string;
        datasetId: string;
        snapshotVersion?: string;
        createdById?: string;
        updatedById?: string;
        created?: Date;
        updated?: Date;
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create Datapoint

Creates a new datapoint in the specified dataset.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.create_datapoint(dataset_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.createDatapoint({
      datasetId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
        "request_body": {  # optional
            "inputs": Union[str, float, bool],
            "messages": Union[CreateDatasetItemMessagesSystemMessage, CreateDatasetItemMessagesDeveloperMessage, CreateDatasetItemMessagesUserMessage, CreateDatasetItemMessagesAssistantMessage, CreateDatasetItemMessagesToolMessage],
            "expected_output": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
      requestBody?: {
        inputs?: string;
        messages?: string;
        expectedOutput?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve Datapoint

Retrieves a datapoint object

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.retrieve_datapoint(dataset_id="<id>", datapoint_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.retrieveDatapoint({
      datasetId: "<id>",
      datapointId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
        "datapoint_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
      datapointId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "workspace_id": str,
        "inputs": Dict[str, Any],
        "messages": Union[RetrieveDatapointMessagesSystemMessage, RetrieveDatapointMessagesDeveloperMessage, RetrieveDatapointMessagesUserMessage, RetrieveDatapointMessagesAssistantMessage, RetrieveDatapointMessagesToolMessage],
        "expected_output": Optional[str],
        "evaluations": Union[RetrieveDatapointEvaluations1, RetrieveDatapointEvaluations2, RetrieveDatapointEvaluations3],
        "dataset_id": str,
        "snapshot_version": Optional[str],
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      workspaceId: string;
      inputs?: Record<string, any>;
      messages?: string;
      expectedOutput?: string;
      evaluations?: string;
      datasetId: string;
      snapshotVersion?: string;
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Update Datapoint

Update a datapoint

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.datasets.update_datapoint(dataset_id="<id>", datapoint_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.datasets.updateDatapoint({
      datasetId: "<id>",
      datapointId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
        "datapoint_id": str,  # required
        "inputs": Union[str, float, bool],
        "messages": Union[UpdateDatapointMessagesSystemMessage, UpdateDatapointMessagesDeveloperMessage, UpdateDatapointMessagesUserMessage, UpdateDatapointMessagesAssistantMessage, UpdateDatapointMessagesToolMessage],
        "expected_output": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
      datapointId: string;  // required
      requestBody?: {
        inputs?: string;
        messages?: string;
        expectedOutput?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "workspace_id": str,
        "inputs": Dict[str, Any],
        "messages": Union[UpdateDatapointMessagesDatasetsSystemMessage, UpdateDatapointMessagesDatasetsDeveloperMessage, UpdateDatapointMessagesDatasetsUserMessage, UpdateDatapointMessagesDatasetsAssistantMessage, UpdateDatapointMessagesDatasetsToolMessage],
        "expected_output": Optional[str],
        "evaluations": Union[UpdateDatapointEvaluations1, UpdateDatapointEvaluations2, UpdateDatapointEvaluations3],
        "dataset_id": str,
        "snapshot_version": Optional[str],
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      workspaceId: string;
      inputs?: Record<string, any>;
      messages?: string;
      expectedOutput?: string;
      evaluations?: string;
      datasetId: string;
      snapshotVersion?: string;
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete Datapoint

Permanently deletes a specific datapoint from a dataset.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.datasets.delete_datapoint(dataset_id="<id>", datapoint_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.datasets.deleteDatapoint({
      datasetId: "<id>",
      datapointId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
        "datapoint_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
      datapointId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Clear Datasets

Delete all datapoints from a dataset. This action is irreversible.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.datasets.clear(dataset_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.datasets.clear({
      datasetId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "dataset_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      datasetId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>