> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://humanloop.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://humanloop.com/docs/_mcp/server.

# List Datasets

GET https://api.humanloop.com/v5/datasets

List all Datasets.

Reference: https://humanloop.com/docs/api/datasets/list

## Authentication

- `X-API-KEY` header (required) — API Key authentication via header

## Request

### Query parameters

- `page` (integer, optional, default: 1) — Page offset for pagination.
- `size` (integer, optional, default: 10) — Page size for pagination. Number of Datasets to fetch.
- `name` (string, optional) — Case-insensitive filter for Dataset name.
- `user_filter` (string, optional) — Case-insensitive filter for users in the Dataset. This filter matches against both email address and name of users.
- `sort_by` (enum, optional) — Field to sort Datasets by
  - Allowed values: `created_at`, `updated_at`, `name`
- `order` (enum, optional) — Direction to sort by.
  - Allowed values: `asc`, `desc`

## Response

### 200

Successful Response

- `records` (list of DatasetResponse, required)
- `page` (integer, required)
- `size` (integer, required)
- `total` (integer, required)

## Errors

### 422 List Datasets Get Request Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### DatasetResponse

Base type that all File Responses should inherit from. Attributes defined here are common to all File Responses and should be overridden in the inheriting classes with documentation and appropriate Field definitions.

- `path` (string, required) — Path of the Dataset, including the name, which is used as a unique identifier.
- `id` (string, required) — Unique identifier for the Dataset. Starts with `ds_`.
- `name` (string, required) — Name of the Dataset, which is used as a unique identifier.
- `version_id` (string, required) — Unique identifier for the specific Dataset Version. If no query params provided, the default deployed Dataset Version is returned. Starts with `dsv_`.
- `created_at` (datetime, required)
- `updated_at` (datetime, required)
- `last_used_at` (datetime, required)
- `datapoints_count` (integer, required) — The number of Datapoints in this Dataset version.
- `directory_id` (string, optional) — ID of the directory that the file is in on Humanloop.
- `description` (string, optional) — Description of the Dataset.
- `schema` (map from string to any, optional) — The JSON schema for the File.
- `readme` (string, optional) — Long description of the file.
- `tags` (list of string, optional) — List of tags associated with the file.
- `type` ("dataset", optional)
- `environments` (list of EnvironmentResponse, optional) — The list of environments the Dataset Version is deployed to.
- `created_by` (any, optional) — The user who created the Dataset.
- `version_name` (string, optional) — Unique name for the Dataset version. Version names must be unique for a given Dataset.
- `version_description` (string, optional) — Description of the version, e.g., the changes made in this version.
- `datapoints` (list of DatapointResponse, optional) — The list of Datapoints in this Dataset version. Only provided if explicitly requested.
- `attributes` (map from string to any, optional) — Additional fields to describe the Dataset. Helpful to separate Dataset versions from each other with details on how they were created or used.

### ValidationError

- `loc` (list of ValidationErrorLocItem, required)
- `msg` (string, required)
- `type` (string, required)

### EnvironmentResponse

- `id` (string, required)
- `created_at` (datetime, required)
- `name` (string, required)
- `tag` (enum, required) — An enumeration.
  - Allowed values: `default`, `other`

### DatapointResponse

- `id` (string, required) — Unique identifier for the Datapoint. Starts with `dp_`.
- `inputs` (map from string to string, optional) — The inputs to the prompt template.
- `messages` (list of ChatMessage, optional) — List of chat messages to provide to the model.
- `target` (map from string to DatapointResponseTargetValue, optional) — Object with criteria necessary to evaluate generations with this Datapoint. This is passed in as an argument to Evaluators when used in an Evaluation.

### ValidationErrorLocItem

### ChatMessage

- `role` (enum, required) — Role of the message author.
  - Allowed values: `user`, `assistant`, `system`, `tool`, `developer`
- `content` (ChatMessageContent, optional) — The content of the message.
- `name` (string, optional) — Optional name of the message author.
- `tool_call_id` (string, optional) — Tool call that this message is responding to.
- `tool_calls` (list of ToolCall, optional) — A list of tool calls requested by the assistant.
- `thinking` (list of ChatMessageThinkingItem, optional) — Model's chain-of-thought for providing the response. Present on assistant messages if model supports it.

### DatapointResponseTargetValue

### ChatMessageContent

The content of the message.

### ToolCall

A tool call to be made.

- `id` (string, required)
- `type` ("function", required) — The type of tool to call.
- `function` (FunctionTool, required) — A function tool to be called by the model where user owns runtime.

### ChatMessageThinkingItem

### FunctionTool

A function tool to be called by the model where user owns runtime.

- `name` (string, required)
- `arguments` (string, optional)

### AnthropicThinkingContent

- `type` ("thinking", required)
- `thinking` (string, required) — Model's chain-of-thought for providing the response.
- `signature` (string, required) — Cryptographic signature that verifies the thinking block was generated by Anthropic.

### AnthropicRedactedThinkingContent

- `type` ("redacted_thinking", required)
- `data` (string, required) — Thinking block Anthropic redacted for safety reasons. User is expected to pass the block back to Anthropic

## Examples

**Response**

```json
{
  "records": [
    {
      "path": "test-questions",
      "id": "ds_345mno",
      "name": "test-questions",
      "version_id": "dsv_678pqr",
      "created_at": "2024-05-01T12:00:00Z",
      "updated_at": "2024-05-01T12:00:00Z",
      "last_used_at": "2024-05-01T12:00:00Z",
      "datapoints_count": 2,
      "type": "dataset",
      "created_by": {
        "id": "usr_v23rSVAgas2a",
        "full_name": "Jordan Burges",
        "email_address": "jordan@humanloop.com"
      }
    }
  ],
  "page": 0,
  "size": 1,
  "total": 1
}
```

**SDK Code**

```python List datasets
import requests

url = "https://api.humanloop.com/v5/datasets"

querystring = {"size":"1"}

headers = {"X-API-KEY": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```typescript List datasets
import { HumanloopClient } from "humanloop";

const client = new HumanloopClient({ apiKey: "YOUR_API_KEY" });
const response = await client.datasets.list({
    size: 1
});
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
const page = await client.datasets.list({
    size: 1
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

```

```go List datasets
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.humanloop.com/v5/datasets?size=1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby List datasets
require 'uri'
require 'net/http'

url = URI("https://api.humanloop.com/v5/datasets?size=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java List datasets
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.humanloop.com/v5/datasets?size=1")
  .header("X-API-KEY", "<apiKey>")
  .asString();
```

```php List datasets
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.humanloop.com/v5/datasets?size=1', [
  'headers' => [
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp List datasets
using RestSharp;

var client = new RestClient("https://api.humanloop.com/v5/datasets?size=1");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift List datasets
import Foundation

let headers = ["X-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.humanloop.com/v5/datasets?size=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```