Learn how to programmatically fetch your chatbot project’s statistics using CustomGPT’s RAG APIs Python SDK implementation. In this guide, we walk through setting up the SDK and obtaining detailed agent stats – such as page counts, words indexed, or credits used – via the CustomGPT API. This is essential for monitoring a chatbot’s content coverage and usage in a retrieval-augmented generation (RAG) system.
Make sure you have read our Getting Started with CustomGPT.ai for New Developers guide to understand the platform basics and API key setup.
Notebook Link: CustomGPT Cookbook – SDK_Get_Project_Stats.ipynb
Introduction
Hi there! In this step-by-step tutorial, we’ll demonstrate how to retrieve project statistics using the CustomGPT Python SDK. Project stats provide a summary of your CustomGPT agent’s content and usage – think number of pages indexed, total tokens or words indexed, and other metrics that help you gauge your chatbot’s scope and performance.
By the end of this guide, you’ll be able to programmatically get these stats without needing to log into the CustomGPT dashboard, enabling you to integrate analytics into your own tools or workflows.
Why does this matter? If you’re building a citation-based chatbot with CustomGPT (a typical RAG setup), keeping an eye on project stats lets you know if all your content is indexed and how your usage is growing. For example, you might want to ensure a new document you added is reflected in the page count, or monitor if you’re nearing any usage limits. The CustomGPT API makes it easy to fetch these details on demand.
Prerequisites
- CustomGPT API Key – You’ll need your CustomGPT API key (token) with access to your project. Generate this from the CustomGPT.ai dashboard if you haven’t already.
- CustomGPT Python SDK installed – This tutorial uses the customgpt-client Python package. Ensure you have it installed in your environment (we’ll show the pip install command).
- Python environment – A working Python setup, such as Google Colab, Jupyter Notebook, or any Python script environment, to run the example code.
- An existing CustomGPT project – If you already have a project (chatbot) created on CustomGPT, you can use its Project ID. If not, we’ll show how to create a sample project on the fly for this demo.
Step-by-Step Tutorial
Let’s dive in and retrieve the agent stats for a CustomGPT project using the SDK. Follow these steps:
- Install and import the CustomGPT SDK. First, install the CustomGPT client library and import the necessary class. Then set your API key for authentication:
!pip install customgpt-client
from customgpt_client import CustomGPT
CustomGPT.api_key = "YOUR_API_TOKENGet 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.
2. In the above code, replace “YOUR_API_TOKEN” with your actual CustomGPT API key. This sets up the SDK to communicate with the CustomGPT API. The customgpt-client library provides the CustomGPT class which we use to access various endpoints (projects, pages, conversations, etc.).
3. (Optional) Create a new project via a sitemap. If you don’t have an existing project ID to work with, you can create a project on the fly. In this example, we’ll create a project by providing a sitemap URL for the bot to ingest:
# Give a name to your new project
project_name = "Example ChatBot using Sitemap"
sitemap_path = "https://adorosario.github.io/small-sitemap.xml"
create_project = CustomGPT.Project.create(project_name=project_name, sitemap_path=sitemap_path)
print(create_project)4. Here we create a project called “Example ChatBot using Sitemap” by pointing it to a sample sitemap URL. The SDK call CustomGPT.Project.create(…) returns a response object containing details of the created project. We print the response to verify it succeeded. The project will automatically start indexing the pages found in the sitemap. (In a real scenario, use your own website’s sitemap URL or skip this step if you already have a project.)
5. Get the Project ID. Whether you used an existing project or just created one, obtain the project_id that we need for fetching stats:
project_id = create_project.parsed.data.id6. In the case of a newly created project, we parse the returned object to extract the id. If you already know your project’s ID, you can simply assign it here (e.g., project_id = “your_project_id”). The project_id is a unique identifier that CustomGPT uses to reference your bot.
7. Retrieve project statistics via the SDK. Now, call the CustomGPT API for stats using the SDK method:
project_stats = CustomGPT.Project.stats(project_id=project_id)
print(project_stats)8. This one-liner reaches out to the CustomGPT service and retrieves the stats for the specified project. We then print the project_stats response. Under the hood, the SDK calls the endpoint GET /projects/{project_id}/stats for you. The response contains a variety of metrics about your project.
9. Inspect the stats output. The printed output will typically include a status and a data payload. For example, you might see a JSON structure in the console like:
{
"status": "success",
"data": {
"total_pages": 5,
"total_words_indexed": 12000,
"total_queries": 0,
"credits_used": 150,
... more stats fields ...
}
}
10. (The exact fields may vary). Key stats often include the number of pages indexed (total_pages), total words or tokens indexed from your content, number of queries (conversations) run on the project, and credits or tokens consumed. These give you a snapshot of your bot’s scope and activity. For instance, in the example above, the project has 5 pages indexed (from the sitemap), around 12k words processed, and so far no user queries. Use these values to monitor growth or verify that recent content additions were successful.
11. Utilize the stats as needed. Now that you have the stats in a project_stats object, you can programmatically use this data. For example, you could log it for analytics, display it on a custom dashboard, or trigger alerts if certain thresholds are exceeded. Accessing fields depends on the SDK’s response structure – if project_stats.parsed.data contains a dictionary, you might retrieve values like:
stats_data = project_stats.parsed.data
print("Pages indexed:", stats_data.total_pages)
print("Words indexed:", stats_data.total_words_indexed)12. This will output the individual stat values in a friendly format. In summary, your code can inspect stats_data to get whichever metric you need. The CustomGPT SDK takes care of the API call and gives you an easy Python object to work with.
That’s it! You’ve successfully fetched the statistics for a CustomGPT project using the Python SDK. This process can be automated to run periodically if you want to track your chatbot’s index growth or usage over time.
FAQs
What kind of statistics can I get from the CustomGPT project stats?
The project stats include various metrics about your chatbot’s knowledge base and usage. Common stats are the total number of pages indexed (from files, websites, etc.), the total number of words or tokens indexed, the number of conversations or queries made with the bot, and the amount of credits or tokens consumed by those queries. These give you insight into both the content size of your bot and how actively it’s being used.
How up-to-date are the statistics? Do they update in real-time?
Project statistics are updated as content is added and as users interact with the bot. When you call the stats endpoint, it fetches the latest metrics at that moment. For example, if you just added a new file or webpage to your project, the page count will reflect the addition once indexing is complete. Similarly, query counts increment as conversations occur. While it’s not exactly “real-time” to the second (there may be minor processing delays), it’s up-to-date to the last completed indexing or interaction.
Do I need to create a new project each time to get stats?
No, not at all. We created a project in this tutorial just for demonstration. In practice, you would call CustomGPT.Project.stats(project_id) on an existing project that you want to monitor. You only need the project_id. In fact, you can loop through multiple project IDs if you want to gather stats for all your bots.
What if I get an error or empty data when calling the stats API?
Ensure that the project_id is correct and that your API key has access to that project. An invalid or unauthorized project ID will result in an error. If the project exists but has no data (e.g., no pages indexed yet), some fields might be zero or null. Always check the status in the response; if it’s “error”, the message field in the response should indicate what went wrong (for example, “Project not found” or “Unauthorized”).
How can I use these stats in my own dashboard or application?
Since the SDK returns stats in a structured format (likely as a Python dict or an object with attributes), you can extract the values and send them to any interface you want. For instance, you could render them on a web dashboard, push them to a logging/monitoring service, or even set up a script to email you a weekly report of your bot’s stats. The CustomGPT API gives you the raw data, and it’s up to you how to utilize it in your application for analytics or monitoring.
Related Posts
- SDK: Get Settings for a Particular Project Using CustomGPT API – A Detailed Tutorial – Learn how to fetch a project’s configuration settings via the SDK, which goes hand-in-hand with understanding project stats.
- SDK: Update Project Settings Using CustomGPT API – A Comprehensive Guide – After viewing stats, you might want to tweak your project’s settings. This guide shows how to update settings like the default prompt or language.
- SDK: List All Pages Belonging to a Project Using CustomGPT API – A How-To Guide – Want to see which pages are counted in your project stats? This post explains how to list every page your project has indexed.
- SDK: Reindex a Page Belonging to a Project Using CustomGPT API – If your stats indicate a page count that seems off due to updated content, learn how to reindex pages to refresh your project’s knowledge base.
Priyansh is Developer Relations Advocate who loves technology, writer about them, creates deeply researched content about them.
