Skip to content

First party terms

Searches people really ran — from your Google Ads search-terms report or a connected source — offered as prompts to track. Beta: these shapes may change; see the changelog.

GET /audits/{auditId}/first-party-terms

One page of terms, best performers first, with counts per source.

Terminal window
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/first-party-terms?source=SOURCE&q=Q" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
sourcequeryno“ads_csv” | “ads_api” | “gsc”Only terms from this source. An unknown value lists every source.
qquerynostringOnly terms containing this text. Cut to 200 characters.
pagequerynointegerPage number, from 1. Anything else is page 1.
pageSizequerynointegerPage size. Defaults to and is capped at 50.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.itemsobject[]yes
data.items[].idstringyes
data.items[].source“ads_csv” | “ads_api” | “gsc”yes
data.items[].termstringyes
data.items[].questionstring | nullyesThe term written as a question; null until written, or when none was asked for.
data.items[].rewritingbooleanyesA rewrite was asked for and has not landed yet.
data.items[].clicksinteger | null
data.items[].impressionsinteger | null
data.items[].conversionsnumber | null
data.items[].costMicrosinteger | nullSpend in millionths of currency.
data.items[].currencystring | null
data.items[].promptIdstring | nullyesThe live prompt made from this term, if any.
data.totalintegeryesTerms matching the filters, across all pages.
data.bySourceobject[]yesMatching terms per source, ignoring the source filter.
data.bySource[].source“ads_csv” | “ads_api” | “gsc”yes
data.bySource[].countintegeryes
data.refreshingbooleanyesA connected source is being re-pulled; read again shortly.
{
"success": true,
"data": {
"items": [
{
"id": "80e3d716-4612-439c-a35f-aa72445b6c3e",
"source": "ads_csv",
"term": "widget software for agencies",
"question": null,
"rewriting": false,
"clicks": 12,
"impressions": 340,
"conversions": 2,
"costMicros": 45200000,
"currency": "USD",
"promptId": null
}
],
"total": 1,
"bySource": [
{
"source": "ads_csv",
"count": 1
}
],
"refreshing": false
}
}

POST /audits/{auditId}/first-party-terms/{termId}/dismiss

Hides a term from the list. A connected source’s later pulls keep it hidden, but a new Ads report upload replaces every term never made a prompt, so a dismissed term in it comes back.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/first-party-terms/TERM_ID/dismiss" \
-H "Authorization: Bearer $BEKET_API_KEY"
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
termIdpathyesstringThe term’s id.

POST /audits/{auditId}/first-party-terms/import

Stores the terms from a Google Ads search-terms CSV. It replaces the previous upload’s terms that were never made into prompts; the others stay. Terms that look like personal data (an email, phone number or street address) are dropped and counted.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/first-party-terms/import" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"<content>","rewrite":true}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
contentstringyesThe Google Ads search-terms report, exported as CSV, as text.
rewritebooleanyesAlso write each term as a question, in the background. The list shows rewriting until it lands.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.foundintegeryesData rows read — one per term per campaign or ad group, so above upserted.
data.skippedRowsintegeryesRows with no search term.
data.hasConversionsbooleanyesThe file had a Conversions column; without it terms rank by clicks.
data.upsertedintegeryesDistinct terms stored.
data.withConversionsintegeryes
data.skippedPiiintegeryes
data.skippedInvalidintegeryesTerms no prompt could be: too short, too long, or blank.
{
"success": true,
"data": {
"found": 1,
"skippedRows": 0,
"hasConversions": true,
"upserted": 1,
"withConversions": 1,
"skippedPii": 0,
"skippedInvalid": 0
}
}

POST /audits/{auditId}/first-party-terms/select

Adds up to 100 terms as prompts, using each one’s question when it has one. Terms that repeat each other or an existing prompt are skipped; prompts past the plan’s capacity are added unselected.

Terminal window
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/first-party-terms/select" \
-H "Authorization: Bearer $BEKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"termIds":[]}'
NameInRequiredTypeDescription
auditIdpathyesstringThe audit’s id.
FieldTypeRequiredDescription
termIdsstring[]yesTerm ids from the term list. A term that is not one of this audit’s is a 404.
FieldTypeRequiredDescription
successbooleanyes
dataobjectyes
data.promptsPrompt[]yes
data.maxQueriesinteger | nullyes
data.addedintegeryesPrompts inserted.
data.skippedDuplicatesintegeryes
data.overCapintegeryesInserted prompts left unselected past the plan’s capacity.
{
"success": true,
"data": {
"prompts": [
{
"id": "0f4d5c46-b98e-4854-af39-2f6c7a32c038",
"text": "best widget software for small teams",
"selected": true,
"angleId": "CUSTOM",
"language": null,
"promptType": "UNBRANDED",
"topicId": null,
"region": null,
"querySubject": "OFFERING",
"funnelStage": null,
"angleLabel": "Custom",
"isCustom": true,
"branded": false
},
{
"id": "a3985077-683f-4df2-9b51-6474baab91e2",
"text": "how do I choose a widget vendor",
"selected": true,
"angleId": "CUSTOM",
"language": null,
"promptType": "UNBRANDED",
"topicId": null,
"region": null,
"querySubject": "OFFERING",
"funnelStage": null,
"angleLabel": "Custom",
"isCustom": true,
"branded": false
}
],
"maxQueries": 25,
"added": 1,
"skippedDuplicates": 0,
"overCap": 0
}
}
FieldTypeRequiredDescription
idstringyes
textstringyes
selectedbooleanyesWhether the next run asks this prompt.
angleIdstringyes
angleLabelstringyes
querySubjectstring
funnelStagestring | null
isCustombooleanyesWritten by a person rather than generated.
brandedbooleanyesWhether the prompt names the brand.
languagestring | null
promptType“UNBRANDED” | “BRANDED” | “RECALL”yes
topicIdstring | null
regionstring | null
firstPartyobject
firstParty.sourcestringyes
firstParty.termstringyes
minedobject
mined.questionIdstringyes
mined.seedKeywordstring
mined.sourceKindstring
mined.seedSourcestring
mined.firstSeenAtstring
mined.answerDomainsstring[]yes