Skip to main content
POST
/
api
/
public
/
v2
/
dataset-versions
/
from-filter-params
Create Dataset Version from Filter Params
curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/dataset-versions/from-filter-params \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "dataset_group_id": 2,
  "variables_to_parse": [
    "<string>"
  ],
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-11-07T05:31:56Z",
  "limit": 25000,
  "q": "<string>",
  "id": 2,
  "starred": true,
  "order_by_random": false,
  "metadata_and": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "metadata_or": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "tags_and": [
    "<string>"
  ],
  "tags_or": [
    "<string>"
  ],
  "prompt_templates_include": [
    {
      "name": "<string>",
      "version_numbers": [
        123
      ],
      "labels": [
        "<string>"
      ]
    }
  ],
  "prompt_templates_exclude": [
    {
      "name": "<string>",
      "version_numbers": [
        123
      ],
      "labels": [
        "<string>"
      ]
    }
  ],
  "scores": [
    {
      "name": "<string>",
      "operator": ">",
      "value": 1
    }
  ],
  "status": [
    "SUCCESS"
  ],
  "sort_by": "request_start_time",
  "sort_order": "asc",
  "include_fields": [
    "<string>"
  ],
  "transpose_metadata_columns": false
}
'
{
  "success": true,
  "message": "<string>",
  "dataset_id": 123,
  "dataset_group_id": 123,
  "version_number": 123
}
Create a new dataset version by filtering existing request logs. The dataset is populated asynchronously based on the provided filter parameters.

​
Authentication

This endpoint requires API key authentication only.

​
Asynchronous Processing

This endpoint initiates an asynchronous job to process the request logs based on the filter parameters. The actual dataset version creation happens in the background. A draft dataset (version_number = -1) is created immediately.

​
Webhooks

The following webhook is triggered when the process completes:
  • dataset_version_created_from_filter_params - Sent when the dataset version is successfully created, includes:
    • dataset_id: ID of the created dataset
    • rows_added: Number of rows added to the dataset
    • dataset_version_number: Final version number assigned

​
Notes

  • If an existing draft dataset exists for the dataset group, it will be updated with new filter params
  • If no matching request logs are found, an empty dataset version is created
  • Failed drafts are automatically cleaned up

​
Filtering by metadata

Metadata filters are provided as a list of {key, value} pairs under either metadata_and (all must match) or metadata_or (any must match). Values are compared as strings. 
{
  "dataset_group_id": 20123,
  "prompt_templates_include": [{ "name": "generate-summary" }],
  "metadata_and": [
    { "key": "app_name", "value": "local" }
  ],
  "start_time": "2026-04-22T17:00:00Z",
  "end_time": "2026-04-23T17:00:00Z",
  "limit": 25
}
Unknown fields in the request body are ignored silently, so a typo such as "metadata": { "app_name": "local" } will not produce an error — it simply will not filter. Use metadata_and / metadata_or exactly as shown above.

Headers

​
X-API-KEY
string
required

API key for authentication. This endpoint supports API key authentication only.

Body

application/json
​
dataset_group_id
integer
required

ID of the dataset group where the new version will be created.

Required range: x >= 1
​
variables_to_parse
string[]

List of input variables to extract as columns in the resulting dataset.

​
start_time
string<date-time>

Filter logs after this timestamp (ISO 8601). Example: 2026-04-22T17:00:00Z.

​
end_time
string<date-time>

Filter logs before this timestamp (ISO 8601). Example: 2026-04-23T17:00:00Z.

​
limit
integer

Maximum number of request logs to include. Capped at 50,000.

Required range: 0 <= x <= 50000
​
q
string

Free-text search query applied to the prompt input and LLM output.

​
id
integer

Filter to a single request log by its numeric id.

Required range: x >= 1
​
starred
boolean

When true, only include starred request logs.

​
order_by_random
boolean
default:false

When true, sample request logs in random order. Requires limit to be set.

​
metadata_and
object[]

Filter logs whose metadata matches ALL of the provided key/value pairs.

​
metadata_or
object[]

Filter logs whose metadata matches ANY of the provided key/value pairs.

​
tags_and
string[]

Filter logs that have ALL of the provided tags.

​
tags_or
string[]

Filter logs that have ANY of the provided tags.

​
prompt_templates_include
object[]

Include logs associated with any of these prompt templates. Matches by template name, with optional version and/or release label narrowing.

​
prompt_templates_exclude
object[]

Exclude logs associated with any of these prompt templates. Same shape as prompt_templates_include.

​
scores
object[]

Filter logs by score comparisons. Each entry asserts that the named score satisfies operator value.

​
status
enum<string>[]

Filter logs by request status.

Available options:
SUCCESS,
WARNING,
ERROR
​
sort_by
enum<string>

Field to sort results by.

Available options:
request_start_time,
input_tokens,
output_tokens,
price,
score,
latency,
prompt_name,
status
​
sort_order
enum<string>

Sort direction. Defaults to desc when sort_by is provided.

Available options:
asc,
desc
​
include_fields
string[]

Additional request-log fields to materialize as dataset columns.

​
transpose_metadata_columns
boolean
default:false

When true, pivot metadata keys into dataset columns. Requires metadata_and or metadata_or to be set.

Response

Dataset version creation job queued

​
success
boolean
required
​
message
string
required
​
dataset_id
integer
required

ID of the created draft dataset

​
dataset_group_id
integer
required

ID of the dataset group

​
version_number
integer
required

Version number of the dataset (-1 for draft)