List Annotations | Clarifai Docs

GPU Shortage?

Make the most out of your GPUs with Compute Orchestration. Learn More

On this page

You can get a list of annotations within your app with a GET call. Annotations will be returned from oldest to newest.

These requests are paginated. By default each page will return 20 annotations.

List All User Created Annotations in Your App

Below is an example of how to list all your user labelled annotations.

note
This will not show annotations by models in your workflow. To include model created annotations, you need to set list_all_annotations to True.

##################################################################
# In this section, we set the user authentication and app ID.
# Change these strings to run your own example.
##################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
    service_pb2.ListAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        per_page=10
    ),
    metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
    print(list_annotations_response.status)
    raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
    print(annotation_object)

List All Annotations in Your App

Below is an example of how to list all annotations, including those created by models.

channel = ClarifaiChannel.get_grpc_channel() stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations( service_pb2.ListAnnotationsRequest( user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT per_page=10, list_all_annotations=True ), metadata=metadata )

for annotation_object in list_annotations_response.annotations: print(annotation_object)


### List User Created Annotations by Input IDs
Below is an example of how to list all user created annotations for certain input (one or several) by providing a list of input IDs.

> **note**  
> This will not show annotations by models in your workflow. To include model created annotations, you need to set `list_all_annotations` to `True`.

```python
#########################################################################
# In this section, we set the user authentication, app ID, and input IDs
# Change these strings to run your own example.
#########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to list your own annotations
INPUT_ID_1 = '53d0362a9dfa4e03b2293375e2d0db73'
INPUT_ID_2 = '00f6d742124147ac8ca7788f73736fb9'

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
    service_pb2.ListAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        input_ids=[INPUT_ID_1, INPUT_ID_2],
        per_page=10
    ),
    metadata=metadata
)

for annotation_object in list_annotations_response.annotations:
    print(annotation_object)

List Annotations by User IDs

An annotation is created by either a user or a model. You can list annotations created by specific user(s) by providing their user IDs.

Below is an example of how to do that.

#########################################################################
# In this section, we set the user authentication, app ID, and user IDs.
# Change these strings to run your own example.
#########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Insert the user IDs
USER_ID_1 = 'USER_ID_1_HERE'
USER_ID_2 = 'USER_ID_2_HERE'

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
    service_pb2.ListAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        user_ids=[USER_ID_1, USER_ID_2],
        per_page=10
    ),
    metadata=metadata
)

for annotation_object in list_annotations_response.annotations:
    print(annotation_object)

List Annotations by Model Version IDs

An annotation is created by either a user or a model. For example, if your workflow has a detection model, when you add an input, the model will detect objects in your input. You can see these detected objects by listing the annotations created in the detection model.

Below is an example of how to list annotations by model version IDs.

##################################################################################
# In this section, we set the user authentication, app ID, and model version IDs.
# Change these strings to run your own example.
##################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Insert the model version IDs
MODEL_VERSION_ID_1 = 'MODEL_VERSION_ID_1_HERE'
MODEL_VERSION_ID_2 = 'MODEL_VERSION_ID_2_HERE'

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
    service_pb2.ListAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        model_version_ids=[MODEL_VERSION_ID_1, MODEL_VERSION_ID_2],
        per_page=10
    ),
    metadata=metadata
)

for annotation_object in list_annotations_response.annotations:
    print(annotation_object)

List Annotations by Input IDs and Annotation IDs

You can list annotations by input IDs and their corresponding annotation IDs. Number of input IDs and annotation IDs should be the same. Since we are finding annotation by IDs, this will match any user or model created annotations.

Below is an example of how to do that.

##########################################################################
# In this section, we set the user authentication, app ID, input IDs, and
# annotation IDs. Change these strings to run your own example.
##########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to list your own annotations
INPUT_ID_1 = '53d0362a9dfa4e03b2293375e2d0db73'
INPUT_ID_2 = '00f6d742124147ac8ca7788f73736fb9'
ANNOTATION_ID_1 = '300b8e39a65e4f33ae4e15e86eaf4a3b'
ANNOTATION_ID_2 = 'fcd19d4ad96440e7b1fbda7279c19e44'

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
    service_pb2.ListAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        input_ids=[INPUT_ID_1, INPUT_ID_2],
        ids=[ANNOTATION_ID_1, ANNOTATION_ID_2],
        per_page=10
    ),
    metadata=metadata
)

for annotation_object in list_annotations_response.annotations:
    print(annotation_object)

List Annotations by Model Version IDs

An annotation is created by either a user or a model. You can see these detected objects by listing the annotations created in the detection model.

List Annotations by Input IDs and Annotation IDs

You can list annotations by input IDs and their corresponding annotation IDs. Number of input IDs and annotation IDs should be the same.

curl -X GET 'https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations?page=1&per_page=10&input_ids=YOUR_INPUT_ID_1_HERE&input_ids=YOUR_INPUT_ID_2_HERE&ids=YOUR_ANNOTATION_ID_1_HERE&ids=YOUR_ANNOTATION_ID_2_HERE' \ 
-H 'Authorization: Key YOUR_PAT_HERE'

Build your next AI app, test and tune popular LLMs models, and much more.