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

# List Versions of a Dataset

GET https://api.humanloop.com/v5/datasets/{id}/versions

Get a list of the versions for a Dataset.

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

## Authentication

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

## Request

### Path parameters

- `id` (string, required) — Unique identifier for Dataset.

### Query parameters

- `include_datapoints` (enum, optional) — If set to 'latest_saved', include datapoints for the latest saved version. Alternatively, 'latest_committed' (deprecated) includes datapoints for the latest committed version only.
  - Allowed values: `latest_committed`, `latest_saved`

## Response

### 200

Successful Response

- `records` (list of DatasetResponse, required) — The list of Datasets.

## Errors

### 422 List Versions Datasets ID Versions 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"
      }
    }
  ]
}
```

**SDK Code**

```python List versions
import requests

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

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

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

print(response.json())
```

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

const client = new HumanloopClient({ apiKey: "YOUR_API_KEY" });
await client.datasets.listVersions("ds_b0baF1ca7652");

```

```go List versions
package main

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

func main() {

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

	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 versions
require 'uri'
require 'net/http'

url = URI("https://api.humanloop.com/v5/datasets/ds_b0baF1ca7652/versions")

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 versions
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

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

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

$client = new \GuzzleHttp\Client();

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

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

```csharp List versions
using RestSharp;

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

```swift List versions
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.humanloop.com/v5/datasets/ds_b0baF1ca7652/versions")! 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()
```