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

# List Contacted Creators

> List creators contacted by your TopYappers outreach agent

## `GET /api/v1/agent/contacted-creators`

Returns creators who have received at least one non-failed outbound email from your agent. This is the fastest way to map an inbox email address back to the creator, projects, threads, and reply status.

## Query parameters

| Parameter                | Type    | Description                                                                           |
| ------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `projectId`              | string  | Filter to one agent project.                                                          |
| `creatorEmail` / `email` | string  | Case-insensitive exact creator email match.                                           |
| `creatorEmailContains`   | string  | Case-insensitive partial creator email match. Ignored when `creatorEmail` is present. |
| `creatorId`              | string  | Filter by creator ID.                                                                 |
| `page`                   | integer | Page number. Default: `1`.                                                            |
| `perPage`                | integer | Results per page. Default: `50`, maximum: `100`.                                      |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.topyappers.com/api/v1/agent/contacted-creators?email=creator@example.com" \
    -H "x-ty-api-key: $TY_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    email: 'creator@example.com',
    perPage: '25',
  });

  const res = await fetch(
    `https://api.topyappers.com/api/v1/agent/contacted-creators?${params.toString()}`,
    {
      headers: {
        'x-ty-api-key': process.env.TY_API_KEY,
      },
    },
  );

  const payload = await res.json();
  ```
</CodeGroup>

## Response fields

Each item in `response.data` includes:

| Field                                                      | Description                                                       |
| ---------------------------------------------------------- | ----------------------------------------------------------------- |
| `creator_email`                                            | Email address contacted by the agent.                             |
| `creator_id`, `creator_name`, `creator_platform`           | Creator context captured when outreach was sent.                  |
| `project_ids`                                              | Agent project IDs that contacted this creator.                    |
| `thread_ids`                                               | Gmail thread IDs associated with the creator.                     |
| `sent_messages_count`                                      | Number of non-failed outbound messages sent.                      |
| `reply_messages_count`                                     | Number of inbound replies saved for the matching thread or email. |
| `has_replies`                                              | `true` when at least one inbound reply exists.                    |
| `first_contacted_at`, `last_contacted_at`, `last_reply_at` | ISO timestamp fields.                                             |
| `last_subject`, `last_status`, `last_body_preview`         | Preview of the latest outbound message.                           |

## Example response

```json theme={null}
{
  "message": "OK",
  "response": {
    "data": [
      {
        "creator_email": "creator@example.com",
        "creator_id": "instagram_123",
        "creator_name": "Creator Name",
        "creator_platform": "instagram",
        "project_ids": ["662f01a2c86c2af2a2b9f123"],
        "thread_ids": ["18f8d5c7a1b12345"],
        "sent_messages_count": 2,
        "reply_messages_count": 1,
        "has_replies": true,
        "first_contacted_at": "2026-05-01T10:15:00",
        "last_contacted_at": "2026-05-04T10:15:00",
        "last_reply_at": "2026-05-05T14:20:00",
        "last_subject": "Partnership idea",
        "last_status": "replied",
        "last_body_preview": "Loved your recent post about meal prep..."
      }
    ],
    "page": 1,
    "per_page": 50,
    "next_page": 0,
    "total_pages": 1,
    "total": 1
  }
}
```