Pagination | Clarifai Docs

Learn how to paginate your GET or POST requests

Many of our API endpoints support pagination, a crucial feature when handling large outputs. It helps manage and display results efficiently by breaking them into smaller, manageable batches.

You can provide page and per_page params to the API request, and your results will be split into pages.

Creating a pagination request may vary depending on whether you're working with a GET or a POST endpoint.

GET Endpoints

For GET requests, the pagination parameters are included in the query string of the URL.

from clarifai.client.user import User

# Create the input object
input_obj = User(user_id="user_id").app(app_id="test_app", pat="YOUR_PAT").inputs()
# list the inputs with pagination
all_inputs = list(input_obj.list_inputs(page_no=1,per_page=3))
print(all_inputs)

import { Input, Search, User } from "clarifai-nodejs";

const appId = "test_app"; // Placeholder for application ID

// Initialize a User object with your credentials
const client = new User({
  userId: process.env.CLARIFAI_USER_ID,
  pat: process.env.CLARIFAI_PAT,
  appId,
});

// Create an application with the specified app ID and base workflow
await client.createApp({ appId, baseWorkflow: "Universal" });

// URLs of images to be uploaded
const urls = [
  "https://images.pexels.com/photos/139257/pexels-photo-139257.jpeg",
  "https://images.pexels.com/photos/1879386/pexels-photo-1879386.jpeg",
  "https://images.pexels.com/photos/1071882/pexels-photo-1071882.jpeg",
];

// Initialize an Input object to manage input data
const input = new Input({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
});

// Upload each image from the provided URLs
for (let i = 0; i < urls.length; i++) {
  await input.uploadFromUrl({ inputId: `input${i}`, imageUrl: urls[i] });
}

// Initialize a search object for the created application, top-K not set for pagination
const search = new Search({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
  metric: "euclidean",
});

const response = search.query({
  ranks: [{ textRaw: "Red pineapples on the beach." }],
  perPage: 2,
  page: 1,
});

const hits = (await response.next()).value?.hitsList ?? [];
console.log(hits);

################################################################
# 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) # The userDataObject is required when using a PAT

list_inputs_response = stub.ListInputs(
    service_pb2.ListInputsRequest(
        user_app_id=userDataObject,
        page=2,
        per_page=20
    ),
    metadata=metadata
)

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

print(list_inputs_response)

//index.js file

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

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

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

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.ListInputs(
    {
        user_app_id: {
            user_id: USER_ID,
            app_id: APP_ID
        },
        page: 2,
        per_page: 20
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }

if (response.status.code !== 10000) {
            throw new Error("List inputs failed, status: " + response.status.description);
        }

console.log(response);

}
);

curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/inputs?page=2&per_page=20" \
  -H "Authorization: Key YOUR_PAT_HERE" \

POST Endpoints

For POST requests, the pagination parameters are included in the request body.

################################################################################
# In this section, we set the user authentication, app ID, and the concept we
# we want to filter by. 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 this to filter by your own concept
CONCEPT_ID = 'people'

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) # The userDataObject is required when using a PAT

post_annotations_searches_response = stub.PostAnnotationsSearches(
    service_pb2.PostAnnotationsSearchesRequest(
        user_app_id=userDataObject,
        searches = [
            resources_pb2.Search(
                query=resources_pb2.Query(
                    filters=[
                        resources_pb2.Filter(
                            annotation=resources_pb2.Annotation(
                                data=resources_pb2.Data(
                                    concepts=[  # You can search by multiple concepts
                                        resources_pb2.Concept(
                                            id=CONCEPT_ID,  # You could search by concept Name as well
                                            value=1  # Value of 0 will search for images that don't have the concept
                                        )
                                    ]
                                )
                            )
                        )
                    ]
                )
            ),
        ],
        pagination=service_pb2.Pagination(page=2, per_page=20)
    ),
    metadata=metadata
)

if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
    raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)

print(post_annotations_searches_response)

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [{
      "query": {
        "filters": [
          {
            "annotation": {
              "data": {
                "concepts": [
                  {
                    "id":"people",
                    "value": 1
                  }
                ]
              }
            }
          }
        ]
      }
    }],
    "pagination": {
        "page": 2,
        "per_page": 20
      }
  }'

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