> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Avatars

> Retrieve a paginated list of your avatars

## Endpoint

```
GET https://api.percify.io/v1/avatars
```

## Query Parameters

<ParamField query="limit" type="number" default="20">
  Number of avatars to return per page

  **Range:** 1-100
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of avatars to skip (for pagination)

  **Example:** `offset=20` with `limit=20` returns avatars 21-40
</ParamField>

<ParamField query="status" type="string">
  Filter by generation status

  **Options:** `queued`, `processing`, `completed`, `failed`
</ParamField>

<ParamField query="model" type="string">
  Filter by AI model used

  **Options:** `flux`, `imagen3`, `reality4`
</ParamField>

<ParamField query="visibility" type="string">
  Filter by visibility setting

  **Options:** `public`, `unlisted`, `private`
</ParamField>

<ParamField query="published" type="boolean">
  Filter by publication status

  **Options:** `true` (published only), `false` (unpublished only)
</ParamField>

<ParamField query="sortBy" type="string" default="createdAt">
  Sort field

  **Options:** `createdAt`, `likes`, `comments`, `remixes`
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort direction

  **Options:** `asc`, `desc`
</ParamField>

<ParamField query="search" type="string">
  Search avatars by prompt text or tags

  **Example:** `search=cyberpunk`
</ParamField>

## Response

<ResponseField name="avatars" type="array">
  Array of avatar objects
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="pagination fields">
    <ResponseField name="total" type="number">
      Total number of avatars matching filters
    </ResponseField>

    <ResponseField name="limit" type="number">
      Items per page
    </ResponseField>

    <ResponseField name="offset" type="number">
      Current offset
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether more pages exist
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.percify.io/v1/avatars?limit=20&offset=0&status=completed&sortBy=createdAt&sortOrder=desc',
    {
      headers: {
        'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
      }
    }
  );

  const data = await response.json();
  console.log(`Found ${data.pagination.total} avatars`);
  data.avatars.forEach(avatar => {
    console.log(`${avatar.id}: ${avatar.prompt}`);
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://api.percify.io/v1/avatars',
      params={
          'limit': 20,
          'offset': 0,
          'status': 'completed',
          'sortBy': 'createdAt',
          'sortOrder': 'desc'
      },
      headers={
          'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}'
      }
  )

  data = response.json()
  print(f"Found {data['pagination']['total']} avatars")
  for avatar in data['avatars']:
      print(f"{avatar['id']}: {avatar['prompt']}")
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.percify.io/v1/avatars?limit=20&offset=0&status=completed&sortBy=createdAt&sortOrder=desc" \
    -H "Authorization: Bearer $PERCIFY_API_KEY"
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "avatars": [
    {
      "id": "avatar_abc123",
      "status": "completed",
      "prompt": "cyberpunk warrior, neon lights, futuristic city",
      "model": "imagen3",
      "imageUrl": "https://cdn.percify.io/avatars/avatar_abc123.png",
      "thumbnailUrl": "https://cdn.percify.io/avatars/avatar_abc123_thumb.png",
      "width": 1024,
      "height": 1024,
      "creditCost": 5,
      "visibility": "public",
      "published": true,
      "likes": 42,
      "comments": 8,
      "createdAt": "2025-11-25T06:00:00Z"
    },
    {
      "id": "avatar_def456",
      "status": "completed",
      "prompt": "fantasy elf mage, magical forest, glowing staff",
      "model": "flux",
      "imageUrl": "https://cdn.percify.io/avatars/avatar_def456.png",
      "thumbnailUrl": "https://cdn.percify.io/avatars/avatar_def456_thumb.png",
      "width": 1024,
      "height": 1024,
      "creditCost": 2,
      "visibility": "private",
      "published": false,
      "likes": 0,
      "comments": 0,
      "createdAt": "2025-11-25T05:45:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}
```

## Pagination Example

```javascript theme={null}
async function fetchAllAvatars() {
  const allAvatars = [];
  let offset = 0;
  const limit = 50;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://api.percify.io/v1/avatars?limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
        }
      }
    );
    
    const data = await response.json();
    allAvatars.push(...data.avatars);
    
    hasMore = data.pagination.hasMore;
    offset += limit;
  }
  
  return allAvatars;
}
```

## Filtering Examples

### Get Published Avatars Only

```bash theme={null}
curl "https://api.percify.io/v1/avatars?published=true&visibility=public" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

### Search by Keyword

```bash theme={null}
curl "https://api.percify.io/v1/avatars?search=fantasy&limit=10" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

### Get Most Liked Avatars

```bash theme={null}
curl "https://api.percify.io/v1/avatars?sortBy=likes&sortOrder=desc&limit=10" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

### Get Processing Avatars

```bash theme={null}
curl "https://api.percify.io/v1/avatars?status=processing" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"
```

## Related Endpoints

* [Get Avatar](/api-reference/avatars/get) - Get single avatar details
* [Generate Avatar](/api-reference/avatars/generate) - Create new avatar
* [Delete Avatar](/api-reference/avatars/delete) - Remove avatar


## OpenAPI

````yaml GET /avatars
openapi: 3.1.0
info:
  title: Percify API
  description: >-
    Percify AI Avatar & Video Generation API - Create stunning AI-generated
    avatars, videos, and voice content
  version: 1.0.0
  contact:
    name: Percify Support
    email: support@percify.io
    url: https://percify.io
servers:
  - url: https://percify.io/api
    description: Production API
security:
  - bearerAuth: []
paths:
  /avatars:
    get:
      tags:
        - Avatars
      summary: List Avatars
      description: Get a paginated list of user's avatars
      operationId: listAvatars
      parameters:
        - name: limit
          in: query
          description: Maximum number of avatars to return
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: cursor
          in: query
          description: Pagination cursor for next page
          schema:
            type: string
      responses:
        '200':
          description: List of avatars
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvatarList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AvatarList:
      type: object
      properties:
        avatars:
          type: array
          items:
            $ref: '#/components/schemas/Avatar'
        nextCursor:
          type: string
          nullable: true
        hasMore:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
    Avatar:
      type: object
      properties:
        id:
          type: string
          description: Unique avatar identifier
        imageUrl:
          type: string
          format: uri
          description: URL to the generated avatar image
        prompt:
          type: string
          description: Prompt used for generation
        model:
          type: string
          description: AI model used
        status:
          type: string
          enum:
            - processing
            - completed
            - failed
          description: Generation status
        creditsUsed:
          type: integer
          description: Credits consumed for this generation
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Your Percify API token

````