---
updatedAt: 2026-04-29T16:33:48.000Z
agentTools:
  projectIndex: https://docs.customgpt.ai/llms.txt
---

# List all agents.

Returns all agents in your account, sorted by creation date with the most recent first. Use this endpoint to get an overview of your agents or to retrieve agent IDs for other API calls. Results are paginated with a default page size of 10.

Notes: Use the page query parameter to fetch additional results.

# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "CustomGPT.ai",
    "description": "API Documentation for CustomGPT.ai.",
    "contact": {
      "name": "CustomGPT.ai",
      "url": "https://app.customgpt.ai",
      "email": "hello@customgpt.ai"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://app.customgpt.ai",
      "description": "API Version 1"
    }
  ],
  "paths": {
    "/api/v1/projects": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "List all agents.",
        "description": "Returns all agents in your account, sorted by creation date with the most recent first. Use this endpoint to get an overview of your agents or to retrieve agent IDs for other API calls. Results are paginated with a default page size of 10.\n\nNotes: Use the page query parameter to fetch additional results.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number to retrieve. Page numbering starts at 1.\n\nIncrement until the response's `last_page` value is reached to paginate through all results. Default: 1.",
            "required": false,
            "schema": {
              "default": 1,
              "type": "integer",
              "example": 1
            }
          },
          {
            "name": "duration",
            "in": "query",
            "description": "The duration of the agents to list.",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "example": 90
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort direction for results.",
            "required": false,
            "schema": {
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "type": "string",
              "example": "desc"
            }
          },
          {
            "name": "orderBy",
            "in": "query",
            "description": "Field to sort results by.",
            "required": false,
            "schema": {
              "enum": [
                "id",
                "created_at"
              ],
              "default": "id",
              "type": "string",
              "example": "id"
            }
          },
          {
            "name": "width",
            "in": "query",
            "description": "The width of the embed code. Defaults to 100%.",
            "required": false,
            "schema": {
              "default": "100%",
              "type": "string",
              "example": "50rem"
            }
          },
          {
            "name": "height",
            "in": "query",
            "description": "The height of the embed code. Defaults to 100%.",
            "required": false,
            "schema": {
              "default": "auto",
              "type": "string",
              "example": "50rem"
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Filter the results by agent name",
            "required": false,
            "schema": {
              "type": "string",
              "example": "Sample agent"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved list of agents that belong to the user.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "description": "The status of the response",
                      "enum": [
                        "error",
                        "success"
                      ],
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "description": "The page number of this response. The first page is 1.",
                          "type": "integer",
                          "example": 1
                        },
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Project"
                          }
                        },
                        "first_page_url": {
                          "description": "The first page url",
                          "type": "string",
                          "example": "https://app.customgpt.ai/api/v1/users?page=1"
                        },
                        "from": {
                          "description": "The first item number of the current page",
                          "type": "integer",
                          "example": 1
                        },
                        "last_page": {
                          "description": "Total number of pages available. Pagination is complete when the requested `page` equals `last_page`.",
                          "type": "integer",
                          "example": 1
                        },
                        "last_page_url": {
                          "description": "The last page url",
                          "type": "string",
                          "example": "https://app.customgpt.ai/api/v1/users?page=1"
                        },
                        "next_page_url": {
                          "description": "The next page url",
                          "type": "string",
                          "example": "https://app.customgpt.ai/api/v1/users?page=1"
                        },
                        "path": {
                          "description": "The current page url",
                          "type": "string",
                          "example": "https://app.customgpt.ai/api/v1/users?page=1"
                        },
                        "per_page": {
                          "description": "Number of results returned per page.",
                          "type": "integer",
                          "example": 10
                        },
                        "prev_page_url": {
                          "description": "The previous page url",
                          "type": "string",
                          "example": "https://app.customgpt.ai/api/v1/users?page=1"
                        },
                        "to": {
                          "description": "The last item number of the current page",
                          "type": "integer",
                          "example": 1
                        },
                        "total": {
                          "description": "The total number of items",
                          "type": "integer",
                          "example": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ApiTokenValidationErrorResponse"
          },
          "429": {
            "$ref": "#/components/responses/ResourceExhaustedErrorResponse"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerErrorResponse"
          }
        },
        "security": [
          {
            "BearerToken": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Agent ID",
            "type": "integer",
            "example": 1
          },
          "project_name": {
            "description": "Agent name",
            "type": "string",
            "example": "My Agent"
          },
          "sitemap_path": {
            "description": "Agent sitemap",
            "type": "string",
            "example": "https://www.example.com/sitemap.xml"
          },
          "is_chat_active": {
            "description": "Returns true when the agent has finished processing your documents and is ready to respond to queries. After creating an agent or adding new data sources, poll GET /api/v1/projects/{projectId} every 5-10 seconds until is_chat_active is true before sending the first message.",
            "default": false,
            "type": "boolean",
            "example": true
          },
          "is_master": {
            "description": "Whether the agent is a master agent.",
            "default": false,
            "type": "boolean",
            "example": false
          },
          "user_id": {
            "description": "User ID of the agent owner",
            "type": "integer",
            "example": 1
          },
          "team_id": {
            "description": "Team ID of the agent owner",
            "type": "integer",
            "example": 1
          },
          "created_at": {
            "description": "Date and time when the agent was created",
            "default": "2023-05-08 13:06:55",
            "format": "date-time",
            "type": "string",
            "example": "2021-01-01 00:00:00"
          },
          "updated_at": {
            "description": "Date and time when the agent was last updated",
            "default": "2023-05-08 13:06:55",
            "format": "date-time",
            "type": "string",
            "example": "2021-01-01 00:00:00"
          },
          "deleted_at": {
            "description": "Date and time when the agent was deleted",
            "format": "date-time",
            "type": "string",
            "nullable": true,
            "example": "2021-01-01 00:00:00"
          },
          "type": {
            "description": "The type of content source used to train this agent.",
            "enum": [
              "SITEMAP",
              "URL"
            ],
            "default": "SITEMAP",
            "type": "string",
            "example": "SITEMAP"
          },
          "is_shared": {
            "description": "Is the agent public or not",
            "default": false,
            "type": "boolean",
            "example": true
          },
          "shareable_slug": {
            "description": "Shareable slug that can be used to share the agent",
            "format": "md5",
            "type": "string",
            "nullable": true,
            "example": "1234567890abcdef1234567890abcdef"
          },
          "shareable_link": {
            "description": "Shareable link that can be used to share the agent",
            "format": "url",
            "type": "string",
            "nullable": true
          },
          "embed_code": {
            "description": "Embed code that can be used to embed the agent",
            "format": "html",
            "type": "string",
            "nullable": true
          },
          "live_chat_code": {
            "description": "Live chat code that can be used to embed the live chat",
            "format": "html",
            "type": "string",
            "nullable": true
          },
          "are_licenses_allowed": {
            "description": "Whether licenses are allowed or not",
            "default": false,
            "type": "boolean",
            "example": true
          },
          "subdomain_slug": {
            "description": "Subdomain slug that can be used to share the agent",
            "format": "md5",
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "responses": {
      "ApiTokenValidationErrorResponse": {
        "description": "API Token is either missing or invalid",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "description": "The status of the response",
                  "enum": [
                    "error",
                    "success"
                  ],
                  "type": "string",
                  "example": "error"
                },
                "url": {
                  "description": "The URL of the request",
                  "type": "string",
                  "example": "https://app.customgpt.ai/api/v1/projects/1"
                },
                "data": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "description": "The error status code",
                      "enum": [
                        400,
                        401,
                        403,
                        404,
                        422,
                        500,
                        503
                      ],
                      "type": "integer",
                      "example": 401
                    },
                    "message": {
                      "type": "string",
                      "example": "API Token is either missing or invalid"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerErrorResponse": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "description": "The status of the response",
                  "enum": [
                    "error",
                    "success"
                  ],
                  "type": "string",
                  "example": "error"
                },
                "url": {
                  "description": "The URL of the request",
                  "type": "string",
                  "example": "https://app.customgpt.ai/api/v1/projects/1"
                },
                "data": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "description": "The error status code",
                      "enum": [
                        400,
                        401,
                        403,
                        404,
                        422,
                        500,
                        503
                      ],
                      "type": "integer",
                      "example": 500
                    },
                    "message": {
                      "type": "string",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ResourceExhaustedErrorResponse": {
        "description": "Too many requests. You have exceeded your API rate limit.",
        "headers": {
          "X-RateLimit-Limit": {
            "description": "The maximum number of requests allowed per minute for your plan (Standard: 90, Premium/Enterprise: 120).",
            "schema": {
              "type": "integer",
              "example": 90
            }
          },
          "X-RateLimit-Remaining": {
            "description": "The number of requests remaining in the current rate limit window.",
            "schema": {
              "type": "integer",
              "example": 89
            }
          },
          "Retry-After": {
            "description": "The number of seconds to wait before making another request. Only present on 429 responses.",
            "schema": {
              "type": "integer",
              "example": 60
            }
          },
          "X-RateLimit-Reset": {
            "description": "Unix timestamp when the rate limit window resets. Only present on 429 responses.",
            "schema": {
              "type": "integer",
              "example": 1743037694
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "description": "The status of the response",
                  "enum": [
                    "error",
                    "success"
                  ],
                  "type": "string",
                  "example": "error"
                },
                "url": {
                  "description": "The URL of the request",
                  "type": "string",
                  "example": "https://app.customgpt.ai/api/v1/projects/1"
                },
                "data": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "description": "The error status code",
                      "enum": [
                        400,
                        401,
                        403,
                        404,
                        422,
                        500,
                        503
                      ],
                      "type": "integer",
                      "example": 429
                    },
                    "message": {
                      "description": "The error message",
                      "type": "string",
                      "example": "Too Many Attempts."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerToken": {
        "type": "http",
        "description": "HTTP Bearer authentication using a CustomGPT API token.\n\nHow to obtain a token:\n1. Log in to your CustomGPT dashboard\n2. Go to Developers page in the sidebar\n3. Click Create new key and copy the token\n\nUsage: Include the token in every request:\n Authorization: Bearer YOUR_API_TOKEN\n\nTokens do not expire by default but can be configured to expire. Token also can be revoked from the dashboard. A missing or invalid token returns 401 Unauthorized.",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "tags": [
    {
      "name": "Agents",
      "description": "API Endpoints for Agents"
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  }
}
```