> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/api/datasets.md).
# Datasets
## List Dataset Snapshots
> Lists datasets in the workspace that have a successful snapshot.\
> \
> Each item is the latest successful snapshot for one dataset. \`id\` is the\
> dataset id. \`last\_dataset\_snapshot\_id\` is the snapshot id to pass to\
> GET /v1/workspaces/{workspace\_id}/dataset\_snapshots/{id}.\
> \
> The list contains at most 200 datasets, newest successful run first.\
> \`meta.total\_count\` is the number of matches before that limit.\
> \
> Filter with \`query\`, \`source\`, \`name\`, or \`dataflow\_id\`.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"dataset_snapshots.collection.response":{"type":"object","properties":{"meta":{"type":"object","description":"Totals for the list.","properties":{"total_count":{"type":"integer","description":"Number of matching datasets before the 200-item limit."}},"required":["total_count"]},"datasets":{"type":"array","description":"Matching datasets, newest successful run first. At most 200.","items":{"$ref":"#/components/schemas/dataset_snapshots.item.response"}}},"required":["meta","datasets"]},"dataset_snapshots.item.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataset. Same value as `dataset_id` on GET /v1/workspaces/{workspace_id}/dataset_snapshots/{id}."},"name":{"type":"string","description":"Name of the dataset."},"dataflow_id":{"type":"string","format":"uuid","description":"Id of the parent dataflow."},"dataflow_name":{"type":"string","description":"Name of the parent dataflow."},"last_successful_execution_id":{"type":"string","format":"uuid","description":"Id of the successful execution that produced this snapshot."},"last_success_run_at":{"type":["string","null"],"format":"date-time","description":"When the dataflow last ran successfully, in ISO 8601. Null when it has not."},"rows_count":{"type":"integer","description":"Number of rows in the snapshot."},"last_dataset_snapshot_id":{"type":"string","format":"uuid","description":"Id of this snapshot. Pass it to GET /v1/workspaces/{workspace_id}/dataset_snapshots/{id}."},"table_name":{"type":"string","description":"Dataset table name used in SQL queries within the same dataflow."},"preview_url":{"type":"string","description":"Coupler.io page where the user can review the dataset."},"type":{"type":["string","null"],"description":"Dataset transformation type, such as customSql. Null when the dataset has no complex transformation. Only customSql datasets support SQL query updates."}},"required":["id","name","dataflow_id","dataflow_name","last_successful_execution_id","last_success_run_at","rows_count","last_dataset_snapshot_id","table_name","preview_url","type"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataset_snapshots":{"get":{"summary":"List Dataset Snapshots","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Text matched against the dataset name, dataflow name, source name, and source key.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"Source integration key or name. Combined with `name` and `query` when those are also set.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Text matched against the dataset name and source name. Does not match the dataflow name.","schema":{"type":"string"}},{"name":"dataflow_id","in":"query","required":false,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"description":"Lists datasets in the workspace that have a successful snapshot.\n\nEach item is the latest successful snapshot for one dataset. `id` is the\ndataset id. `last_dataset_snapshot_id` is the snapshot id to pass to\nGET /v1/workspaces/{workspace_id}/dataset_snapshots/{id}.\n\nThe list contains at most 200 datasets, newest successful run first.\n`meta.total_count` is the number of matches before that limit.\n\nFilter with `query`, `source`, `name`, or `dataflow_id`.\n","responses":{"200":{"description":"datasets with a successful snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dataset_snapshots.collection.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}}}}}}
```
## Get Dataset Snapshot
> Returns one dataset snapshot.\
> \
> \`id\` is \`last\_dataset\_snapshot\_id\` from the list. \`dataset\_id\` is the\
> dataset. \`columns\` are the visible columns.\
> \
> \`ai\_context\` is markdown describing the dataset, or null when none is set.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"dataset_snapshots.member.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of this snapshot. Same value as `last_dataset_snapshot_id` on the list."},"dataset_id":{"type":"string","format":"uuid","description":"Id of the dataset. Same value as `id` on the list."},"type":{"type":["string","null"],"description":"Dataset transformation type, such as customSql. Null when the dataset has no complex transformation."},"ai_context":{"type":["string","null"],"description":"Markdown describing the dataset. Null when none is set."},"columns":{"type":"array","description":"Visible columns. Hidden and skipped columns are omitted.","items":{"type":"object","properties":{"key":{"type":"string","description":"Column key used in SQL queries."},"label":{"type":["string","null"],"description":"Human-readable column label. Null when none is set."},"dbName":{"type":"string","description":"Column name in the underlying data table."},"schema":{"type":"object","description":"Column type schema, when available.","additionalProperties":true},"description":{"type":"string","description":"Column description, when set."}},"required":["key","label","dbName"]}}},"required":["id","dataset_id","type","ai_context","columns"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataset_snapshots/{id}":{"get":{"summary":"Get Dataset Snapshot","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataset snapshot. Use `last_dataset_snapshot_id` from GET /v1/workspaces/{workspace_id}/dataset_snapshots.","schema":{"type":"string"}}],"description":"Returns one dataset snapshot.\n\n`id` is `last_dataset_snapshot_id` from the list. `dataset_id` is the\ndataset. `columns` are the visible columns.\n\n`ai_context` is markdown describing the dataset, or null when none is set.\n","responses":{"200":{"description":"dataset snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dataset_snapshots.member.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataset snapshot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}}}}}}
```
## Update dataset column labels and descriptions
> Updates labels and descriptions on a dataset's columns.\
> \
> Each item in \`column\_updates\` matches a column by \`key\`. \`label\` and\
> \`description\` can be set or cleared with null. Omitted fields stay\
> unchanged. The response lists the keys that were updated.\
> \
> Custom SQL datasets accept description updates. A label change on a\
> custom SQL dataset is rejected; rename the column with a SQL alias\
> instead.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"datasets.columns_update.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataset."},"updated_column_keys":{"type":"array","description":"Keys of the columns that were updated.","items":{"type":"string"}}},"required":["id","updated_column_keys"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/datasets/{dataset_id}/columns":{"patch":{"summary":"Update dataset column labels and descriptions","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"dataset_id","in":"path","required":true,"description":"Id of the dataset. Use an id from GET /v1/workspaces/{workspace_id}/datasets.","schema":{"type":"string"}}],"description":"Updates labels and descriptions on a dataset's columns.\n\nEach item in `column_updates` matches a column by `key`. `label` and\n`description` can be set or cleared with null. Omitted fields stay\nunchanged. The response lists the keys that were updated.\n\nCustom SQL datasets accept description updates. A label change on a\ncustom SQL dataset is rejected; rename the column with a SQL alias\ninstead.\n","responses":{"200":{"description":"column labels and descriptions updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/datasets.columns_update.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"422":{"description":"custom SQL datasets reject label updates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"column_updates":{"type":"array","description":"Columns to update. Match each column by `key`. Omitted fields stay unchanged.","items":{"type":"object","properties":{"key":{"type":"string","description":"Column key from the dataset."},"label":{"type":["string","null"],"description":"Human-readable column label. Null clears it."},"description":{"type":["string","null"],"description":"Column description. Null clears it."}},"required":["key"]}}},"required":["column_updates"]}}}}}}}}
```
## List Datasets
> Lists datasets in the workspace.\
> \
> Each item includes \`state\` and \`queryable\`. \`legend\` explains those values.\
> A dataset can have a snapshot and still have \`queryable\` false when its rows\
> are not shared for analysis. \`id\` is the dataset id to pass to\
> GET /v1/workspaces/{workspace\_id}/datasets/{id}.\
> \
> The list contains at most 200 datasets, newest successful run first.\
> \`meta.total\_count\` is the number of matches before that limit.\
> \
> Filter with \`query\`, \`source\`, \`name\`, or \`dataflow\_id\`.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"datasets.collection.response":{"type":"object","properties":{"meta":{"type":"object","description":"Totals for the list.","properties":{"total_count":{"type":"integer","description":"Number of matching datasets before the 200-item limit."}},"required":["total_count"]},"datasets":{"type":"array","description":"Matching datasets, newest successful run first. At most 200.","items":{"$ref":"#/components/schemas/datasets.item.response"}},"legend":{"type":"object","description":"Meaning of `state` and `queryable` on each dataset.","properties":{"state":{"type":"object","description":"Human-readable meaning of each dataset state.","additionalProperties":{"type":"string"}},"queryable":{"type":"string","description":"When row data is available for analysis."}},"required":["state","queryable"]}},"required":["meta","datasets","legend"]},"datasets.item.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataset. Pass it to GET /v1/workspaces/{workspace_id}/datasets/{id}."},"name":{"type":"string","description":"Name of the dataset."},"dataflow_id":{"type":"string","format":"uuid","description":"Id of the parent dataflow."},"dataflow_name":{"type":"string","description":"Name of the parent dataflow."},"state":{"type":"string","enum":["FULL","FULL_STALE","SCHEMA_ONLY","SCHEMA_PENDING","NO_SCHEMA"],"description":"Dataset state. See `legend.state` for the meaning of each value."},"queryable":{"type":"boolean","description":"Whether row data is available for analysis. See `legend.queryable`."},"last_error":{"type":["string","null"],"description":"Error from the latest dataflow run. Null when the latest run succeeded or there has been no run."},"last_successful_execution_id":{"type":["string","null"],"description":"Id of the dataflow's last successful execution. Null when there has been none."},"last_success_run_at":{"type":["string","null"],"description":"When the dataflow last ran successfully, in ISO 8601. Null when it has not."},"rows_count":{"type":"integer","description":"Number of rows in the latest snapshot. 0 when there is no snapshot."},"last_dataset_snapshot_id":{"type":["string","null"],"description":"Id of the latest snapshot. Null when there is none. Pass it to GET /v1/workspaces/{workspace_id}/dataset_snapshots/{id}."},"table_name":{"type":"string","description":"Dataset table name used in SQL queries within the same dataflow."},"preview_url":{"type":"string","description":"Coupler.io page where the user can review the dataset."},"type":{"type":["string","null"],"description":"Dataset transformation type, such as customSql. Null when the dataset has no complex transformation. Only customSql datasets support SQL query updates."}},"required":["id","name","dataflow_id","dataflow_name","state","queryable","last_error","last_successful_execution_id","last_success_run_at","rows_count","last_dataset_snapshot_id","table_name","preview_url","type"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/datasets":{"get":{"summary":"List Datasets","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Text matched against the dataset name, dataflow name, source name, and source key.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"Source integration key or name. Combined with `name` and `query` when those are also set.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Text matched against the dataset name and source name. Does not match the dataflow name.","schema":{"type":"string"}},{"name":"dataflow_id","in":"query","required":false,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"description":"Lists datasets in the workspace.\n\nEach item includes `state` and `queryable`. `legend` explains those values.\nA dataset can have a snapshot and still have `queryable` false when its rows\nare not shared for analysis. `id` is the dataset id to pass to\nGET /v1/workspaces/{workspace_id}/datasets/{id}.\n\nThe list contains at most 200 datasets, newest successful run first.\n`meta.total_count` is the number of matches before that limit.\n\nFilter with `query`, `source`, `name`, or `dataflow_id`.\n","responses":{"200":{"description":"datasets in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/datasets.collection.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}}}}}}
```
## Show Dataset
> Returns one dataset.\
> \
> \`state\` and \`queryable\` use the same values as the list. \`columns\` are the\
> visible columns. \`query\` is the SQL statement, or null when the dataset is\
> not customSql. \`ai\_context\` is markdown describing the dataset, or null when\
> none is set.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"datasets.member.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataset."},"name":{"type":"string","description":"Name of the dataset."},"dataflow_id":{"type":"string","format":"uuid","description":"Id of the parent dataflow."},"dataflow_name":{"type":"string","description":"Name of the parent dataflow."},"state":{"type":"string","enum":["FULL","FULL_STALE","SCHEMA_ONLY","SCHEMA_PENDING","NO_SCHEMA"],"description":"Dataset state. See the list `legend.state` for each value."},"queryable":{"type":"boolean","description":"Whether row data is available for analysis."},"last_error":{"type":["string","null"],"description":"Error from the latest dataflow run. Null when the latest run succeeded or there has been no run."},"last_successful_execution_id":{"type":["string","null"],"description":"Id of the dataflow's last successful execution. Null when there has been none."},"last_success_run_at":{"type":["string","null"],"description":"When the dataflow last ran successfully, in ISO 8601. Null when it has not."},"rows_count":{"type":"integer","description":"Number of rows in the latest snapshot. 0 when there is no snapshot."},"last_dataset_snapshot_id":{"type":["string","null"],"description":"Id of the latest snapshot. Null when there is none."},"table_name":{"type":"string","description":"Dataset table name used in SQL queries within the same dataflow."},"preview_url":{"type":"string","description":"Coupler.io page where the user can review the dataset."},"type":{"type":["string","null"],"description":"Dataset transformation type, such as customSql. Null when the dataset has no complex transformation. Only customSql datasets support SQL query updates."},"query":{"type":["string","null"],"description":"SQL query of the dataset. Null when the dataset is not customSql."},"ai_context":{"type":["string","null"],"description":"Markdown describing the dataset. Null when none is set."},"columns":{"type":"array","description":"Visible columns. Hidden and skipped columns are omitted.","items":{"$ref":"#/components/schemas/datasets.column.response"}}},"required":["id","name","dataflow_id","dataflow_name","state","queryable","last_error","last_successful_execution_id","last_success_run_at","rows_count","last_dataset_snapshot_id","table_name","preview_url","type","query","ai_context","columns"]},"datasets.column.response":{"type":"object","properties":{"key":{"type":"string","description":"Column key used in SQL queries."},"label":{"type":["string","null"],"description":"Human-readable column label. Null when none is set."},"dbName":{"type":"string","description":"Column name in the underlying data table."},"schema":{"type":"object","description":"Column type schema, when available.","additionalProperties":true},"description":{"type":"string","description":"Column description, when set."}},"required":["key","label","dbName"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/datasets/{id}":{"get":{"summary":"Show Dataset","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataset. Use an id from GET /v1/workspaces/{workspace_id}/datasets.","schema":{"type":"string"}}],"description":"Returns one dataset.\n\n`state` and `queryable` use the same values as the list. `columns` are the\nvisible columns. `query` is the SQL statement, or null when the dataset is\nnot customSql. `ai_context` is markdown describing the dataset, or null when\nnone is set.\n","responses":{"200":{"description":"dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/datasets.member.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}}}}}}
```
## Update Dataset
> Updates a dataset name, context, or SQL query.\
> \
> \`name\` and \`ai\_context\` can be set or cleared with null. To change the\
> SQL, send \`query\`. \`type\` is optional; when it is included it must be\
> customSql. Only customSql datasets accept a query, and the query must be\
> a SELECT. The response is the updated dataset, including columns detected\
> from the query.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"datasets.member.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataset."},"name":{"type":"string","description":"Name of the dataset."},"dataflow_id":{"type":"string","format":"uuid","description":"Id of the parent dataflow."},"dataflow_name":{"type":"string","description":"Name of the parent dataflow."},"state":{"type":"string","enum":["FULL","FULL_STALE","SCHEMA_ONLY","SCHEMA_PENDING","NO_SCHEMA"],"description":"Dataset state. See the list `legend.state` for each value."},"queryable":{"type":"boolean","description":"Whether row data is available for analysis."},"last_error":{"type":["string","null"],"description":"Error from the latest dataflow run. Null when the latest run succeeded or there has been no run."},"last_successful_execution_id":{"type":["string","null"],"description":"Id of the dataflow's last successful execution. Null when there has been none."},"last_success_run_at":{"type":["string","null"],"description":"When the dataflow last ran successfully, in ISO 8601. Null when it has not."},"rows_count":{"type":"integer","description":"Number of rows in the latest snapshot. 0 when there is no snapshot."},"last_dataset_snapshot_id":{"type":["string","null"],"description":"Id of the latest snapshot. Null when there is none."},"table_name":{"type":"string","description":"Dataset table name used in SQL queries within the same dataflow."},"preview_url":{"type":"string","description":"Coupler.io page where the user can review the dataset."},"type":{"type":["string","null"],"description":"Dataset transformation type, such as customSql. Null when the dataset has no complex transformation. Only customSql datasets support SQL query updates."},"query":{"type":["string","null"],"description":"SQL query of the dataset. Null when the dataset is not customSql."},"ai_context":{"type":["string","null"],"description":"Markdown describing the dataset. Null when none is set."},"columns":{"type":"array","description":"Visible columns. Hidden and skipped columns are omitted.","items":{"$ref":"#/components/schemas/datasets.column.response"}}},"required":["id","name","dataflow_id","dataflow_name","state","queryable","last_error","last_successful_execution_id","last_success_run_at","rows_count","last_dataset_snapshot_id","table_name","preview_url","type","query","ai_context","columns"]},"datasets.column.response":{"type":"object","properties":{"key":{"type":"string","description":"Column key used in SQL queries."},"label":{"type":["string","null"],"description":"Human-readable column label. Null when none is set."},"dbName":{"type":"string","description":"Column name in the underlying data table."},"schema":{"type":"object","description":"Column type schema, when available.","additionalProperties":true},"description":{"type":"string","description":"Column description, when set."}},"required":["key","label","dbName"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/datasets/{id}":{"patch":{"summary":"Update Dataset","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataset. Use an id from GET /v1/workspaces/{workspace_id}/datasets.","schema":{"type":"string"}}],"description":"Updates a dataset name, context, or SQL query.\n\n`name` and `ai_context` can be set or cleared with null. To change the\nSQL, send `query`. `type` is optional; when it is included it must be\ncustomSql. Only customSql datasets accept a query, and the query must be\na SELECT. The response is the updated dataset, including columns detected\nfrom the query.\n","responses":{"200":{"description":"dataset updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/datasets.member.response"}}}},"400":{"description":"type must be customSql","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"422":{"description":"query is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"502":{"description":"query preview could not be stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Dataset name. Null clears it."},"ai_context":{"type":["string","null"],"description":"Markdown describing the dataset. Null clears it."},"type":{"type":"string","description":"Optional. When included, must be customSql."},"query":{"type":"string","description":"SELECT statement that replaces the dataset query. Only customSql datasets accept a query."}}}}}}}}}}
```
## Query Dataset
> Runs a SELECT statement on the latest successful run of the dataset and\
> returns the rows. Show Dataset and Update Dataset read and change the\
> dataset definition.\
> \
> \> \*\*Warning: the query endpoint is for analytical queries, not for exports\*\*\
> \>\
> \> Use it to answer questions about a dataset: aggregates, filters, samples.\
> \> It returns at most \*\*10,000 rows\*\*. When a statement produces more,\
> \> the extra rows are dropped and the response has \`truncated: true\`.\
> \>\
> \> To export the data, add a destination to the dataflow instead of\
> \> returning the rows inline: a JSON or CSV file, or a data warehouse such\
> \> as BigQuery, Snowflake, Redshift, or PostgreSQL.\
> \
> \- The response returns at most 10,000 rows. \`truncated\` is true when the\
> statement produced more rows than that. Aggregate or filter the data,\
> or add \`LIMIT\`, to get a complete result.\
> \- The request has 60 seconds to load the snapshot and return the rows.\
> A longer query returns 504.\
> \
> Authenticate with the same \`Authorization: Bearer \\` header. Errors use\
> the same format as the other endpoints.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/datasets/{id}/query":{"post":{"summary":"Query Dataset","tags":["Datasets"],"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataset. Use an id from GET /v1/workspaces/{workspace_id}/datasets.","schema":{"type":"string"}}],"description":"Runs a SELECT statement on the latest successful run of the dataset and\nreturns the rows. Show Dataset and Update Dataset read and change the\ndataset definition.\n\n> **Warning: the query endpoint is for analytical queries, not for exports**\n>\n> Use it to answer questions about a dataset: aggregates, filters, samples.\n> It returns at most **10,000 rows**. When a statement produces more,\n> the extra rows are dropped and the response has `truncated: true`.\n>\n> To export the data, add a destination to the dataflow instead of\n> returning the rows inline: a JSON or CSV file, or a data warehouse such\n> as BigQuery, Snowflake, Redshift, or PostgreSQL.\n\n- The response returns at most 10,000 rows. `truncated` is true when the\n statement produced more rows than that. Aggregate or filter the data,\n or add `LIMIT`, to get a complete result.\n- The request has 60 seconds to load the snapshot and return the rows.\n A longer query returns 504.\n\nAuthenticate with the same `Authorization: Bearer ` header. Errors use\nthe same format as the other endpoints.\n","responses":{"200":{"description":"query results","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"One row. Keys are the column names or aliases from the SELECT list."},"description":"Rows returned by the query, at most 10,000."},"truncated":{"type":"boolean","description":"True when the statement produced more than 10,000 rows and only the first 10,000 are returned."}},"required":["rows","truncated"]}}}},"400":{"description":"request body is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"401":{"description":"token is missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"workspace is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"422":{"description":"the statement cannot be run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"504":{"description":"the query timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"statement":{"type":"string","description":"SELECT statement in the DuckDB SQL dialect. Read the dataset rows from the `data` table."}},"required":["statement"]}}},"required":true}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/api/datasets.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.