Skip to main content

Matrix Generation API

The Matrix Generation API creates combinatorial audience topics by computing the cartesian product of multiple dimension value arrays. For example, crossing 52 US states with 6 age ranges generates 312 classified topics in a single request. Classification uses the local rule-based engine (no LLM calls), making this endpoint fast and cost-free for bulk generation.

POST /api/topics/generate-matrix​

Generate topics from a cartesian product of dimensions.

Auth: API key with classify scope, or Clerk session

POST /api/topics/generate-matrix

Request Body​

{
  "dimensions": [
    {
      "name": "State",
      "values": ["California", "Texas", "New York", "Florida"]
    },
    {
      "name": "Age Range",
      "values": ["18-24", "25-34", "35-44", "45-54", "55-64", "65+"]
    }
  ],
  "template": "{State} {Age Range} Audience",
  "segmentType": "B2C",
  "parentCategory": "Demographics"
}
FieldTypeRequiredDescription
dimensionsarrayYesAt least 2 dimensions, each with name and values
dimensions[].namestringYesDimension name (e.g., "State", "Age Range")
dimensions[].valuesstring[]YesDimension values (at least 1 per dimension)
templatestringNoTopic name template using {DimensionName} placeholders. Defaults to joining values with spaces.
segmentTypestringNoOverride segment type for all generated topics
parentCategorystringNoOverride parent category (41 types) for all generated topics
taxonomyTypestringNoOverride taxonomy type group (13 groups) for all generated topics

Combination Limit​

The total number of combinations (cartesian product) must not exceed 5,000 topics. For the example above: 4 states x 6 age ranges = 24 topics.

Response (200)​

{
  "batchId": "matrix_1740000000000_a3b7c9",
  "totalTopics": 24,
  "created": 22,
  "duplicates": 0,
  "errors": 2,
  "topicIds": ["ot_01...", "ot_02...", "ot_03..."]
}
FieldTypeDescription
batchIdstringUnique identifier for this generation batch
totalTopicsnumberTotal combinations computed
creatednumberTopics successfully created
duplicatesnumberTopics skipped due to existing duplicates
errorsnumberTopics that failed classification
topicIdsstring[]IDs of newly created topics

curl Example​

curl -X POST https://app.audiencegpt.com/api/topics/generate-matrix \
  -H "Authorization: Bearer txadv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": [
      {
        "name": "Seniority",
        "values": ["C-Suite", "VP", "Director", "Manager", "Individual Contributor"]
      },
      {
        "name": "Department",
        "values": ["Marketing", "Engineering", "Sales", "Finance", "HR"]
      }
    ],
    "template": "{Seniority} - {Department}",
    "segmentType": "B2B"
  }'

TypeScript Example​

interface MatrixRequest {
  dimensions: { name: string; values: string[] }[];
  template?: string;
  segmentType?: string;
  parentCategory?: string;
  taxonomyType?: string;
}

async function generateMatrix(request: MatrixRequest) {
  const response = await fetch(
    "https://app.audiencegpt.com/api/topics/generate-matrix",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(request),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

// Generate B2B firmographic matrix: 5 seniority x 15 departments = 75 topics
const result = await generateMatrix({
  dimensions: [
    { name: "Seniority", values: ["C-Suite", "VP", "Director", "Manager", "IC"] },
    { name: "Department", values: ["Marketing", "Engineering", "Sales", "Finance", "HR",
      "Operations", "Legal", "IT", "Product", "Design", "Customer Success",
      "Business Development", "Data Science", "Security", "Procurement"] },
  ],
  template: "{Seniority} {Department} Decision Makers",
  segmentType: "B2B",
  parentCategory: "Business Technology",
});

Known Dimension Sets​

AudienceGPT includes 22 pre-built dimension value sets based on IAB, Experian, and Acxiom standards. When using the chatbot UI, natural language like "state by age" auto-resolves to the full US State and Age Range dimensions.

Demographic Dimensions​

DimensionValues
Age Range18-24, 25-34, 35-44, 45-54, 55-64, 65+
GenderMale, Female, Non-Binary
Income RangeUnder $25K, $25K-$50K, $50K-$75K, $75K-$100K, $100K-$150K, $150K-$200K, $200K-$300K, $300K-$500K, $500K+
Net Worth13 ranges from Under $50K to $10M+
Education LevelHigh School, Some College, Associate, Bachelor, Master, Doctorate
Marital StatusSingle, Married, Divorced, Widowed, Separated
HomeownershipOwner, Renter, Other
Presence of ChildrenNo Children, Has Children, Infant (0-2), Young (3-5), School Age (6-12), Teen (13-17)
Household Size1, 2, 3-4, 5+
Ethnicity7 categories
Language10 languages
Life Stage9 stages
Home Value7 ranges
Length of Residence5 ranges
Employment Status6 statuses

Geographic Dimensions​

DimensionValues
US State50 states + DC + Puerto Rico (52 values)

Firmographic Dimensions​

DimensionValues
Seniority LevelC-Suite, VP, Director, Manager, Individual Contributor
Department15 departments
Company Size8 ranges (1-10 to 10,000+)
Company Revenue7 ranges (Under $1M to $10B+)
Company Industry15 industries
C-Suite TitleCEO, CFO, CTO, CMO, COO, CIO, CHRO, CDO

Processing Details​

  • Classification: Each generated topic is classified using the local rule-based engine (7-layer pipeline)
  • Chunking: Topics are processed in chunks of 500 for database insertion
  • Deduplication: Standard embedding-based duplicate detection applies
  • Source tracking: All generated topics are tagged with _source: "matrix" for filtering

Error Responses​

StatusBodyDescription
400{"error": "At least 2 dimensions are required"}Need minimum 2 dimensions
400{"error": "Too many combinations (6000). Maximum is 5000."}Exceeds combination limit
400{"error": "Dimension \"?\" must have a name and at least one value"}Invalid dimension
401{"error": "Unauthorized"}Invalid credentials
429{"error": "Monthly classifications quota exceeded"}Quota exceeded

Next Steps​