Skip to main content

CSV Export

The admin CSV export provides a configurable, streaming download of global topics with selectable fields, optional filters, and efficient query optimization for large catalogs. Super admins can export the entire global catalog or filtered subsets for analysis, platform onboarding, or compliance audits.

This guide covers the export API, available fields, filtering options, and strategies for handling large datasets.

Export Endpoint​

API: GET /api/admin/topics/export

Authentication: Requires super admin access (requireSuperAdmin).

Response: Returns a CSV file download with the filename format taxonomy-export-YYYY-MM-DD.csv.

Required Parameters​

ParameterTypeDescription
fieldsstring (comma-separated)List of field keys to include in the export, in order

Optional Filter Parameters​

ParameterTypeDescription
searchstringCase-insensitive substring match on topic name
parentCategorystringFilter by parent category (one of 41 types)
segmentTypestringFilter by segment type (B2B, B2C, B2B2C, B2E, B2G)

Example Request​

GET /api/admin/topics/export?fields=topic_name,parent_category,segment_type,segment_name_tradedesk&parentCategory=Business%20Technology

Available Export Fields​

Core Fields​

Field KeyDB ColumnDescription
topic_ididUnique topic identifier
topic_nametopic_nameTopic name
parent_categorytaxonomy_typeParent category (41 types, e.g., "Business Technology")
taxonomy_typeparent_categoryTaxonomy type group (13 groups, e.g., "Technology & Telecom")
subcategorysubcategorySubcategory classification
segment_typesegment_typeB2B / B2C / B2B2C / B2E / B2G
audience_typeaudience_typeAudience type (e.g., "In-Market Buyers")
intent_typeintent_typePrimary intent type
keywordskeywordsClassification keywords (semicolon-separated)
iab_codeiab_codeIAB content taxonomy code
engine_versionengine_versionClassification engine version
taxonomy_hashtaxonomy_hashTaxonomy definition hash for staleness detection
sourcesourceTopic origin (e.g., "classify", "import", "sync")
external_idexternal_idExternal system identifier
performance_scoreperformance_scorePerformance metric
created_atcreated_atCreation timestamp
updated_atupdated_atLast update timestamp
DB-to-TS Field Name Swap

Note that the export field parent_category reads from DB column taxonomy_type, and the export field taxonomy_type reads from DB column parent_category. The export route handles this swap in its field extractor map, so the exported CSV has the correct TS-perspective column names.

Platform Name Fields​

Field KeyDB ColumnDescription
segment_name_tradedesksegment_name_tradedeskTrade Desk segment name
segment_name_liverampsegment_name_liverampLiveRamp segment name
segment_name_internalsegment_name_internalInternal segment name

Platform Description Fields​

Field KeyDB ColumnDescription
segment_desc_liverampsegment_desc_liverampLiveRamp segment description
segment_desc_tradedesksegment_desc_tradedeskTrade Desk segment description
internal_descriptioninternal_descriptionInternal description

Classification Layer Fields​

These fields are extracted from the classification JSONB column:

Field KeySource PathDescription
sensitivityclassification.layer5_sensitivitySensitivity classification
buyer_journeyclassification.layer6_buyer_journey.labelBuyer journey stage label
intent_scoreclassification.layer7_composite.scoreComposite intent score (0--100)
intensityclassification.layer2_intensityIntensity level label
awarenessclassification.layer3_awarenessAwareness stage label
journey_stageclassification.layer3_awarenessJourney stage (maps to awareness)
funnel_stageclassification.layer7_composite.funnel_stageFunnel stage
tip

The classification layer fields (sensitivity, buyer_journey, intent_score, etc.) are stored in a JSONB column. When any of these fields are requested, the export includes the full classification column in the SQL query. For very large exports, this increases memory usage -- consider omitting these fields if you only need basic topic data.

Query Optimization​

The export route uses intelligent query optimization to handle large datasets:

Minimal SELECT List​

Rather than selecting all columns with SELECT *, the export builds a minimal column list based on the requested fields. This is critical for avoiding Neon's 64 MB response limit:

  • The classification JSONB column (~2 KB per row) is only included when classification layer fields are requested
  • Each requested field is mapped to its source DB column via FIELD_TO_COLUMN
  • The id and created_at columns are always included (for ordering)

Row Limit​

The export query includes a LIMIT 50000 to prevent runaway queries. If you need more than 50,000 topics, use filter parameters to export in batches by parent category or segment type.

Filters Applied at Query Level​

All filters (search, parentCategory, segmentType) are applied in the SQL WHERE clause, not post-query. Combined with the standard exclusions (merged_into IS NULL, archived_at IS NULL), this ensures only relevant data is fetched.

CSV Format​

Escaping​

The export uses standard CSV escaping:

  • Fields containing commas, double quotes, or newlines are wrapped in double quotes
  • Double quotes within fields are escaped as "" (doubled)
  • The escapeCSV() function handles all edge cases

Keywords​

The keywords field (stored as a PostgreSQL text array) is exported as a semicolon-separated string:

"Cloud Computing; SaaS; Enterprise; CRM"

Timestamps​

Date fields (created_at, updated_at) are exported as ISO 8601 strings directly from the database.

Step-by-Step Export Procedure​

Exporting All Topics​

  1. Navigate to the admin export interface (or use the API directly)
  2. Select the fields you want to include
  3. Leave filters empty for a full export
  4. Download the CSV
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.example.com/api/admin/topics/export?fields=topic_id,topic_name,parent_category,taxonomy_type,subcategory,segment_type,segment_name_tradedesk,segment_name_liveramp,created_at"

Exporting a Filtered Subset​

# Only B2B topics in Business Technology
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.example.com/api/admin/topics/export?fields=topic_name,segment_type,segment_name_tradedesk&parentCategory=Business%20Technology&segmentType=B2B"

Exporting with Classification Layers​

# Include 7-layer classification details
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.example.com/api/admin/topics/export?fields=topic_name,parent_category,segment_type,sensitivity,buyer_journey,intent_score,intensity,awareness,funnel_stage"
warning

Requesting classification layer fields significantly increases the response size because the entire classification JSONB must be fetched for each row. For catalogs with 20,000+ topics, consider splitting the export into multiple requests filtered by parent category.

Error Handling​

ErrorCauseResolution
Missing 'fields' query parameterNo fields param in URLAdd comma-separated field keys
No valid fields specifiedEmpty fields listSpecify at least one valid field key
Unknown fields: xyzInvalid field keyCheck the available fields table above
500 Internal Server ErrorQuery timeout or memory limitReduce field count (especially remove classification layers) or add filters

Admin vs Org Export​

The admin export route (/api/admin/topics/export) exports global topics from the topics table. This is distinct from org-level topic management:

AspectAdmin ExportOrg Library
ScopeAll global topicsOnly topics adopted by an org
AuthenticationSuper admin onlyOrg member with topics:read
Tabletopicsorg_topics (with JOIN to topics)
Use caseCatalog auditing, platform onboardingOrg-specific segment lists
tip

For org-specific exports, use the org library's export functionality. The admin export is for system-wide catalog management and should be used for tasks like platform onboarding (sending the full catalog to Trade Desk or LiveRamp) or compliance audits.

Next Steps​