Manage multiple CustomGPT chatbots by listing all your projects via the CustomGPTs RAG APIs Python SDK implementation, with support for pagination. If you have several chatbot projects (agents) in CustomGPT, you might want to fetch a list of all of them programmatically. In this guide, we’ll use the CustomGPT Python SDK to list all agents (projects) in an account and demonstrate how to handle pagination in case you have more projects than can be returned in a single response.
Be sure to have followed Getting Started with CustomGPT.ai for New Developers so you have your API key and environment configured properly.
Notebook Link: CustomGPT Cookbook – SDK_List_all_projects_using_pagination.ipynb
Introduction
If you’re an enterprise user or a developer managing multiple chatbots with CustomGPT, being able to get an inventory of all your projects is essential. Each project corresponds to a different CustomGPT agent (for example, a bot for product support, another for internal docs, etc.). The CustomGPT API allows you to list projects, and when you have many, the results are paginated.
In this tutorial, we will:
- Retrieve the first page of projects using the SDK.
- Check the response for total projects and pages.
- Loop through subsequent pages to gather all projects.
- Print out or otherwise utilize the list of projects.
By the end, you’ll be able to fetch all project names/IDs in your account, which can be used for generating reports or iterating through projects to perform batch operations.
Prerequisites
- CustomGPT API Key – Your API token with permission to read projects in your account.
- CustomGPT Python SDK – Ensure the customgpt-client library is installed.
- Multiple projects in CustomGPT – This guide is most relevant if you have more than one project. If you only have a single project, listing projects will of course just return that one.
- Python environment – (Colab, Jupyter, etc.) to run the code examples.
Step-by-Step Guide
Follow these steps to list all agents (projects), handling pagination:
- Install and import the SDK, and set API key.
Begin by installing the CustomGPT SDK and configuring your API key for authentication:
!pip install customgpt-client
from customgpt_client import CustomGPT
CustomGPT.api_key = "YOUR_API_TOKEN"Get API keys
To get your API key, there are two ways:
Method 1 – Via Agent
- Agent > All Agents.
- Select your agent and go to deploy, click on the API key section and create an API.
Method 2 – Via Profile section.
- Go to profile (top right corner of your screen)
- Click on My Profile
- You will see the screen something like this (below screenshot). Here you can click on “Create API key”, give it a name and copy the key.
Please save this secret key somewhere safe and accessible. For security reasons, You won’t be able to view it again through your CustomGPT.ai account. If you lose this secret key, you’ll need to generate a new one.
- This sets up our environment. The CustomGPT class will provide the Project.list method we need.
- Call the API to list projects (first page).
Use the SDK to retrieve the first set of projects:
projects_page = CustomGPT.Project.list()
print(projects_page)- By default, CustomGPT.Project.list() will fetch the first page of projects (page 1). The print will show the raw response, which should include a list of projects (under some field like data) and metadata such as total count or total pages.
- Parse the response and extract data.
Let’s extract the project list and the total number of projects from the first page response:
project_data = projects_page.parsed.data.data # list of projects on this page
total_projects = projects_page.parsed.data.total # total number of projects across all pages
print(f"Projects on page 1: {len(project_data)} out of {total_projects} total projects")- Here we assume the response structure has data.data as the list of project entries and data.total as the total count of projects. This is suggested by the SDK’s naming in the notebook. The print will confirm how many projects were on page 1 and how many in total.
Each project entry in project_data likely contains details like project id, name, creation date, etc. - Iterate through remaining pages (if any).
If total_projects is more than the number of projects per page, we need to fetch subsequent pages. The API typically returns, say, 10 projects per page by default. We can calculate total pages or simply loop until we’ve got all projects. One strategy:
# We already have page 1 data
all_projects = project_data[:] # make a copy of the list
projects_per_page = len(project_data)
total_pages = (total_projects // projects_per_page) + (1 if total_projects % projects_per_page != 0 else 0)
for page in range(2, total_pages + 1):
projects_page = CustomGPT.Project.list(page=page)
page_data = projects_page.parsed.data.data
all_projects.extend(page_data)
print(f"Fetched page {page}, {len(page_data)} projects")- This code calculates total_pages based on the count. It then loops from page 2 up to the last page, fetching each and appending the projects to all_projects. We also print a log for each page fetched.
Alternatively, if the API returned a direct total_pages field, you could use that instead of computing. The concept remains: iterate until you’ve retrieved all projects.
We include a short delay (time.sleep(1) for example) if needed to be polite with the API (the example in the notebook had a 5-second sleep, perhaps to avoid hitting rate limits). - Verify all projects are collected.
After the loop, all_projects should contain all project objects. You can verify:
print(f"Total projects collected: {len(all_projects)}")
for proj in all_projects:
print(proj.id, "-", proj.name)- This will list each project’s ID and name. The number of projects collected should match the total_projects we saw earlier.
Example output might be:
Total projects collected: 12
proj_abc123 – Support Bot
proj_def456 – Documentation QA Bot
proj_ghi789 – HR Policy Chatbot
... (and so on for all projects)- This confirms we have the complete list.
- Use the project list as needed.
Now that you have all_projects in a Python list, you can use it for whatever management tasks you want:
- Displaying all project names in an admin dashboard.
- Iterating through them to perform batch operations (like updating a setting on all projects, or gathering stats for each as shown in other tutorials).
- Checking if a certain project exists by name or ID.
- Or simply keeping an inventory log.
- Displaying all project names in an admin dashboard.
- Each project object likely contains more than just ID and name – it might have flags like whether it’s public, when it was created, etc., which you can also utilize.
And that’s how you list all projects in your CustomGPT account using the Python SDK, handling any pagination to ensure none are missed.
FAQs
What details are included for each project in the list?
Each project entry usually includes its unique id, the name of the project, and possibly other metadata such as creation timestamp, last updated time, and flags like is_public (sharing status). It may also include counts (like number of pages or conversations) if the API provides them in the listing, though often those are obtained via separate calls (stats API). The primary ones you will definitely have are the ID and name, which are key for referencing the project in other API calls.
I only have one project, do I need to worry about pagination?
If you have one project, Project.list() will just return that single project (likely with total count = 1). No further pages to fetch. The code above will handle it gracefully (the loop for page 2..total_pages will not execute because total_pages would be 1). So it’s fine to use the same approach regardless of count – it will just end quickly if there’s only one page of results.
After listing projects, can I get more details or delete/update them via SDK?
Absolutely. Once you have the project IDs, you can use other API calls on each. For example, you could iterate through all_projects and call CustomGPT.Project.stats(project_id) for each to get their stats (see the Project Stats guide). Or use CustomGPT.Project.update to change something about each project (like making them all private/public, etc.). You can also delete a project using
CustomGPT.Project.delete(project_id) if needed (use with caution!). Essentially, listing projects is often the first step before performing some operation on each project.
Related Posts
- SDK: Get Project Stats Using CustomGPT API – Step-by-Step Guide – After listing all projects, you might want to fetch metrics for each. This guide shows how to get stats for a given project (which you can loop over for all projects).
- SDK: Update a Project Name with CustomGPT API – Tutorial – If you want to programmatically rename projects (perhaps based on some naming convention or after listing them), see this guide.
- SDK: Update Project Sharing and Get Project Share Link – Useful if you need to adjust the sharing settings of multiple projects. For instance, after listing, you might decide to make some projects public or retrieve their share links.
- SDK: Delete a Conversation Using CustomGPT API – While not directly about projects, if you’re listing projects to manage them, you might also be interested in how to manage conversations within those projects. This guide covers updating or deleting conversations (chats) in a project.
Priyansh is Developer Relations Advocate who loves technology, writer about them, creates deeply researched content about them.
