Reverse lookup

Required capabilities: annotationsAcl:WRITE

Provided an annotation filter and an annotated resource type (file/3D), returns ids of annotated resources having annotations matching the filter. A typical use case is looking up files with annotations linking to a specific asset. Only ids of annotated resources that the client has access to will be returned.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

POST

annotations

reverselookup

JavaScript SDK

const assetQueryData = {
  limit: -1,
  filter: {
    annotatedResourceType: 'file' as const,
    annotationType: 'images.AssetLink',
    data: {
      assetRef: { id: 123 }
    }
  }
};
const resourceIdsResponse = client.annotations.reverseLookup(assetQueryData);

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "annotatedResourceType": "file",
    "status": "approved",
    "data": {
      "label": "cat",
      "fileRef": {
        "externalId": "abc"
      }
    }
  },
  "limit": 100,
  "cursor": "MzE1NjAwMDcxNzQ0ODI5"
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup"

payload = {
    "filter": {
        "annotatedResourceType": "file",
        "status": "approved",
        "data": {
            "label": "cat",
            "fileRef": { "externalId": "abc" }
        }
    },
    "limit": 100,
    "cursor": "MzE1NjAwMDcxNzQ0ODI5"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup",
  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([
    'filter' => [
        'annotatedResourceType' => 'file',
        'status' => 'approved',
        'data' => [
                'label' => 'cat',
                'fileRef' => [
                                'externalId' => 'abc'
                ]
        ]
    ],
    'limit' => 100,
    'cursor' => 'MzE1NjAwMDcxNzQ0ODI5'
  ]),
  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}/annotations/reverselookup"

	payload := strings.NewReader("{\n  \"filter\": {\n    \"annotatedResourceType\": \"file\",\n    \"status\": \"approved\",\n    \"data\": {\n      \"label\": \"cat\",\n      \"fileRef\": {\n        \"externalId\": \"abc\"\n      }\n    }\n  },\n  \"limit\": 100,\n  \"cursor\": \"MzE1NjAwMDcxNzQ0ODI5\"\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}/annotations/reverselookup")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": {\n    \"annotatedResourceType\": \"file\",\n    \"status\": \"approved\",\n    \"data\": {\n      \"label\": \"cat\",\n      \"fileRef\": {\n        \"externalId\": \"abc\"\n      }\n    }\n  },\n  \"limit\": 100,\n  \"cursor\": \"MzE1NjAwMDcxNzQ0ODI5\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup")

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  \"filter\": {\n    \"annotatedResourceType\": \"file\",\n    \"status\": \"approved\",\n    \"data\": {\n      \"label\": \"cat\",\n      \"fileRef\": {\n        \"externalId\": \"abc\"\n      }\n    }\n  },\n  \"limit\": 100,\n  \"cursor\": \"MzE1NjAwMDcxNzQ0ODI5\"\n}"

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

{
  "items": [
    {
      "id": 123,
      "externalId": "abc-1066"
    }
  ],
  "annotatedResourceType": "file",
  "nextCursor": null
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ]
  }
}

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

A request to look up annotated resource ids based on having annotations matching a filter.

filter

object

required

A filter for reverse lookups

Show child attributes

Example:

{
  "annotatedResourceType": "file",
  "status": "approved",
  "data": {
    "label": "cat",
    "fileRef": { "externalId": "abc" }
  }
}

limit

integer

default:100

Required range: 1 <= x <= 1000

cursor

string | null

A cursor pointing to another page of results

Required string length: 1 - 255

Example:

"MzE1NjAwMDcxNzQ0ODI5"

Response

Successful reverse lookup of annotated resource ids

items

object[]

required

Show child attributes

annotatedResourceType

enum<string>

required

The annotated CDF resource type. Files as well as 3d-Models are supported.

Available options:

file,

threedmodel

Example:

"file"

nextCursor

string | null

A cursor pointing to another page of results

Required string length: 1 - 255

Example:

null

Last modified on October 7, 2026

⌘I

JavaScript SDK

const assetQueryData = {
  limit: -1,
  filter: {
    annotatedResourceType: 'file' as const,
    annotationType: 'images.AssetLink',
    data: {
      assetRef: { id: 123 }
    }
  }
};
const resourceIdsResponse = client.annotations.reverseLookup(assetQueryData);

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "annotatedResourceType": "file",
    "status": "approved",
    "data": {
      "label": "cat",
      "fileRef": {
        "externalId": "abc"
      }
    }
  },
  "limit": 100,
  "cursor": "MzE1NjAwMDcxNzQ0ODI5"
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup"

payload = {
    "filter": {
        "annotatedResourceType": "file",
        "status": "approved",
        "data": {
            "label": "cat",
            "fileRef": { "externalId": "abc" }
        }
    },
    "limit": 100,
    "cursor": "MzE1NjAwMDcxNzQ0ODI5"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup",
  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([
    'filter' => [
        'annotatedResourceType' => 'file',
        'status' => 'approved',
        'data' => [
                'label' => 'cat',
                'fileRef' => [
                                'externalId' => 'abc'
                ]
        ]
    ],
    'limit' => 100,
    'cursor' => 'MzE1NjAwMDcxNzQ0ODI5'
  ]),
  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}/annotations/reverselookup"

	payload := strings.NewReader("{\n  \"filter\": {\n    \"annotatedResourceType\": \"file\",\n    \"status\": \"approved\",\n    \"data\": {\n      \"label\": \"cat\",\n      \"fileRef\": {\n        \"externalId\": \"abc\"\n      }\n    }\n  },\n  \"limit\": 100,\n  \"cursor\": \"MzE1NjAwMDcxNzQ0ODI5\"\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}/annotations/reverselookup")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": {\n    \"annotatedResourceType\": \"file\",\n    \"status\": \"approved\",\n    \"data\": {\n      \"label\": \"cat\",\n      \"fileRef\": {\n        \"externalId\": \"abc\"\n      }\n    }\n  },\n  \"limit\": 100,\n  \"cursor\": \"MzE1NjAwMDcxNzQ0ODI5\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/annotations/reverselookup")

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  \"filter\": {\n    \"annotatedResourceType\": \"file\",\n    \"status\": \"approved\",\n    \"data\": {\n      \"label\": \"cat\",\n      \"fileRef\": {\n        \"externalId\": \"abc\"\n      }\n    }\n  },\n  \"limit\": 100,\n  \"cursor\": \"MzE1NjAwMDcxNzQ0ODI5\"\n}"

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

{
  "items": [
    {
      "id": 123,
      "externalId": "abc-1066"
    }
  ],
  "annotatedResourceType": "file",
  "nextCursor": null
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ]
  }
}