> ## Documentation Index
> Fetch the complete documentation index at: https://docs.communityhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /data-source/instance — List Data Source Instances
> List the configured data source instances of a single type, filtered by organization, status, and error type.
Like [Type Listing](/api-reference/query/data-source-type-list) and [Monitored Entity List](/api-reference/query/monitored-entity-list), this is a `POST` request with a JSON body rather than a `GET` with query parameters.
A data source **type** is the integration (AirNow, CSV, OneDrive, and so on); an **instance** is a specific configured connection of that type. This endpoint lists instances **one type at a time**: the required `type` field selects the type, the top-level `image` and `name` describe it, and every object in `data` shares that same `type` value.
The example response below is a **composite** — it shows one instance of several types so every field and `type` value is documented in one place. A real response is homogeneous (every item is the requested type), and `pagination.total_records` reflects that single type's count.
## Endpoint
```text theme={null}
POST /data-source/instance
```
## Request body
| Field | Type | Required | Description |
| --------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Yes | The data source type key to list instances for (for example `usgs`, `airnow`, `csv`, `buildingos`) — see the `type` values under [Type Listing](/api-reference/query/data-source-type-list). Scopes the response to a single type. |
| `organizations` | array of string | No | Organization ids to filter by — see [Organizations](/api-reference/query/organizations) and [Instance Filters](/api-reference/query/data-source-instance-filters). Omit to include every organization the token can access. |
| `errorType` | array of string | No | Error-type filter — any of `fileError`, `dataError`, `connectionError` (the `errorType` facet on [Instance Filters](/api-reference/query/data-source-instance-filters)). |
| `status` | array of string | No | Status filter — `enabled` and/or `disabled` (the `status` facet on [Instance Filters](/api-reference/query/data-source-instance-filters)). |
## Query parameters
| Parameter | Description |
| ---------- | ------------------------------------------------------------------------------------------- |
| `page` | Page number to retrieve (1-indexed). |
| `per_page` | Number of results per page — the same pagination controls used by the other list endpoints. |
## Example request
The only required field is `type`, so the smallest valid body is `{ "type": "usgs" }`. A fully-filtered request:
```bash theme={null}
curl -X POST "https://api.communityhub.cloud/dh/public/v1/data-source/instance?page=1&per_page=25" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"type": "usgs",
"organizations": ["0c8a44f7"],
"errorType": ["dataError", "connectionError"],
"status": ["enabled", "disabled"]
}'
```
## Response shape
The response is an object describing the single type (`image`, `name`), its instances (`data`), and `pagination`:
```json theme={null}
{
"image": "https://communityhubstorage.cloud/ch-data-hub/integrations/usgs.png",
"name": "USGS",
"data": [
{
"id": 115,
"name": "Cleveland-Akron-Lorain",
"type": "airnow",
"orgId": 2,
"metadata": {
"description": "This is a test description",
"deliveryInterval": 10,
"incomingResolution": 10
},
"isEnabled": false,
"localTimezone": "America/New_York",
"dataReception": "offline",
"lastRecordedTime": "2026-06-16T10:00:00",
"variablesCount": "3",
"dataReceivingType": "pull",
"sourcesWithDataErrors": 0,
"disconnectedSources": 0,
"dataErrors": 0,
"connectivityLast24Hours": 0,
"lastReceivedData": 0
},
{
"id": 3518,
"name": "CSV New",
"type": "csv",
"orgId": 11,
"metadata": {
"logging": false,
"batchSize": 2,
"dateFormat": "ISO",
"description": "Description",
"deliveryInterval": 5,
"incomingResolution": 5,
"skipSourceDataEntry": false,
"lastReceivedLocalTimestamp": "2025-01-28T03:21:00-08:00"
},
"isEnabled": false,
"localTimezone": "America/Los_Angeles",
"dataReception": "offline",
"lastRecordedTime": "2026-04-04T12:27:08",
"variablesCount": "43",
"dataReceivingType": "push",
"sourcesWithDataErrors": 0,
"disconnectedSources": 0,
"dataErrors": 0,
"connectivityLast24Hours": 0,
"lastReceivedData": 0
},
{
"id": 3510,
"name": "Derived Variables",
"type": "derived",
"orgId": 11,
"metadata": {},
"isEnabled": false,
"localTimezone": "America/Los_Angeles",
"dataReception": "offline",
"lastRecordedTime": null,
"variablesCount": "0",
"dataReceivingType": "derived",
"sourcesWithDataErrors": 0,
"disconnectedSources": 0,
"dataErrors": 0,
"connectivityLast24Hours": 0,
"lastReceivedData": 0
},
{
"id": 3706,
"name": "Birmingham Temperature",
"type": "open-weather-map",
"orgId": 2,
"metadata": {
"description": "test1",
"deliveryInterval": 1,
"incomingResolution": 5
},
"isEnabled": true,
"localTimezone": "America/New_York",
"dataReception": "online",
"lastRecordedTime": "2026-07-30T06:27:00",
"variablesCount": "3",
"dataReceivingType": "pull",
"sourcesWithDataErrors": 0,
"disconnectedSources": 0,
"dataErrors": 0,
"connectivityLast24Hours": 0,
"lastReceivedData": 0
}
],
"pagination": {
"total_records": 4,
"total_perpage": 25,
"total_page": 1,
"current_page": 1,
"next_page": null,
"previous_page": null
}
}
```
### Top-level object
| Field | Type | Description |
| ------------ | ------ | --------------------------------------------------------------------- |
| `image` | string | Icon/logo URL for the single data source type being listed. |
| `name` | string | Display name of that type. |
| `data` | array | The instances of that type — see [Instance object](#instance-object). |
| `pagination` | object | Pagination metadata — see [Pagination object](#pagination-object). |
### Instance object
| Field | Type | Description |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | integer | Unique instance id. |
| `name` | string | Instance display name. |
| `type` | string | The data source type key (for example `airnow`, `onedrive-csv`, `atrius-csv`, `buildingos`, `jace`, `obvius`, `derived`, `open-weather-map`, `usgs`). Every item in one response shares this value. |
| `orgId` | integer | Id of the organization the instance belongs to. Returned as a number here, unlike the 8-character organization-id placeholders used in examples on the filter-discovery pages. |
| `metadata` | object | Type-specific configuration. Commonly `description`, `deliveryInterval`, `incomingResolution`; some types add more (for example CSV adds `logging`, `batchSize`, `dateFormat`, `skipSourceDataEntry`, `lastReceivedLocalTimestamp`). May be an empty object. |
| `isEnabled` | boolean | Whether the instance is enabled. |
| `localTimezone` | string | IANA timezone name (for example `America/New_York`). |
| `dataReception` | string | `online` or `offline`. |
| `lastRecordedTime` | string \| null | Local ISO-8601 timestamp of the last recorded data point, or `null`. |
| `variablesCount` | string | Number of variables on the instance — returned as a **string** (for example `"3"`), not an integer. |
| `dataReceivingType` | string | How data is ingested: `pull`, `push`, or `derived`. |
| `sourcesWithDataErrors` | integer | Count of this instance's sources currently reporting data errors. |
| `disconnectedSources` | integer | Count of this instance's currently disconnected sources. |
| `dataErrors` | integer | Count of current data errors. |
| `connectivityLast24Hours` | integer | Connectivity metric over the last 24 hours. |
| `lastReceivedData` | integer | `0` in every provided example; meaning and units are not documented in the source. |
### Pagination object
| Field | Type | Description |
| --------------- | --------------- | ------------------------------------------------------------------- |
| `total_records` | integer | Total number of instances (of the requested type) across all pages. |
| `total_perpage` | integer | Page size in effect. |
| `total_page` | integer | Total number of pages. |
| `current_page` | integer | Current page number (1-indexed). |
| `next_page` | integer \| null | Next page number, or `null` on the last page. |
| `previous_page` | integer \| null | Previous page number, or `null` on the first page. |
See [Instance Filters](/api-reference/query/data-source-instance-filters) to discover valid organization, status, and error-type filter values, and [Type Listing](/api-reference/query/data-source-type-list) for the type-level listing.