Guides
API Reference

Data Source Instances

A data source may have more than one instance associated with it. If the data source is a dynamic data source, it will have more than one instance associated with it. Other data sources have one instance, and the ID in this case is the same as the data source ID.

GET /datasource-instances

DescriptionGet a list of all the datasource-instances to which the user has access. Note that the "id" returned is the id of the data source instance - use this id to query for a specific instance. The id of the related data source is "datasource_id".
Permissionsdashboard.library
Resource URLhttps://app.klipfolio.com/api/1.0/datasource-instances
Parametersclient_id={client_id} - show only instances belonging to the specified client.
datasource_id={datasource_id} - show only instances of the specified data source. Use the data source id here, not the id of the instance.
Response codes401 — Access to this datasource-instance is denied
404 — Data source instance not found

Example Request

GET https://app.klipfolio.com/api/1/datasource-instances?client_id=0123456789abcdef0123cdef

Example Response

{
  "meta": {
    "success": true,
    "status": 200,
    "count": 4,
    "total": 4
  "data": {
    "datasources": [
      {
        "id": "4928fb1d95bfb4e02012de483c1234a5",
        "datasource_id": "4928fb1d95bfb4e02012de483c1234a5",
        "datasource_name": "Fake data used in Klip samples. Originates from the Gallery.",
        "refresh_fail_count": 0 
        "data_size": 32564,
        "date_last_refresh": "2016-06-20T11:56:08Z"  
      }]
    }
}

GET /datasource-instances/{id}

DescriptionGet the details for a specific data source instance id. Note that the "id" returned is the id of the data source instance. The id of the related data source is "datasource_id".
Note: dates are returned in UTC time.
Permissionsdashboard.library
Resource URLhttps://app.klipfolio.com/api/1.0/datasource-instances/{id}
Parametersid={datasource instance id}

Example Request

GET https://app.klipfolio.com/api/1/datasource-instances/0123456789abcdef0123456789abcdef

Example Response

{
"data": {
    "id":"0123456789abcdef0123456789abcdef"
    "datasource_id":"0123456789abcdef0123456789abcdef",
    "datasource_name":"Sample data",
    "date_last_refresh":"2014-11-18T19:34:36Z",
    "date_next_refresh":"2014-11-18T20:34:36Z",
    "refresh_fail_count":0,
    "data_size":14050
},
"meta": {
   "status": 200,
   "success": true
}
}

POST /datasource-instances

DescriptionCreate a new data source instance based on a data source (specified as “datasource_id” in the post data). Data source instance properties can optionally be specified in the post data.
Permissionsdatasource.create
Resource URLhttps://app.klipfolio.com/api/1.0/datasource-instances
Parametersno_refresh
Note: The no_refresh parameter creates a data source with no instance, then creates an instance that doesn't refresh and then push data to it.

Example Request

POST https://app.klipfolio.com/api/1/datasource-instances -d {'datasource_id': '2342d101cee439562b794b07e9ebe9e2', 'properties': {'example': 'test', ...}}

Example Response

{
"meta": {
   "status": 200,
   "success": true

}
}

DELETE /datasource-instances

DescriptionDelete instances related to a specific data source.
Permissionsdatasource.delete
Resource URLhttps://app.klipfolio.com/api/1.0/datasource-instances/{id}
Parameters

Example Request

DELETE https://app.klipfolio.com/api/1/datasource-instances/2342d101cee439562b794b07e9ebe9e2

Example Response

{
"meta": {
   "status": 200,
   "success": true
}
}