Audiences API

The Audiences API returns the audience profiles configured for the caller's company. Audiences are used by AutoGenerator and other generation endpoints to tailor content tone, depth, and structure.

Full schemas and try-it-out forms live in the interactive API Reference.

Authentication

All endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

See Getting Started → Authentication.

Response envelope

Every endpoint returns the canonical envelope: { "success": true, "data": { ... } } on success or the standard error envelope on error.

Endpoint summary

Method	Path	Description	Sync/Async
GET	/api/v1/audiences	List audience profiles	Sync
POST	/api/v1/audiences/search	Search audience profiles	Sync

All endpoints are in the auto_generator rate-limit category. See Developer Guide → Usage quotas and rate limits.

---

GET /api/v1/audiences — List audiences

Returns the audiences configured for the caller's company. Supports opt-in cursor pagination — omit limit/cursor to receive the full list unchanged. See Developer Guide → Pagination.

Query parameters

Parameter	Type	Required	Description
feature	string	no	Filter by feature scope.
id	string	no	Filter to a single audience by id.
sort	string	no	Sort expression (for example name:asc).
limit	integer	no	Items per page (1–200, default 50). Enables pagination.
cursor	string	no	Opaque cursor from the previous response's next_cursor.

Example

cURL

curl "https://api.prezent.ai/api/v1/audiences?sort=name:asc" \
  -H "Authorization: Bearer $PREZENT_API_KEY"

Python

import os
import requests

url = "https://api.prezent.ai/api/v1/audiences"
headers = {
    "Authorization": f"Bearer {os.environ['PREZENT_API_KEY']}",
}
params = {"sort": "name:asc"}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
print(response.json())

Node.js

const axios = require('axios');

const listAudiences = async () => {
  const { data } = await axios.get(
    'https://api.prezent.ai/api/v1/audiences',
    {
      params: { sort: 'name:asc' },
      headers: {
        Authorization: `Bearer ${process.env.PREZENT_API_KEY}`,
      },
    }
  );

  console.log(data);
  return data;
};

listAudiences();

Success response (200)

{
  "success": true,
  "data": {
    "items": [
      { "id": "aud_exec", "name": "Executives" },
      { "id": "aud_sales", "name": "Sales team" }
    ],
    "next_cursor": null
  }
}

next_cursor is null on the last page (or when pagination was not requested). Pass it back as the cursor query parameter to fetch the next page.

---

POST /api/v1/audiences/search — Search audiences

Free-text and field-filtered search across audience profiles.

Query parameters

Parameter	Type	Required	Description
feature	string	no	Filter by feature scope.

Request body

Field	Type	Required	Description
query	string	no	Free-text search query.
id	string	no	Filter to a single audience by id.
sort	string	no	Sort expression.
filterBy	object	no	Field-level filter.
filterByCollection	object	no	Collection-level filter.
fields	array of string	no	Subset of fields to return.
extraFields	array of string	no	Additional fields to include beyond defaults.
limit	integer	no	Maximum number of results (default 15).

Example

cURL

curl -X POST https://api.prezent.ai/api/v1/audiences/search \
  -H "Authorization: Bearer $PREZENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "executive", "limit": 10 }'

Python

import os
import requests

url = "https://api.prezent.ai/api/v1/audiences/search"
headers = {
    "Authorization": f"Bearer {os.environ['PREZENT_API_KEY']}",
    "Content-Type": "application/json",
}
payload = {"query": "executive", "limit": 10}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

Node.js

const axios = require('axios');

const searchAudiences = async () => {
  const { data } = await axios.post(
    'https://api.prezent.ai/api/v1/audiences/search',
    { query: 'executive', limit: 10 },
    {
      headers: {
        Authorization: `Bearer ${process.env.PREZENT_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );

  console.log(data);
  return data;
};

searchAudiences();

Success response (200)

Search returns the top matches (capped by limit, most relevant first). It is a single ranked result set — there is no cursor to follow.

{
  "success": true,
  "data": {
    "items": [
      { "id": "aud_exec", "name": "Executives" }
    ]
  }
}

---

Errors

Common error codes:

• 400 — INVALID_INPUT.
• 401 — INVALID_API_KEY, EXPIRED_API_KEY, UNAUTHORIZED.
• 404 — ENDPOINT_NOT_FOUND.
• 429 — RATE_LIMIT_EXCEEDED, TOO_MANY_REQUESTS.
• 500 / 503 / 504 — standard server-side codes.

See the full catalog in Developer Guide → Error codes.