Lists Files contained in a Dataset. By default files are listed on the latest view of the default
branch - master for most enrollments.
See Datasets Core Concepts for details on using branches and transactions.
To list files on a specific Branch specify the Branch's identifier as branchId. 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.
stringThe identifier (name) of the Branch on which to list Files. Defaults to master for most enrollments.
stringThe Resource Identifier (RID) of the start Transaction.
stringThe Resource Identifier (RID) of the end Transaction.
integerThe desired size of the page to be returned. Defaults to 1,000. See page sizes for details.
stringThe 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 use it to populate the pageToken field of the next request.
objectA page of Files and an optional page token that can be used to retrieve the next page.
stringThe 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 use it to populate the pageToken field of the next request.
list<File>1
2
3
curl \
-H "Authorization: Bearer $TOKEN" \
"https://$HOSTNAME/api/v1/datasets/ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da/files?branchId=master&startTransactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4&endTransactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"nextPageToken": "v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z",
"data": [
{
"path": "q3-data/my-file.csv",
"transactionRid": "ri.foundry.main.transaction.bf9515c2-02d4-4703-8f84-c3b3c190254d",
"sizeBytes": "74930",
"updatedTime": "2022-10-10T16:44:55.192Z"
},
{
"path": "q2-data/my-file.csv",
"transactionRid": "ri.foundry.main.transaction.d8db1cfc-9f8b-4bad-9d8c-00bd818a37c5",
"sizeBytes": "47819",
"updatedTime": "2022-07-12T10:12:50.919Z"
},
{
"path": "q2-data/my-other-file.csv",
"transactionRid": "ri.foundry.main.transaction.d8db1cfc-9f8b-4bad-9d8c-00bd818a37c5",
"sizeBytes": "55320",
"updatedTime": "2022-07-12T10:12:46.112Z"
}
]
}| Error Name | ||
|---|---|---|
Invalid | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The given parameters are individually valid but cannot be used in the given combination. | |
| Parameters | validCombinations, providedParameters | |
Invalid | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The requested branch name cannot be used. Branch names cannot be empty and must not look like RIDs or UUIDs. | |
| Parameters | branchId | |
Branch | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The requested branch could not be found, or the client token does not have access to it. | |
| Parameters | datasetRid, branchId | |
Dataset | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The requested dataset could not be found, or the client token does not have access to it. | |
| Parameters | datasetRid | |
Transaction | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The requested transaction could not be found on the dataset, or the client token does not have access to it. | |
| Parameters | datasetRid, transactionRid | |
See Errors for a general overview of errors in the platform.