Retrieve external data sources by external ids

Required capabilities: transformationsExternalDataSourcesAcl:READ

Retrieve external data sources by their externalId.

The response items are in the same order as the requested external IDs. All externalId values must be unique within the request.

If an externalId doesn’t match an external data source, or the data source isn’t accessible to the caller, the request fails with a 400 listing the missing IDs, unless ignoreUnknownIds is true. In that case unknown IDs are omitted from the response.

POST

transformations

externaldata

byids

Retrieve external data sources by external ids

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "externalId": "my.known.id"
    }
  ],
  "ignoreUnknownIds": false
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids"

payload = {
    "items": [{ "externalId": "my.known.id" }],
    "ignoreUnknownIds": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({items: [{externalId: 'my.known.id'}], ignoreUnknownIds: false})
};

fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'externalId' => 'my.known.id'
        ]
    ],
    'ignoreUnknownIds' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ],\n  \"ignoreUnknownIds\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ],\n  \"ignoreUnknownIds\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ],\n  \"ignoreUnknownIds\": false\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "externalId": "my.known.id",
      "format": "one_lake",
      "settings": {
        "credentials": {
          "clientId": "<string>",
          "tenantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "locationDescription": {
          "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "containerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "name": "<string>",
      "dataSetId": 4503599627370496
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "`null` values aren't allowed."
  }
}

{
  "error": {
    "code": 403,
    "message": "This endpoint is not enabled for project: my-project"
  }
}

Authorizations

Authorization

string

header

required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Body

application/json

items

object[]

required

External data sources to retrieve. All externalId values must be unique within the request.

Required array length: 1 - 100 elements

Show child attributes

ignoreUnknownIds

boolean

default:false

Ignore external IDs that are not found, or not accessible to the caller, instead of failing the request.

Response

Response with the requested external data sources.

Array of objects (External Data Source).

items

object[]

required

An external data source.

Option 1
Option 2

Show child attributes

⌘I

Retrieve external data sources by external ids

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "externalId": "my.known.id"
    }
  ],
  "ignoreUnknownIds": false
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids"

payload = {
    "items": [{ "externalId": "my.known.id" }],
    "ignoreUnknownIds": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({items: [{externalId: 'my.known.id'}], ignoreUnknownIds: false})
};

fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'externalId' => 'my.known.id'
        ]
    ],
    'ignoreUnknownIds' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ],\n  \"ignoreUnknownIds\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ],\n  \"ignoreUnknownIds\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/transformations/externaldata/byids")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ],\n  \"ignoreUnknownIds\": false\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "externalId": "my.known.id",
      "format": "one_lake",
      "settings": {
        "credentials": {
          "clientId": "<string>",
          "tenantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "locationDescription": {
          "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "containerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "name": "<string>",
      "dataSetId": 4503599627370496
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "`null` values aren't allowed."
  }
}

{
  "error": {
    "code": 403,
    "message": "This endpoint is not enabled for project: my-project"
  }
}