Dataset API
The following article covers Sigma’s developer API for datasets. Datasets are a Sigma document type used for data modeling.
Dataset materialization is covered under Dataset Materialization API.
Summary of Content
Endpoints
The Dataset Object
Attributes
The Dataset List Object
Attributes
List Datasets
Permissions
Arguments
cURL Request
Response
Example
Look up a Dataset
Permissions
Parameters
cURL Request
Response
Example
Create or Update Dataset Grant
List Dataset Grants
Delete a Dataset Grant
Related Resources
Endpoints
GET /v2/datasets
Returns a list of datasets in your organization.
Try it in Swagger
GET /v2/datasets/{datasetId}
Returns a dataset object based on its unique identifier, datasetId.
Try it in Swagger
POST /datasets/{datasetId}/grants
Creates and/or updates a dataset's grants.
Try it in Swagger.
GET /v2/datasets/{datasetId}/grants
Returns a list grants associated with the requested dataset.
Try it in Swagger.
DELETE /v2/datasets/{datasetId}/grants/{grantId}
This endpoint deletes a dataset grant.
Try it in Swagger.
The Dataset Object
Attributes
datasetId string
The dataset’s unique identifier.
createdBy string
The unique identifier, memberId, of the organization member who created the dataset.
updatedBy string
The unique identifier, memberId, of the organization member who last modified changes to the dataset.
createdAt string
The timestamp at which the dataset was created.
updatedAt string
The timestamp at which the dataset was last modified.
name string
The dataset name.
url boolean
The URL path to the dataset.
IsArchived boolean | undefined
True if the dataset has been deleted.
{
"datasetId": "4337a3bb-d7a3-46e9-b929-ba264864e0ab",
"createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
"updatedBy": "8C2szXPJqLXpIezcD5adESnwfPUpp",
"createdAt": "2021-10-04T21:26:50.466Z",
"updatedAt": "2021-10-07T21:01:40.848Z",
"name": "Salesforce Campaigns",
"url": "https://app.sigmacomputing.com/my-org/b/32PUCBHcchwHcSg3l91Bin"
}
The Dataset List Object
Attributes
entries Array<Dataset>
A list of datasets matching the requested parameters.
Default number of entries per page: 50
hasMore boolean
True if additional datasets are available (accessible but not included in the current list).
total number
The total number of available datasets, including those on other pages.
Datasets in the organization that are not accessible by the user are excluded from this count.
nextPage string | null
The next page in the list of datasets. Used for pagination.
{
"entries": [
<Dataset>,
<Dataset>,
...
],
"hasMore": true,
"total": 63,
"nextPage": "50"
}
List Datasets
Returns a list of datasets in your organization. Pagination may be required to access all available datasets.
GET /v2/datasets
Permissions
-
You will only have access to the datasets available in Sigma to the user account associated with the API access token.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
page string [optional]
An identifier used for pagination.
limit number [optional]
The number of datasets to be returned.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/datasets?page={page}&limit={limit} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns Array<Dataset>.
{
"entries": [
<Dataset>,
<Dataset>,
...
],
"hasMore": boolean,
"total": number,
"nextPage": string | null
}
Example
Example Request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/datasets' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{
"entries": [
{
"datasetId": "4337a3bb-d7a3-46e9-b929-ba264864e0ab",
"createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
"updatedBy": "8C2szXPJqLXpIezcD5adESnwfPUpp",
"createdAt": "2021-10-04T21:26:50.466Z",
"updatedAt": "2021-10-07T21:01:40.848Z",
"name": "Salesforce Campaigns",
"url": "https://app.sigmacomputing.com/my-org/b/32PUCBHcchwHcSg3l91Bin"
},
{
"datasetId": "9551t76d-23f7-4195-ad98-d9d2578c7d05",
"createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
"updatedBy": "6VZpXc5Pl6XpIezcD5adtYi23Pt1u",
"createdAt": "2021-10-04T21:14:25.963Z",
"updatedAt": "2021-10-07T21:01:40.848Z",
"name": "Sales by Product Group",
"url": "https://app.sigmacomputing.com/my-org/b/4xLe1KDR78M9cmYkgYJrtX"
},
...
],
"hasMore": false,
"total": 2,
"nextPage": null
}
Look up a Dataset
Returns a dataset object based on its unique identifier, datasetId.
GET /v2/datasets/{datasetId}
Permissions
-
You will only have access to the datasets available in Sigma to the user account associated with the API access token.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
None
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/datasets/{datasetId} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns a dataset object.
{
"datasetId": string,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string,
"name": string,
"url": string,
"isArchived": boolean,
}
Example
Example Request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/datasets/4337a3bb-d7a3-46e9-b929-ba264864e0ab' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{
"datasetId": "9551t76d-23f7-4195-ad98-d9d2578c7d05",
"createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
"updatedBy": "6VZpXc5Pl6XpIezcD5adtYi23Pt1u",
"createdAt": "2021-10-04T21:14:25.963Z",
"updatedAt": "2021-10-07T21:01:40.848Z",
"name": "Sales by Product Group",
"url": "https://app.sigmacomputing.com/my-org/b/4xLe1KDR78M9cmYkgYJrtX"
}
Create or Update Dataset Grant
Creates and/or updates a dataset's grants.
POST /datasets/{datasetId}/grants
Permissions
- You must be an admin to use this endpoint.
Path Parameters
datasetId | string
The dataset’s unique identifier.
Request Parameters
grants | array <{grantee, permission}>
A list of one or more objects describing the grant(s) to be added.
Example — Single Grant
{
grantee: { memberId: string }
permission: string// 'edit', 'organize', 'explore', 'view'
}
tagId | string
The tag's unique identifier.
cURL Request
curl --location --request POST 'https://api.sigmacomputing.com/v2/{datasetId}/grants \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"grants": [
{
"grantee": {
"memberId": "MK56SY1jeAy3EcRYeqlzHJectzy60"
},
"permission": "view"
}
]
"tagId":"PS6Gy78pRtY9"
}'
Response
200 OK
{}List Dataset Grant
Returns a list grants associated with the requested dataset.
GET /v2/datasets/{datasetId}/grants
Permissions
- You must be an admin to use this endpoint.
Parameters
datasetId | string
The dataset’s unique identifier.
page | string [optional]
An identifier used for pagination.
limit | number [optional]
The number of datasets to be returned.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/{datasetId}/grants \
--header 'Authorization: Bearer {access_token}' \
Response
{
"entries": [
{
"grantId": "string",
"organizationId": "string",
"memberId": "string",
"teamId": "string",
"permission": "string",
"createdBy": "string",
"updatedBy": "string",
"createdAt": "2023-01-19T03:07:05.688Z",
"updatedAt": "2023-01-19T03:07:05.688Z"
}
],
"hasMore": true,
"nextPage": "string",
"total": 0
}
Delete Dataset Grant
This endpoint deletes a dataset grant.
DELETE /v2/datasets/{datasetId}/grants/{grantId}
Permissions
- You must be an admin to use this endpoint.
Parameters
grantId | string
The unique identifier associated with the grant.
cURL Request
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/{datasetId}/grants/{grantId} \
--header 'Authorization: Bearer {access_token}' \
Response
{}
Related Resources
API Documentation
Get Started with Sigma's API
Create an API Token and Client Id
Identify Unique Ids in Sigma