Search documentation
karat

+

K

User Documentation ↗

List Files

GET/api/v2/datasets/{datasetRid}/files
Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Lists Files contained in a Dataset. By default files are listed on the latest view of the default branch - master for most enrollments.

Advanced Usage

See Datasets Core Concepts for details on using branches and transactions. To list files on a specific Branch specify the Branch's name as branchName. This will include the most recent version of all files since the latest snapshot transaction, or the earliest ancestor transaction of the branch if there are no snapshot transactions. To list files on the resolved view of a transaction specify the Transaction's resource identifier as endTransactionRid. This will include the most recent version of all files since the latest snapshot transaction, or the earliest ancestor transaction if there are no snapshot transactions. To list files on the resolved view of a range of transactions specify the the start transaction's resource identifier as startTransactionRid and the end transaction's resource identifier as endTransactionRid. This will include the most recent version of all files since the startTransactionRid up to the endTransactionRid. Note that an intermediate snapshot transaction will remove all files from the view. Behavior is undefined when the start and end transactions do not belong to the same root-to-leaf path. To list files on a specific transaction specify the Transaction's resource identifier as both the startTransactionRid and endTransactionRid. This will include only files that were modified as part of that Transaction.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:datasets-read.

Path parameters

datasetRid
string

The Resource Identifier (RID) of a Dataset.

Query parameters

branchName
string
optional

The name of the Branch on which to list Files. Defaults to master for most enrollments.

startTransactionRid
string
optional

The Resource Identifier (RID) of the start Transaction.

endTransactionRid
string
optional

The Resource Identifier (RID) of the end Transaction.

pageSize
integer
optional

The page size to use for the endpoint.

pageToken
string
optional

The page token indicates where to start paging. This should be omitted from the first page's request. To fetch the next page, clients should take the value from the nextPageToken field of the previous response and populate the next request's pageToken field with it.

preview
boolean
optional

Enables the use of preview functionality.

Response body

ListFilesResponse
object
Hide children

Hide children

data
list<File>
optional
Show children

Show children

File
object
Show children

Show children

path
string

The path to a File within Foundry. Examples: my-file.txt, path/to/my-file.jpg, dataframe.snappy.parquet.

transactionRid
string

The Resource Identifier (RID) of a Transaction.

sizeBytes
string
optional
updatedTime
string
nextPageToken
string
optional

The page token indicates where to start paging. This should be omitted from the first page's request. To fetch the next page, clients should take the value from the nextPageToken field of the previous response and populate the next request's pageToken field with it.

Examples

Request

Copied!
1 2 3 curl \ -H "Authorization: Bearer $TOKEN" \ "https://$HOSTNAME/api/v2/datasets/ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da/files?branchName=master&startTransactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4&endTransactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4&pageSize=100&pageToken=v1.VGhlcmUgaXMgc28gbXVjaCBsZWZ0IHRvIGJ1aWxkIC0gcGFsYW50aXIuY29tL2NhcmVlcnMv&preview=true"

Response

Copied!
1 2 3 4 5 6 7 8 { "data": [ { "transactionRid": "ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4" } ], "nextPageToken": "v1.VGhlcmUgaXMgc28gbXVjaCBsZWZ0IHRvIGJ1aWxkIC0gcGFsYW50aXIuY29tL2NhcmVlcnMv" }