Skip to Content
API DocumentationAPI ReferenceDatasets

Dataset

Get dataset overview

GET /v2/team/datasets/{id}/overview

Retrieve basic information about the dataset, including keywords, description, and pre-generated questions.

Request Parameters

NameLocationTypeRequiredDescription
idpathstringYesThe ID of the target dataset.
user_idquerystringYesUser ID, which is your unique identifier within the organization.
x-pd-external-trace-idheaderstringNoTrace ID set in your local system, supporting up to 128 characters. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

Detailed Explanation

id: The ID of the target dataset.

To query the list of datasets you have access to, call the GET /v2/team/datasets API.

Response Example

{ "code": { "code": 0 }, "data": { "id": "dset-cm5axptyyxxx298", "name": "sales_indicators_2024", "description": "A dataset comprising 373 travel bookings with 15 attributes, offering insights into booking patterns, pricing strategies, and more", "summary": "This dataset contains 373 travel bookings with 15 attributes, enabling analysis of booking trends, pricing strategies, and travel agency dynamics.", "exploration_questions": [ "How does the booking price trend over time based on the BookingTimestamp?", "How does the average booking price change with respect to the TravelDate?", "Are there any significant outliers in the booking prices, and what might be causing them?", "How does the average price vary between one-way and round-trip bookings?" ], "keywords": [ "Travel Bookings", "Booking Trends", "Travel Agencies" ] } }

Response Results

Status CodeMeaningDescriptionData Model
200OKnoneInline

Response Data Structure

Status Code 200

NameTypeRequiredConstraintsChinese NameDescription
» codeobjecttruenonenone
»» codeintegertruenoneStatus code. 0 indicates a successful operation. Other values indicate a failed operation. For error troubleshooting, please refer to Error Codes.
» dataobjecttruenoneDataset object.
»» idstringtruenoneDataset ID, the unique identifier of the dataset in the project.
»» namestringtruenoneDataset name.
»» descriptionstringtruenoneDataset description.
»» summarystringtruenoneOverview of the data source in the dataset.
»» exploration_questions[string]truenonePre-generated questions by MAXIR AI to help explore the data within the dataset.
»» keywords[string]truenoneDataset keywords to help better understand the dataset content.

Create dataset

POST /v2/team/datasets

Create a dataset.

A dataset is a collection of related data sources. Data sources can be in formats such as Excel, CSV, PDF, Word, web pages, Markdown, plain text, etc. Using datasets can make accessing and utilizing your data for analysis more efficient. You can create a dataset to store all necessary data sources for specific analysis. Then, during a Q&A session, you can associate the dataset with the session to access all the data sources within the dataset.

Body Request Parameters

{ "name": "My dataset", "description": "my default dataset", "user_id": "tmm-dafasdfasdfasdf" }

Request Parameters

NameLocationTypeRequiredDescription
x-pd-external-trace-idheaderstringNoTrace ID set in your local system, supporting up to 128 characters. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.
bodybodyobjectNonone
» namebodystringYesDataset name, supporting up to 128 characters. If it exceeds this limit, the name will be truncated for display.
» descriptionbodystringNoDataset description, supporting up to 5000 characters. If it exceeds this limit, the description will be truncated for display.
» user_idbodystringYesUser ID, your unique identifier within the organization.

Response Example

{ "code": 0, "data": { "id": "dataset-adsdfasafdsfasdgasd" } }

Response Results

Status CodeMeaningDescriptionData Model
200OKnoneInline

Response Data Structure

Status Code 200

NameTypeRequiredConstraintsChinese NameDescription
» codeintegertruenoneStatus code. 0 indicates a successful operation. Other values indicate a failed operation. For error troubleshooting, please refer to Error Codes.
» dataobjecttruenonenone
»» idstringtruenoneDataset ID.

To upload data sources to this dataset or associate it with a task for data analysis and exploration, please save this dataset ID.

Response Header

StatusHeaderTypeFormatDescription
200x-pd-trace-idstringTrace ID returned by MAXIR AI. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

List datasets

GET /v2/team/datasets

Returns a list of datasets.

This API will only return datasets from the same project as your API key.

You can specify a search keyword to filter datasets by name or description.

Request Parameters

NameLocationTypeRequiredDescription
page_numberqueryintegerNoStarting page number for paginated returns. If not specified, the default value 1 will be used.
page_sizequeryintegerNoNumber of records returned per page. If not specified, the default value 10 will be used.
searchquerystringNoSearch keyword, supporting up to 128 characters. All datasets with this keyword in their name or description will be returned.
user_idquerystringYesUser ID, which is your unique identifier within the organization.
x-pd-external-trace-idheaderstringNoTrace ID set in your local system, supporting up to 128 characters. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

Detailed Explanation

search: Search keyword, supporting up to 128 characters. All datasets with this keyword in their name or description will be returned.

If omitted, all datasets in the project will be listed.

Response Example

{ "code": 0, "data": { "page_number": 1, "page_size": 10, "total_items": 1, "records": [ { "id": "dataset-dasfadsgadsgas", "name": "mysql", "description": "mysql databases" } ] } }

Response Results

Status CodeMeaningDescriptionData Model
200OKnoneInline

Response Data Structure

Status Code 200

NameTypeRequiredConstraintsChinese NameDescription
» codeintegertruenoneStatus code. 0 indicates a successful operation. Other values indicate a failed operation. For error troubleshooting, please refer to Error Codes.
» dataobjecttruenoneReturned data object.
»» page_numberintegertruenonePage number of the current page.
»» page_sizeintegertruenoneNumber of datasets returned per page.
»» total_itemsintegertruenoneTotal number of datasets returned.
»» recordsobjecttruenoneList of datasets returned on the current page.
»»» idstringtruenoneDataset ID, the unique identifier of the dataset in the project.
»»» namestringtruenoneDataset name.
»»» descriptionstringtruenoneDataset description.

Response Header

StatusHeaderTypeFormatDescription
200x-pd-trace-idstringTrace ID returned by MAXIR AI. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

Delete dataset

DELETE /v2/team/datasets/{id}

Delete the dataset. Once deleted, all data sources in the dataset will be permanently removed and cannot be recovered.

Body Request Parameters

{ "user_id": "tmm-dafasdfasdfasdf" }

Request Parameters

NameLocationTypeRequiredDescription
idpathstringYesTarget dataset ID. You can only delete datasets you have created.
x-pd-external-trace-idheaderstringNoTrace ID set in your local system, supporting up to 128 characters. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.
bodybodyobjectNonone
» user_idbodystringYesUser ID, which is your unique identifier within the organization.

Detailed Explanation

id: Target dataset ID. You can only delete datasets you have created.

To query the list of datasets you have access to, call the GET /v2/team/datasets API.

Response Example

200 Response

{ "code": 0, "data": {} }

Response Results

Status CodeMeaningDescriptionData Model
200OKnoneInline

Response Data Structure

Status Code 200

NameTypeRequiredConstraintsChinese NameDescription
» codeintegertruenoneStatus code. 0 indicates a successful operation. Other values indicate a failed operation. For error troubleshooting, please refer to Error Codes.
» dataobjectfalsenoneIf successful, returns null.

Response Header

StatusHeaderTypeFormatDescription
200x-pd-trace-idstringTrace ID returned by MAXIR AI. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

Modify dataset

POST /v2/team/datasets/{id}

Modify the name or description of a specified dataset.

Body Request Parameters

{ "name": "sales_data", "description": "sales data of all regions", "user_id": "tmm-dsadfdsafasdf" }

Request Parameters

NameLocationTypeRequiredDescription
idpathstringYesTarget dataset ID. You can only modify datasets you have created.
x-pd-external-trace-idheaderstringNoTrace ID set in your local system, supporting up to 128 characters. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.
bodybodyobjectNonone
» namebodystringNoNew name for the dataset, supporting up to 128 characters. If it exceeds this limit, the name will be truncated for display.
» descriptionbodystringNoNew description for the dataset, supporting up to 5000 characters. If it exceeds this limit, the description will be truncated for display.
» user_idbodystringYesUser ID, your unique identifier within the organization.

Detailed Explanation

id: Target dataset ID. You can only modify datasets you have created.

To query the list of datasets you have access to, call the GET /v2/team/datasets API.

» name: New name for the dataset, supporting up to 128 characters. If it exceeds this limit, the name will be truncated for display.

You must specify at least one of name or description.

» description: New description for the dataset, supporting up to 5000 characters. If it exceeds this limit, the description will be truncated for display.

You must specify at least one of name or description.

Response Example

200 Response

{ "code": 0, "data": {} }

Response Results

Status CodeMeaningDescriptionData Model
200OKnoneInline

Response Data Structure

Status Code 200

NameTypeRequiredConstraintsChinese NameDescription
» codeintegertruenoneStatus code. 0 indicates a successful operation. Other values indicate a failed operation. For error troubleshooting, please refer to Error Codes.
» dataobjecttruenoneIf successful, returns null.

Response Header

StatusHeaderTypeFormatDescription
200x-pd-trace-idstringTrace ID returned by MAXIR AI. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

Get status summary of data sources in dataset

GET /v2/team/datasets/{id}/status

This API calculates and returns the count of data sources in each state within a specified dataset. You can use this API to check whether all data sources in the dataset have completed synchronization and are available for data analysis tasks.

Only when both invalid_count and synching_count return 0 can all data sources in the dataset be used for Q&A. Otherwise, MAXIR AI will not be able to perform data analysis and exploration with unsynchronized data sources.

Request Parameters

NameLocationTypeRequiredDescription
idpathstringYesDataset ID for which you want to know the data source state.
user_idquerystringYesUser ID, which is your unique identifier within the organization.
x-pd-external-trace-idheaderstringNoTrace ID set in your local system, supporting up to 128 characters. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.

Response Example

{ "code": 0, "data": { "synched_count": 5, "invalid_count": 0, "synching_count": 0 } }

Response Results

Status CodeMeaningDescriptionData Model
200OKnoneInline

Response Data Structure

Status Code 200

NameTypeRequiredConstraintsChinese NameDescription
» codeintegertruenoneStatus code. 0 indicates a successful operation. Other values indicate a failed operation. For error troubleshooting, please refer to Error Codes.
» dataobjecttruenoneCount of data sources in each state.

Note that only when invalid_count and synching_count are both 0 can all data sources in the dataset be used for Q&A with MAXIR AI. Otherwise, MAXIR AI will not be able to use unsynchronized data sources for data analysis and exploration.
»» synched_countintegertruenoneCount of synchronized data sources.
»» invalid_countintegertruenoneCount of data sources with failed synchronization.
»» synching_countintegertruenoneCount of data sources waiting for or undergoing synchronization.

Response Header

StatusHeaderTypeFormatDescription
200x-pd-trace-idstringTrace ID returned by MAXIR AI. This ID can be provided to the MAXIR AI team for error troubleshooting when an issue occurs.