Datasets API

Use the Low Code Automation Datasets API to read the values that your tests saved to a writable test dataset.

When your tests save values to a writable test dataset, you can read those values from your own scripts or CI/CD pipelines. For example, you can clean up test records or pass generated IDs to another system. In the API, a writable test dataset is called an output dataset and has the output dataset type.

All endpoints on this page use the base URL https://lcnc-api.browserstack.com/api/v1/public and HTTP Basic authentication with your BrowserStack username and access key. Your plan must include test data management, and your role must have the View data configuration permission.

Read saved values

To read the values that your tests saved:

Find the ID of your project using the List projects endpoint. You can use either the project_id, for example PR-1, or the project_key, for example 22530.
Find the ID of the dataset using the List output datasets endpoint. You can also copy the ID from Metadata > Test dataset ID on the dataset page.
Optionally, check the details of the dataset, such as the row count, using the Get a dataset endpoint.
Read the rows using the List dataset rows endpoint. While has_more is true in the response, call the endpoint again with after set to the next_cursor value.

To fetch only the rows that were added since your last read, save the last next_cursor value and pass it as after in your next request. Row IDs are never reused, even after the dataset is cleared, so the response contains only new rows. The rowNumber value restarts at 1 after the dataset is cleared, so use id to track rows.

A build that writes to the dataset might still be running when you read it. In that case, all_writers_finished is false, and more rows might still arrive. Wait until all_writers_finished is true before you treat the data as complete.

In each row, columns that the step didn’t fill are returned as empty strings (""). For example, if a dataset has three columns and a step saves one value, the row contains one value and two empty strings. This is expected and doesn’t indicate data loss.

List output datasets

Fetches the writable test datasets in a project. This is the List datasets endpoint with the type parameter set to output.

GET /api/v1/public/projects/{project_id}/datasets

Request parameters

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  -X GET "https://lcnc-api.browserstack.com/api/v1/public/projects/PR-1/datasets?type=output" \
  -H "accept: application/json"

project_id^* string

Unique identifier of the project. Use either the integer Project Key, for example 22530, or the Project ID, for example PR-1. To find both, open your project, click Settings, then General, and look under Project details.
name string

Return only datasets whose name matches this value.
type string

Return only datasets of this type. Use input for datasets that provide data to tests, or output for datasets that tests write to. Any other value returns a 400 response.
page integer

Page to fetch. Pages are 1-based. The default is 1.
per_page integer

Number of records per page. The default is 50 and the maximum is 100.

Response attributes `200` `application/json`

{
  "datasets": [
    {
      "id": "728553e52f04f0c58bdec6b95df790f4b89c20a7",
      "name": "Order IDs",
      "description": "",
      "file_name": "Order IDs.csv",
      "column_names": ["Order IDs", "Products"],
      "column_count": 2,
      "row_count": 1,
      "dataset_type": "output",
      "clearing_behaviour": "reset_per_build",
      "row_ceiling": 100,
      "used_in_tests_count": 2,
      "used_in_modules_count": 0,
      "tests": [
        { "id": "437e9ce4328fa7e24b711fee15daee97bd038dfd", "name": "Checkout flow" },
        { "id": "6f88cd9e874a2a50e1300ff71c28ed1d9212461f", "name": "Untitled test" }
      ],
      "modules": []
    }
  ],
  "paging": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1, "best_effort": true }
}

datasets Array[Object]

Datasets that match the request.

▶ SHOW VALUES
- id String
  
  Unique identifier of the dataset.
- name String
  
  Name of the dataset.
- description String
  
  Description of the dataset. Empty string ("") when not set.
- file_name String
  
  Name of the uploaded file.
- column_names Array[String]
  
  Column names in the dataset.
- column_count Integer
  
  Number of columns.
- row_count Integer
  
  Number of rows.
- used_in_tests_count Integer
  
  Number of tests that use the dataset.
- used_in_modules_count Integer
  
  Number of modules that use the dataset.
- tests Array[Object]
  
  Tests that use the dataset.
  
  ▶ SHOW VALUES
  - id String
    
    Unique identifier.
  - name String
    
    Display name.
- modules Array[Object]
  
  Modules that use the dataset.
  
  ▶ SHOW VALUES
  - id String
    
    Unique identifier.
  - name String
    
    Display name.
- dataset_type String
  
  Type of the dataset. input for datasets that provide data to tests, and output for datasets that tests write to.
- clearing_behaviour String
  
  Data clearance schedule of the dataset. Possible values are accumulate (Never, the default), reset_per_build (Before every cloud run (Builds)), and scheduled (Custom). Returned as null for input datasets.
- row_ceiling Integer
  
  Maximum number of rows that a writable dataset can hold. Returned for every dataset, but applies only to writable datasets. The default is 100.
paging Object

Pagination details of the response.

▶ SHOW VALUES
- page Integer
  
  Page returned. Pages are 1-based.
- per_page Integer
  
  Number of records per page.
- total Integer
  
  Total number of records that match the request. When best_effort is true, this is an upper bound.
- total_pages Integer
  
  Total number of pages. When best_effort is true, this is an upper bound.
- best_effort Boolean
  
  Returned as true when total and total_pages are upper bounds rather than exact counts. When you see it, page through the results until you receive an empty list instead of relying on total_pages. Absent when the counts are exact.

Response `400` `application/json`

The value of type isn’t input or output.

{
  "error": {
    "code": "invalid_request",
    "message": "string"
  }
}

Get a dataset

Fetches the details of an output dataset, such as its columns, row count, and whether a build is still writing to it.

GET /api/v1/public/projects/{project_id}/datasets/{dataset_id}

Request parameters

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  -X GET "https://lcnc-api.browserstack.com/api/v1/public/projects/PR-1/datasets/YOUR_DATASET_ID" \
  -H "accept: application/json"

project_id^* string

Unique identifier of the project. Use either the integer Project Key, for example 22530, or the Project ID, for example PR-1. To find both, open your project, click Settings, then General, and look under Project details.
dataset_id^* string

Unique identifier of the dataset. Use the id returned by the List output datasets endpoint.

Response attributes `200` `application/json`

{
  "dataset": {
    "id": "728553e52f04f0c58bdec6b95df790f4b89c20a7",
    "name": "Order IDs",
    "description": "",
    "dataset_type": "output",
    "clearing_behaviour": "reset_per_build",
    "columns": ["Order IDs", "Products"],
    "row_count": 1,
    "row_ceiling": 100,
    "all_writers_finished": true
  }
}

dataset Object

Details of the dataset.

▶ SHOW VALUES
- id String
  
  Unique identifier of the dataset.
- name String
  
  Name of the dataset.
- description String
  
  Description of the dataset. Empty string ("") when not set.
- dataset_type String
  
  Type of the dataset. Always output for this endpoint.
- clearing_behaviour String
  
  Data clearance schedule of the dataset. Possible values are accumulate (Never, the default), reset_per_build (Before every cloud run (Builds)), and scheduled (Custom).
- columns Array[String]
  
  Column names in the dataset.
- row_count Integer
  
  Number of rows in the dataset.
- row_ceiling Integer
  
  Maximum number of rows that the dataset can hold. The default is 100.
- all_writers_finished Boolean
  
  Returned as false while a build that writes to the dataset is still running, which means more rows might still arrive. Returned as true when no such build is running.

Response `401` `application/json`

The username or access key is missing or invalid.

{
  "error": {
    "code": "unauthenticated",
    "message": "string"
  }
}

Response `403` `application/json`

Your plan doesn’t include test data management (forbidden_plan), or your role doesn’t have the View data configuration permission (forbidden_rbac).

{
  "error": {
    "code": "forbidden_rbac",
    "message": "string"
  }
}

Response `404` `application/json`

The project or dataset doesn’t exist, the dataset isn’t an output dataset, or the dataset belongs to another project or group.

{
  "error": {
    "code": "not_found",
    "message": "string"
  }
}

Response `503` `application/json`

An upstream dependency is temporarily unavailable. Retry the request.

{
  "error": {
    "code": "dependency_unavailable",
    "message": "string"
  }
}

List dataset rows

Fetches the rows that your tests saved to an output dataset, oldest first.

GET /api/v1/public/projects/{project_id}/datasets/{dataset_id}/rows

Request parameters

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  -X GET "https://lcnc-api.browserstack.com/api/v1/public/projects/PR-1/datasets/YOUR_DATASET_ID/rows?limit=100" \
  -H "accept: application/json"

project_id^* string

Unique identifier of the project. Use either the integer Project Key, for example 22530, or the Project ID, for example PR-1. To find both, open your project, click Settings, then General, and look under Project details.
dataset_id^* string

Unique identifier of the dataset. Use the id returned by the List output datasets endpoint.
limit integer

Number of rows to return. The default is 50 and the maximum is 100. Values above 100 are capped at 100. Values below 1 or non-numeric values fall back to 50.
after string

Row cursor to start after. Pass the next_cursor value from the previous response to fetch the next set of rows.

Response attributes `200` `application/json`

{
  "rows": [
    {
      "id": "132444",
      "rowNumber": 1,
      "data": {
        "Order IDs": "ORD-10234",
        "Products": "Wireless mouse"
      }
    }
  ],
  "meta": {
    "limit": 100,
    "next_cursor": "132444",
    "has_more": false,
    "all_writers_finished": true
  }
}

rows Array[Object]

Rows in the dataset, oldest first.

▶ SHOW VALUES
- id String
  
  Unique identifier of the row. Row IDs are never reused, even after the dataset is cleared.
- rowNumber Integer
  
  Position of the row in the dataset. Restarts at 1 after the dataset is cleared. To track rows, use id instead.
- data Object
  
  Values in the row, as key-value pairs of column name and saved value. Columns that the step didn’t fill are returned as empty strings ("").
meta Object

Pagination and completion details of the response.

▶ SHOW VALUES
- limit Integer
  
  Maximum number of rows in the response.
- next_cursor String
  
  Cursor for the next request. Pass it as the after parameter to fetch the rows that follow.
- has_more Boolean
  
  Returned as true when more rows are available after this response.
- all_writers_finished Boolean
  
  Returned as false while a build that writes to the dataset is still running, which means more rows might still arrive. Returned as true when no such build is running.

Response `400` `application/json`

The value of after isn’t a valid row cursor.

{
  "error": {
    "code": "invalid_request",
    "message": "string"
  }
}

Response `401` `application/json`

The username or access key is missing or invalid.

{
  "error": {
    "code": "unauthenticated",
    "message": "string"
  }
}

Response `403` `application/json`

Your plan doesn’t include test data management (forbidden_plan), or your role doesn’t have the View data configuration permission (forbidden_rbac).

{
  "error": {
    "code": "forbidden_plan",
    "message": "string"
  }
}

Response `404` `application/json`

The project or dataset doesn’t exist, the dataset isn’t an output dataset, or the dataset belongs to another project or group.

{
  "error": {
    "code": "not_found",
    "message": "string"
  }
}

Response `503` `application/json`

An upstream dependency is temporarily unavailable. Retry the request.

{
  "error": {
    "code": "dependency_unavailable",
    "message": "string"
  }
}

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Datasets API

Read saved values

List output datasets

Request parameters

project_id* string

name string

type string

page integer

per_page integer

Response attributes 200 application/json

datasets Array[Object]

id String

name String

description String

file_name String

column_names Array[String]

column_count Integer

row_count Integer

used_in_tests_count Integer

used_in_modules_count Integer

tests Array[Object]

id String

name String

modules Array[Object]

id String

name String

dataset_type String

clearing_behaviour String

row_ceiling Integer

paging Object

page Integer

per_page Integer

total Integer

total_pages Integer

best_effort Boolean

Response 400 application/json

Get a dataset

Request parameters

project_id* string

dataset_id* string

Response attributes 200 application/json

dataset Object

id String

name String

description String

dataset_type String

clearing_behaviour String

columns Array[String]

row_count Integer

row_ceiling Integer

all_writers_finished Boolean

Response 401 application/json

Response 403 application/json

Response 404 application/json

Response 503 application/json

List dataset rows

Request parameters

project_id* string

dataset_id* string

limit integer

after string

Response attributes 200 application/json

rows Array[Object]

id String

rowNumber Integer

data Object

meta Object

limit Integer

next_cursor String

has_more Boolean

all_writers_finished Boolean

Response 400 application/json

Response 401 application/json

Response 403 application/json

Response 404 application/json

Response 503 application/json

Related topics

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked

project_id^* string

Response attributes `200` `application/json`

Response `400` `application/json`

project_id^* string

dataset_id^* string

Response attributes `200` `application/json`

Response `401` `application/json`

Response `403` `application/json`

Response `404` `application/json`

Response `503` `application/json`

project_id^* string

dataset_id^* string

Response attributes `200` `application/json`

Response `400` `application/json`

Response `401` `application/json`

Response `403` `application/json`

Response `404` `application/json`

Response `503` `application/json`