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

# Get Accounts

> Retrieve accounts with optional filters

## Endpoint

```
POST https://api.ugc.inc/accounts
```

## Overview

Retrieve a list of accounts with optional filtering by tag, organization group, or user group. If no filters are provided, returns all accounts for your organization.

Supports keyset pagination via `limit`/`cursor` — pass `limit` to page through results
newest-first, using each response's `nextCursor` to fetch the next page.

## Request Body

<ParamField body="tag" type="string">
  Filter accounts by tag
</ParamField>

<ParamField body="type" type="'tiktok' | 'instagram'">
  Filter accounts by platform
</ParamField>

<ParamField body="org_group" type="string">
  Filter accounts by organization group
</ParamField>

<ParamField body="user_group" type="string">
  Filter accounts by user group
</ParamField>

<ParamField body="status" type="'pending' | 'initialized' | 'setup' | 'error'">
  Filter accounts by status
</ParamField>

<ParamField body="limit" type="number">
  Max rows to return. Omit to fetch all matching accounts (no pagination).
</ParamField>

<ParamField body="cursor" type="string">
  Opaque cursor from a previous response's `nextCursor`, to fetch the next page. Results are
  ordered newest-first.
</ParamField>

## Response

<ResponseField name="data" type="Account[]">
  Array of account objects matching the filters

  <Expandable title="Account properties">
    <ResponseField name="id" type="string">
      Unique account identifier
    </ResponseField>

    <ResponseField name="org_name" type="string | null">
      Name of the organization this account belongs to
    </ResponseField>

    <ResponseField name="type" type="string">
      Account platform type (`tiktok` or `instagram`)
    </ResponseField>

    <ResponseField name="tag" type="string | null">
      Custom tag for categorization
    </ResponseField>

    <ResponseField name="org_group" type="string | null">
      Organization group identifier
    </ResponseField>

    <ResponseField name="user_group" type="string | null">
      User group identifier
    </ResponseField>

    <ResponseField name="username" type="string | null">
      Account username/handle on the platform
    </ResponseField>

    <ResponseField name="nick_name" type="string | null">
      Display name shown on profile
    </ResponseField>

    <ResponseField name="pfp_url" type="string | null">
      URL to account's profile picture
    </ResponseField>

    <ResponseField name="warmup_enabled" type="boolean | null">
      Whether warmup tasks are enabled for this account
    </ResponseField>

    <ResponseField name="warmup_version" type="'original' | 'v1_smart' | null">
      Warmup scheduling algorithm version. `original` uses the standard scheduling logic, `v1_smart` uses an optimized algorithm with custom flows
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Description/interest area for the account. Used by v1\_smart warmup for browse tasks
    </ResponseField>

    <ResponseField name="keywords" type="string | null">
      Search keywords used for warmup tasks (comma-separated)
    </ResponseField>

    <ResponseField name="profiles" type="string | null">
      Profile usernames to search for warmup tasks (comma-separated)
    </ResponseField>

    <ResponseField name="bio" type="string | null">
      Account bio text
    </ResponseField>

    <ResponseField name="age_range" type="string | null">
      Age band the account's persona presents as (e.g. `18-24`)
    </ResponseField>

    <ResponseField name="sex" type="string | null">
      Gender the account's persona presents as
    </ResponseField>

    <ResponseField name="post_version" type="'original' | 'v1_custom' | 'manual_posting' | null">
      Post flow version. `original` uses standard posting flow, `v1_custom` uses customized posting flow, `manual_posting` skips automated posting
    </ResponseField>

    <ResponseField name="status" type="string">
      Account status: `pending`, `initialized`, `setup`, or `error`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Present when `limit` was passed. Pass back as `cursor` to fetch the next page; `null` means
  there are no more pages.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ugc.inc/accounts \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "tag": "influencer",
      "org_group": "group1",
      "user_group": "users1"
    }'
  ```

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

  response = requests.post(
      'https://api.ugc.inc/accounts',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'tag': 'influencer',
          'org_group': 'group1',
          'user_group': 'users1'
      }
  )

  data = response.json()

  if data['ok']:
      print('Accounts:', data['data'])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ugc.inc/accounts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tag: 'influencer',
      org_group: 'group1',
      user_group: 'users1'
    })
  });

  const data = await response.json();

  if (data.ok) {
    console.log('Accounts:', data.data);
  }
  ```

  ```typescript React theme={null}
  import { UGCClient } from 'ugcinc';

  const client = new UGCClient({
    apiKey: 'YOUR_API_KEY'
  });

  const response = await client.accounts.getAccounts({
    tag: 'influencer',
    org_group: 'group1',
    user_group: 'users1'
  });

  if (response.ok) {
    console.log('Accounts:', response.data);
    response.data.forEach(account => {
      console.log(`${account.username} (${account.type})`);
    });
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": [
      {
        "id": "acc_123456",
        "org_name": "My Organization",
        "type": "tiktok",
        "tag": "influencer",
        "org_group": "group1",
        "user_group": "users1",
        "username": "coolcreator",
        "nick_name": "Cool Creator",
        "pfp_url": "https://storage.example.com/avatar.jpg",
        "warmup_enabled": true,
        "warmup_version": "original",
        "description": "health and wellness content",
        "keywords": "fitness,workout,health",
        "profiles": "fitnessguru,healthcoach",
        "age_range": "18-24",
        "sex": "female"
      },
      {
        "id": "acc_789012",
        "org_name": "My Organization",
        "type": "instagram",
        "tag": "influencer",
        "org_group": "group1",
        "user_group": "users1",
        "username": "awesome_account",
        "nick_name": "Awesome Account",
        "pfp_url": "https://storage.example.com/avatar2.jpg",
        "warmup_enabled": false,
        "warmup_version": null,
        "description": null,
        "keywords": null,
        "profiles": null,
        "age_range": null,
        "sex": null
      }
    ],
    "nextCursor": null
  }
  ```
</ResponseExample>