> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/data-sources/get-data-sources.md).
# Search Data Sources
{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}
## Endpoints and methods
| Method | Path | Purpose |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **GET** | [`/dataSource`](#get-datasource) | Search for data sources. |
| **GET** | [`/dataSource/{dataSourceId}`](#get-datasource-datasourceid) | Get a data source based on the ID. |
| **GET** | [`/dataSource/name/{dataSourceName}`](#get-datasource-name-datasourcename) | Get data source based on the name. |
| **GET** | [`/dataSource/sqlTableName/{shortName}`](#get-datasource-sqltablename-shortname) | Get data source based on the short name. |
| **GET** | [`/dataSource/{dataSourceId}/access`](#get-datasource-datasourceid-access) | Get all users with the provided access level for this data source. |
| **GET** | [`/dataSource/{dataSourceId}/users/{profileId}/policyInfo`](#get-datasource-datasourceid-users-profileid-policyinfo) | Retrieves the visibilities, masking information, and filters that the passed in user has access to in the specified data source. |
| **GET** | [`/dataSource/{dataSourceId}/users/{profileId}/visibilityReport`](#get-datasource-datasourceid-users-profileid-visibilityreport) | Retrieves a summary of total records, total visibilities, and visibilities a given user has access to. |
| **GET** | [`/dataSource/{dataSourceId}/visibilityReport`](#get-datasource-datasourceid-visibilityreport) | Retrieves a summary of total records, total visibilities, and visibilities the current user has access to for a specified data source. |
| **GET** | [`/dataSource/{dataSourceId}/contacts`](#get-datasourcedatasourceidcontacts) | Gets the profiles for the data source owners and experts. |
| **GET** | [`/dataSource/byPurposes`](#get-datasourcebypurposes) | Get data sources that match a set of purposes. |
| **GET** | [`/dataSource/rpc/mine`](#get-datasourcerpcmine) | Retrieves all the data sources the current user has access to. |
| **GET** | [`/dataSource/{dataSourceId}/activities`](#get-datasourcedatasourceidactivities) | Get all of the recent policy activities for a given data source. |
| **GET** | [`/dataSource/{dataSourceId}/tags`](#get-datasourcedatasourceidtags) | Get the tags for a data source. |
## `GET` `/dataSource`
Search for data sources that you own or are authorized to see.
**Required**: For a data source to appear in the response, you must own the data source, the data source must be publicly visible, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource?size=2
```
### Query parameters
| Attribute | Description | Required |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| blobHandlerType | `array[string]` Describes the type of underlying blob handler that will be used with this data source (e.g., Custom, MS SQL). | No |
| subscription | `array[string]` The requesting user's subscription status: `pending`, `owner`, `subscribed`, `not_subscribed`, or `expert`. | No |
| status | `array[string]` The data source status: `passed` or `failed`. | No |
| tag | `array[string]` Filters data sources by tags associated with the data sources. | No |
| tagOperator | `string` Use with the `tag` attribute to search for data sources with multiple tags. Options are `AND` or `OR`. | No |
| tagModelTypes | `string` Use with the `tag` attribute to search for data sources with the tags applied to the `datasource` or the `column`. | No |
| searchText | `string` Searches for data source names using the provided `string`. | No |
| fuzzySearch | `boolean` If `true`, the search will ignore quotes and spaces. | No |
| column | `array[string]` Searches for data source column names. | No |
| connectionString | `array[string]` Searches by connection string. | No |
| schema | `string` Searches for data source schema. | No |
| nameOnly | `boolean` When `true`, `searchText` will only search data source names. **Default is `false`.** | No |
| idOnly | `boolean` When `true`, only returns the ID of the data source and the user's subscription status. `count` will be `0` in the response if `idOnly` is set to `true`. | No |
| dataSourceIds | `array[integer]` Searches for the provided data source IDs. | No |
| selectFields | `array[string]` This field accepts the values `id`, `name`, and `columnEvolutionEnabled`. When `id` or `name` are provided, the request will return only the ID or name of the data source and the subscription status. If `columnEvolutionEnabled` is provided, the response will also include information about the policies, policy conflicts, and workspaces associated with the data sources. | No |
| offset | `integer` Used in combination with `size` to fetch pages. **Default is `0`.** | No |
| size | `integer` The number of results to return per page. **Default is `10`.** | No |
| sortField | `string` Used to sort results by field, which must be `createdAt`, `name`, `blobHandlerType`, `subscriptionStatus`, `id`, `status`, `policy`, or `editable`. | No |
| sortOrder | `string` Sorts results by order, which must be `asc` or `desc`. | No |
| excludedProjects | `array[integer]` Filter out any data sources that belong to the specified projects. | No |
| ephemeral | `boolean` When `true`, returns ephemeral data sources. | No |
| clusterName | `string` The name of the remote cluster the data source is connected to. | No |
| mode | `integer` Specifies the query mode, which must be `0` (`FULL`) or `1` (`COUNT`). | No |
| globalPolicy | `string` Filter by data sources that have this Global Policy applied. | No |
| hostname | `string` Searches data sources by hostname. | No |
| determinePolicyConflicts | `boolean` When `true`, filters results to return the data sources with policy conflicts. | No |
| domainId | `string` Filter by data sources in the domain with this ID. | No |
| domainExclude | `string` When `true`, filters results to return the data sources in the domain of the provided ID. | No |
| domainsToExclude | `array[string]` Use with the `domainExclude` attribute to filter out data sources by the domains they are in. | No |
| disabled | `boolean` If `true`, only data sources that are disabled will be returned. | No |
| port | `string` Filter by data sources associated with a specific port. | No |
| metastoreId | `string` Filter by data sources with the specific metastore ID. | No |
| objectType | `array[string]` Filter by the specifc object type of the data source. Options include: `table`, `view`, `volume`, `function`, and `model`. | No |
### Response
Returns a list of [data source objects](#data-source-object-attributes) for data sources you own or are authorized[^1] to see as `hits` and a `count` of all the data source objects that could be returned.
## `GET` `/dataSource/{dataSourceId}`
Get a data source based on the ID.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/22
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ------------------------------ | -------- |
| dataSourceId | `integer` The data source ID . | **Yes** |
### Response
Returns a [data source object](#data-source-object-attributes).
```json
{
"name": "SnowflakeConnection . snowflake . public . tcp",
"recordFormat": "Not Provided",
"description": null,
"policyHandler": null,
"sqlSchemaName": "public",
"sqlTableName": "tcp",
"blobHandler": {
"url": "https://your-url/snowflake/handler/22",
"ca": {
"name": "Certificate Authority Bundle"
},
"manualDictionary": false
},
"createdBy": 2,
"deleted": false,
"type": "queryable",
"recordCount": 0,
"rowCount": 6,
"statsExpiration": "2021-08-27T16:34:47.846Z",
"id": 22,
"blobHandlerType": "Snowflake",
"policyHandlerType": "Builder",
"subscriptionType": "manual",
"subscriptionPolicy": {
"type": "subscription",
"automaticSubscription": false
},
"globalPolicies": null,
"status": "passed",
"statusInfo": {
"sql": {
"status": "passed",
"message": "Passed"
}
},
"catalogMetadata": null,
"workspace": null,
"seeded": false,
"schemaEvolutionId": null,
"columnEvolutionEnabled": false,
"createdAt": "2025-11-19T23:20:08.297Z",
"updatedAt": "2026-03-17T17:27:40.514Z",
"dataObjectId": 398083,
"legacyName": null,
"dataObjectUniqueId": "4eed11f5-1368-4b75-afda-e7c5634544b4",
"parentIdPath": [
"db86f25d-f4e9-4e86-9862-2ca22f0213f7",
"9c008f0d-69b5-446c-ac2c-bc34e544aef4",
"2c786c68-87a9-4896-8925-93423ddfb5b3"
],
"namePath": [
"snowflake",
"public",
"tcp"
],
"legacyObjectType": "BASE TABLE",
"connectionKey": "SnowflakeConnection",
"subscribedAsUser": true,
"subscriptionContext": null,
"subscriptionId": 15291,
"acknowledgeRequired": false,
"subscriptionStatus": "owner",
"requestedState": "owner",
"approved": true,
"subscriptionExpiration": null,
"filterId": null,
"accessGrant": "READ",
"accessPolicies": null,
"subscribers": 2,
"tags": [
{
"id": 73517,
"name": "Immuta Connections.Snowflake.SnowflakeConnection.snowflake.public",
"displayName": "public",
"source": "connections",
"context": "connections",
"addedBy": 1,
"deleted": false
},
{
"id": 77919,
"name": "Immuta Marketplace Data Object.4eed11f5-1368-4b75-afda-e7c5634544b4",
"displayName": "4eed11f5-1368-4b75-afda-e7c5634544b4",
"source": "marketplace",
"context": "marketplace",
"addedBy": 1,
"deleted": false
}
],
"fingerprintCreatedAt": null,
"remoteDataObject": {
"objectPath": [
"SnowflakeConnection",
"snowflake",
"public",
"tcp"
],
"name": "tcp",
"path": "SnowflakeConnection/snowflake/public/tcp",
"lastCrawled": "2025-12-01T01:49:57.883Z"
}
}
```
## `GET` `/dataSource/name/{dataSourceName}`
Get a data source based on the name.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/name/Public%20Barfoo
```
### Path parameters
| Attribute | Description | Required |
| -------------- | ------------------------------ | -------- |
| dataSourceName | `string` The data source name. | **Yes** |
### Response
Returns a [data source object](#data-source-object-attributes).
## `GET` `/dataSource/sqlTableName/{shortName}`
Get a data source based on the SQL table name.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/sqlTableName/customer_data
```
### Path parameters
| Attribute | Description | Required |
| --------- | ---------------------------------------- | -------- |
| shortName | `string` The data source SQL table name. | **Yes** |
### Response
Returns a [data source object](#data-source-object-attributes).
## `GET` `/dataSource/{dataSourceId}/access`
Get all users with the provided access level for this data source.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/22/access?sortOrder=desc
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ------------------------------ | -------- |
| dataSourceId | `integer` The data source ID . | **Yes** |
### Query parameters
| Attribute | Description | Required |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| states | `Array[string]` The status levels to include when querying for user access. | No |
| approved | `boolean` Denotes whether the returned access objects should be approved. | No |
| searchText | `string` A string used to filter returned users. The query is executed with a wildcard prefix and suffix. | No |
| size | `integer` The number of results to return. | No |
| offset | `integer` The number of results to skip (for paging). | No |
| sortField | `string` The field on which to sort the result set. | No |
| sortOrder | `string` The order in which to sort the results. | No |
| expandGroups | `boolean` If true will return individual members of any group subscribed. | No |
| ignoreSystemGenerated | `boolean` If true, will not return system-generated accounts. | No |
| filterBySchemaEvolution | `boolean` If true, will only return users who have the specified level of access across ALL data sources within the same schema evolution group as this one. | No |
### Response
Returns metadata about users with access to the data source.
| Attribute | Description |
| --------- | ------------------------------------------------------------------------- |
| count | `integer` The number of users with access to the data source. |
| users | `string` The metadata regarding the users with access to the data source. |
```json
{
"count": 2,
"users": [
{
"profile": 2,
"name": "First Last",
"iamid": "bim",
"userid": "first.last@immuta.com",
"email": "first.last@immuta.com",
"type": "user",
"admin": "First Last",
"approved": true,
"state": "owner",
"systemGenerated": false,
"lastExternalRefresh": "2021-10-06T14:58:46.983Z",
"subscriptionId": 586,
"createdAt": "2021-10-05T14:33:01.518Z",
"updatedAt": "2021-10-05T14:33:01.518Z",
"approvals": [
{
"requiredPermission": "OWNER",
"state": "approved",
"approverId": null,
"ownerModelId": null,
"approver": "First Last",
"ownerModelName": null
}
],
"currentUserCanApprove": false
},
{
"profile": 3,
"name": "Tommy Test",
"iamid": "bim",
"userid": "tommy.test@immuta.com",
"email": "tommy.test@immuta.com",
"type": "user",
"admin": "First Last",
"approved": true,
"state": "subscribed",
"systemGenerated": false,
"lastExternalRefresh": "2021-09-07T16:16:29.957Z",
"subscriptionId": 649,
"createdAt": "2021-10-06T14:58:31.366Z",
"updatedAt": "2021-10-06T14:58:31.366Z",
"approvals": [
{
"requiredPermission": "OWNER",
"state": "approved",
"approverId": null,
"ownerModelId": null,
"approver": "First Last",
"ownerModelName": null
}
],
"currentUserCanApprove": false
}
]
}
```
## `GET` `/dataSource/{dataSourceId}/users/{profileId}/policyInfo`
Retrieves the visibilities, masking information, and filters that the passed in user has access to in the specified data source.
**Required Immuta permission**: `FETCH_POLICY_INFO`
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/16/users/2/policyInfo
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ------------------------------------- | -------- |
| dataSourceId | `integer` The data source ID . | **Yes** |
| profileId | `integer` The profile ID of the user. | **Yes** |
### Query parameters
| Attribute | Description | Required |
| --------- | --------------------------------------------------------------------------------------------------------- | -------- |
| projectId | `integer` The project ID. If provided, this project will be used when evaluating the user's visibilities. | No |
### Response
Returns visibility, masking, and filter details for the specified user.
| Attribute | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visibilities | `array` Details of the user's visibilities, including `anyKey`. |
| visibilityRuleApplies | `boolean` If `true`, a visibility rule exists and the user is not excepted from it. |
| masked | `array` Masking information for the data source, including `metadata`, `name`, `type`, and `actionType`. |
| additionalFilters | `array` Policy information for the data source, including `customWhere`, `eventTimeColumn`, `minimization`, `time`, `filterSeconds`, and `isOlderOrNewer`. |
```json
{
"visibilities": [],
"visibilityRuleApplies": false,
"masked": [
{
"type": "Consistent Value",
"metadata": {
"constant": null
},
"name": "WS_SOLD_DATE_SK",
"actionType": "Nullify"
},
{
"type": "Consistent Value",
"metadata": {
"constant": null
},
"name": "WS_BILL_CUSTOMER_SK",
"actionType": "Nullify"
}
],
"additionalFilters": {}
}
```
## `GET` `/dataSource/{dataSourceId}/users/{profileId}/visibilityReport`
Retrieves a summary of total records, total visibilities (the unique values contained in a column protected by a row-level security policy that allow Immuta to determine whether or not a user can see a given row if they possess an attribute that matches the visibility of that row), and visibilities a given user has access to.
**Required**: The global `GOVERNANCE` permission or be the data source owner
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/16/users/2/visibilityReport
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ------------------------------------- | -------- |
| dataSourceId | `integer` The data source ID . | **Yes** |
| profileId | `integer` The profile ID of the user. | **Yes** |
### Query parameters
| Attribute | Description | Required |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| informationOnly | `boolean` If `true`, the query will just return information for the UI and will skip running some queries for ephemeral data sources. | No |
| includeNestedColumns | `boolean` If `true`, the query will return just information for the dictionary page, including the masking policies for nested columns. | No |
### Response
Returns a summary of records, visibilities, masking, and policy details for the specified user.
| Attribute | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| noVisibilities | `boolean` If `true`, the data source has no row-level security or purpose-based restriction policies applied to it. |
| dataSourceVisibilitiesCount | `integer` The total number of possible visibilities the given data source has. |
| userVisibilitiesCount | `integer` The number of visibilities the current user can see for the given data source. |
| masked | `array` Masking information for the data source, including `metadata`, `name`, `type`, and `actionType`. |
| dataSource | `integer` The data source ID. |
| dataSourceName | `string` The data source name. |
| additionalFilters | `array` Policy information for the data source, including `customWhere`, `eventTimeColumn`, `minimization`, `time`, `filterSeconds`, and `isOlderOrNewer`. |
| allowMaskedJoins | `boolean` If `true` the data source allows masked joins. |
| policySet | `array` Details about the policies on the data source. |
```json
[
{
"noVisibilities": true,
"dataSourceVisibilitiesCount": 0,
"userVisibilitiesCount": 0,
"masked": [
{
"type": "Consistent Value",
"metadata": {
"constant": null
},
"name": "WS_SOLD_DATE_SK"
},
{
"type": "Consistent Value",
"metadata": {
"constant": null
},
"name": "WS_BILL_CUSTOMER_SK"
}
],
"dataSource": 16,
"dataSourceName": "Web Sales",
"additionalFilters": {},
"allowMaskedJoins": false,
"policySet": "[{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_BILL_CUSTOMER_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_bill_customer_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"3a2faac13e332cca1829ed773afa298a5455ac5bb54e68c53ae00991575d2a4b\"},{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_SOLD_DATE_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_sold_date_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"2877a1ace4cfa6427370fd39b254ce0ea75dc22cb024a2f857e033c82a987f9a\"}]"
}
]
```
## `GET` `/dataSource/{dataSourceId}/visibilityReport`
Retrieves a summary of total records, total visibilities (the unique values contained in a column protected by a row-level security policy that allow Immuta to determine whether or not a user can see a given row if they possess an attribute that matches the visibility of that row), and visibilities the current user has access to for a specified data source.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/16/visibilityReport
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Response
Returns a summary of records, visibilities, masking, and policy details for the current user.
| Attribute | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| noVisibilities | `boolean` If `true`, the data source has no row-level security or purpose-based restriction policies applied to it. |
| dataSourceVisibilitiesCount | `integer` The total number of possible visibilities the given data source has. |
| userVisibilitiesCount | `integer` The number of visibilities the current user can see for the given data source. |
| denialReason | `string` Reason the user was denied visibility. |
| masked | `array` Masking information for the data source, including `metadata`, `name`, `type`, and `actionType`. |
| dataSource | `integer` The data source ID. |
| dataSourceName | `string` The data source name. |
| additionalFilters | `array` Policy information for the data source, including `customWhere`, `eventTimeColumn`, `minimization`, `time`, `filterSeconds`, and `isOlderOrNewer`. |
| allowMaskedJoins | `boolean` If `true` the data source allows masked joins. |
| policySet | `array` Details about the policies on the data source. |
```json
{
"noVisibilities": true,
"dataSourceVisibilitiesCount": 0,
"userVisibilitiesCount": 0,
"masked": [
{
"type": "Consistent Value",
"metadata": {
"constant": null
},
"name": "WS_SOLD_DATE_SK"
},
{
"type": "Consistent Value",
"metadata": {
"constant": null
},
"name": "WS_BILL_CUSTOMER_SK"
}
],
"dataSource": 16,
"dataSourceName": "Web Sales",
"additionalFilters": {},
"allowMaskedJoins": false,
"policySet": "[{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_BILL_CUSTOMER_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_bill_customer_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"3a2faac13e332cca1829ed773afa298a5455ac5bb54e68c53ae00991575d2a4b\"},{\"type\":\"masking\",\"rules\":[{\"type\":\"masking\",\"config\":{\"fields\":[\"WS_SOLD_DATE_SK\"],\"maskingConfig\":{\"type\":\"Consistent Value\",\"metadata\":{\"constant\":null}}},\"exceptions\":null,\"ruleAppliedForUser\":true}],\"global\":{\"id\":9,\"tag\":\"Confidential\",\"live\":true,\"name\":\"Data Policy\",\"reason\":null,\"staged\":false,\"deleted\":false,\"conflict\":null,\"disabled\":false,\"metadata\":null,\"template\":false,\"createdAt\":\"2022-08-09T17:23:02.634Z\",\"createdBy\":\"jane\",\"policyKey\":\"Data Policy\",\"updatedAt\":\"2022-08-09T17:23:02.634Z\",\"clonedFrom\":null,\"certification\":null,\"createdByName\":\"jane\",\"changedOnApply\":[\"dataTypeMismatch\"],\"parentPolicyId\":null,\"systemGenerated\":false,\"originalPolicyId\":\"masking(^_^)data policy(^_^)ws_sold_date_sk(^_^)consistent value(^_^)(^_^)(^_^)\",\"ownerRestrictions\":null},\"description\":null,\"policyHash\":\"2877a1ace4cfa6427370fd39b254ce0ea75dc22cb024a2f857e033c82a987f9a\"}]"
}
```
## `GET` `/dataSource/{dataSourceId}/contacts`
Gets the profiles for the data source owners and experts.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/23/contacts
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Response
Returns owner and expert profiles for the specified data source.
| Attribute | Description |
| --------- | ---------------------------------------------------------------------- |
| id | `integer` The data source ID. |
| state | `string` The user's data source role, such as `owner` or `subscribed`. |
| name | `string` The user's name. |
| email | `string` The user's email. |
| profile | `integer` The user's profile ID. |
```json
{
"type": "profile",
"id": 23,
"state": "owner",
"name": "first last",
"email": "first.last@immuta.com",
"profile": 2
},
{
"type": "profile",
"id": 23,
"state": "owner",
"name": "Tommy Test",
"email": "tommy.test@immuta.com",
"profile": 3
}
```
## `GET` `/dataSource/byPurposes`
Get data sources that match a set of purposes.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/byPurposes?purposes=Data+Analysis
```
### Query parameters
| Attribute | Description | Required |
| ---------------- | ----------------------------------------------------------------------------- | -------- |
| purposes | `array[string]` The purposes to filter the data sources by. | **Yes** |
| excludedProjects | `array[integer]` Excludes data sources associated with specified project IDs. | No |
### Response
Returns data sources that match the requested purposes.
| Attribute | Description |
| ------------ | ------------------------------------------------------------------------ |
| id | `integer` The data source ID. |
| name | `array` The name of the data source. |
| policyId | `integer` The policy ID. |
| restrictions | `array` Details regarding the `operator` (`and` or `or`) and `purposes`. |
```json
[{
"id": 42,
"name": "Army Records",
"policyId": 56,
"restrictions": [{
"operator": "and",
"purposes": ["Data Analysis"]
}]
}]
```
## `GET` `/dataSource/rpc/mine`
Retrieves all the data sources the current user has access to.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/rpc/mine
```
### Response
Returns data sources the current user can access.
| Attribute | Description |
| --------------- | -------------------------------------------------- |
| id | `integer` The data source ID. |
| name | `string` The data source name. |
| type | `string` The type of data source: `queryable`. |
| sqlTableName | `string` The name of the table in Immuta. |
| sqlSchemaName | `string` The name of the schema in Immuta. |
| blobHandlerType | `string` The type of handler, such as `Snowflake`. |
| sparkUseJDBC | `boolean` When `true`, uses a JDBC driver. |
```json
{
"id": 23,
"name": "Public Record",
"type": "queryable",
"sqlTableName": "record",
"sqlSchemaName": "public",
"blobHandlerType": "Snowflake",
"sparkUseJDBC": true
}
```
## `GET` `/dataSource/{dataSourceId}/activities`
Get all of the recent policy activities for a given data source.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/23/activities
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Query parameters
| Attribute | Description | Required |
| --------- | ----------------------------------------------------- | -------- |
| offset | `integer` The number of results to skip (for paging). | No |
| size | `integer` The number of results to return per page. | No |
### Response
Returns recent policy activity for the specified data source.
| Attribute | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count | `integer` The number of results. |
| activities | `array` Includes details about the policy and the data source, including the policy and data source type, when the activity notification was triggered, and whether or not the policy change was triggered by a Global policy. |
| actionBy | `array` Details about who triggered the action. |
| targetUser | `array` Information about the user who received the notification. |
```json
{
"count": 3,
"activities": [{
"modelType": "datasource",
"modelId": "23",
"createdAt": "2021-09-07T16:13:25.197Z",
"notificationType": "policyUpdated",
"metadata": {
"dataSourceName": "Public Foobar",
"triggeredByGlobal": false,
"conflictCount": 0,
"policyType": "data",
"handlerId": 3,
"previousHandlerId": 2,
"dataSourceType": "queryable"
},
"read": false,
"id": 256,
"updatedAt": "2021-09-07T16:13:25.197Z",
"actionBy": {
"id": 2,
"name": "first last",
"email": "first.last@immuta.com"
},
"targetUser": {
"id": 2,
"name": "first last",
"email": "first.last@immuta.com"
}
}]
}
```
## `GET` `/dataSource/{dataSourceId}/tags`
Get the tags for a data source.
**Required**: The data source must be publicly visible, you must own the data source, or you must have access to see the data source through the `GOVERNANCE` permission or a subscription policy
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/4/tags
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Query parameters
| Attribute | Description | Required |
| ------------ | --------------------------------------------------------------------------------- | -------- |
| blobId | `string` Returns the tags for the specified blob. | No |
| blobTagsOnly | `boolean` When `true`, will only display blob tags associated with a data source. | No |
### Response
Returns tags for the specified data source.
| Attribute | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------ |
| tags | `array` Includes details about the tags, such as the `name`, `source`, and the profile ID of the user who added the tag. |
```json
{
"tags": [
{
"name": "Discovered.Entity.Medicare Number",
"source": "curated",
"modelType": "datasource",
"modelId": "4",
"addedBy": 1,
"deleted": false
}
]
}
```
## Data source object attributes
| Attribute | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | `string` The data source name. |
| recordFormat | `string` The data format of blobs in the data source, such as `json`, `xml`, `html`, or `jpeg`. |
| description | `string` The description of the data source. |
| policyHandler | `object` The policy handler details and policies enforced on the data source. |
| sqlSchemaName | `string` A string that represents this data source's schema name in Immuta. |
| sqlTableName | `string` The SQL table name in Immuta. |
| blobHandler | `object` Blob handler configuration for the data source (for example, `url`, optional `ca`, and `manualDictionary`). |
| blobHandlerType | `string` Describes the type of underlying blob handler that will be used with this data source (e.g., `MS SQL`). |
| createdBy | `integer` The ID of the profile creating the data source. |
| deleted | `boolean` If true, the data source was deleted. |
| type | `string` The data source type: `queryable`. |
| rowCount | `integer` The number of rows. |
| id | `integer` The data source ID. |
| statsExpiration | `timestamp` The time when the data source statistics (e.g., `rowCount`) expire and will need to be re-run. |
| policyHandlerType | `string` The type of policy handler applied to the data source: `Builder`. |
| subscriptionType | `string` The type of subscription policy on the data source. The type can be `policy` (which only allows users with specific groups or attributes to subscribe) or `manual` (which requires users to be manually added). |
| subscriptionPolicy | `object` Details about the subscription policy applied to the data source. |
| globalPolicies | `string` Details about the global policies applied to the data source. |
| status | `string` The data source health status. |
| statusInfo | `object` Details about the status of all the jobs and health checks that ran on the data source. |
| catalogMetadata | `object` Details about the connected external catalog. |
| workspace | `integer` The ID of the workspace the data is in. |
| seeded | `boolean` If `true`, the data source was system-generated. |
| schemaEvolutionId | `string` The ID for the schema project the data source is in. |
| columnEvolutionEnabled | `boolean` If `true`, the data source has schema monitoring and column detection on. |
| createdAt | `timestamp` The time the data source was created. |
| updatedAt | `timestamp` The time the data source was last updated. |
| dataObjectId | `integer` The ID of the data object associated with the data source. |
| legacyName | `string` The name of the data source before it was upgraded to connections. |
| dataObjectUniqueId | `string` The UUID for the data object associated with the data source. |
| parentIdPath | `array` The list of UUIDs for the parent data objects (e.g., database, schema, etc.) that contain this data source. |
| namePath | `array` The list of names for the parent data objects (e.g., database, schema, etc.) that contain this data source. |
| legacyObjectType | `string` The type of data object. Options include: `BASE TABLE`, `ICEBERG TABLE`, `VIEW`, `MATERIALIZED VIEW`, `MANAGED`, `STREAMING_TABLE`, `MATERIALIZED_VIEW`, `VOLUME_MANAGED`, `VOLUME_EXTERNAL`, `GOVERNED`, and `EXTERNAL_TABLE`. |
| connectionKey | `string` The connection key (or display name) for the connection the data source comes from. |
| subscribedAsUser | `boolean` If `true`, the user who made the API request is subscribed to the data source. |
| subscriptionContext | `string` Description of why the user does or does not have access to the data source. Optional and may not be available. |
| subscriptionId | `integer` An ID of the record associated with the subscription of the user who made the API request to the data source. |
| acknowledgeRequired | `boolean` If `true`, users must acknowledge the policy before they can subscribe to the data source. |
| subscriptionStatus | `string` The subscription status to the data source of the user who made the API request. Accepted statuses are `owner`, `subscribed`, or `unsubscribed`. |
| requestedState | `string` The subscription state of the user making the API request if they manually requested access to the data source in the Govern app. |
| approved | `boolean` If `true`, the user's requested subscription status was approved. |
| subscriptionExpiration | `timestamp` The time that the user who made the API request subscription to the data source will expire. |
| filterId | `string` The ID of the search filter applied to this data source, if available. |
| accessGrant | `string` The type of access granted to the user making the API request. Options include: `READ` and `WRITE`. |
| accessPolicies | `object` Details about the access policies applied to the data source. |
| subscribers | `integer` The number of Immuta users subscribed to the data source. |
| tags | `object` Details about the tags applied to this data source. |
| fingerprintCreatedAt | `timestamp` The last time the data source fingerprint was generated, if available. |
| remoteDataObject | `object` Details about the remote data object including the name and path. |
[^1]: It's possible for you to be authorized to see data sources you are not subscribed to, as long as you meet the conditions in the policy on the data source and it is publicly visible. For example, if a policy allows anyone to manually subscribe to the data source but you have not manually subscribed to it yet, then you are authorized to see the data source and it will appear in the response.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/data-sources/get-data-sources.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.