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.
List first-party terms
Section titled “List first-party terms”GET /audits/{auditId}/first-party-terms
One page of terms, best performers first, with counts per source.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/first-party-terms?source=SOURCE&q=Q" \ -H "Authorization: Bearer $BEKET_API_KEY"Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
source | query | no | “ads_csv” | “ads_api” | “gsc” | Only terms from this source. An unknown value lists every source. |
q | query | no | string | Only terms containing this text. Cut to 200 characters. |
page | query | no | integer | Page number, from 1. Anything else is page 1. |
pageSize | query | no | integer | Page size. Defaults to and is capped at 50. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.items | object[] | yes | |
data.items[].id | string | yes | |
data.items[].source | “ads_csv” | “ads_api” | “gsc” | yes | |
data.items[].term | string | yes | |
data.items[].question | string | null | yes | The term written as a question; null until written, or when none was asked for. |
data.items[].rewriting | boolean | yes | A rewrite was asked for and has not landed yet. |
data.items[].clicks | integer | null | ||
data.items[].impressions | integer | null | ||
data.items[].conversions | number | null | ||
data.items[].costMicros | integer | null | Spend in millionths of currency. | |
data.items[].currency | string | null | ||
data.items[].promptId | string | null | yes | The live prompt made from this term, if any. |
data.total | integer | yes | Terms matching the filters, across all pages. |
data.bySource | object[] | yes | Matching terms per source, ignoring the source filter. |
data.bySource[].source | “ads_csv” | “ads_api” | “gsc” | yes | |
data.bySource[].count | integer | yes | |
data.refreshing | boolean | yes | A connected source is being re-pulled; read again shortly. |
Example response (200)
Section titled “Example response (200)”{ "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 }}Dismiss a term
Section titled “Dismiss a term”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.
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/first-party-terms/TERM_ID/dismiss" \ -H "Authorization: Bearer $BEKET_API_KEY"Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
termId | path | yes | string | The term’s id. |
Import a Google Ads search-terms report
Section titled “Import a Google Ads search-terms report”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.
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}'Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
content | string | yes | The Google Ads search-terms report, exported as CSV, as text. |
rewrite | boolean | yes | Also write each term as a question, in the background. The list shows rewriting until it lands. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.found | integer | yes | Data rows read — one per term per campaign or ad group, so above upserted. |
data.skippedRows | integer | yes | Rows with no search term. |
data.hasConversions | boolean | yes | The file had a Conversions column; without it terms rank by clicks. |
data.upserted | integer | yes | Distinct terms stored. |
data.withConversions | integer | yes | |
data.skippedPii | integer | yes | |
data.skippedInvalid | integer | yes | Terms no prompt could be: too short, too long, or blank. |
Example response (201)
Section titled “Example response (201)”{ "success": true, "data": { "found": 1, "skippedRows": 0, "hasConversions": true, "upserted": 1, "withConversions": 1, "skippedPii": 0, "skippedInvalid": 0 }}Turn terms into prompts
Section titled “Turn terms into prompts”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.
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":[]}'Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
termIds | string[] | yes | Term ids from the term list. A term that is not one of this audit’s is a 404. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.prompts | Prompt[] | yes | |
data.maxQueries | integer | null | yes | |
data.added | integer | yes | Prompts inserted. |
data.skippedDuplicates | integer | yes | |
data.overCap | integer | yes | Inserted prompts left unselected past the plan’s capacity. |
Example response (201)
Section titled “Example response (201)”{ "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 }}Schemas
Section titled “Schemas”Prompt
Section titled “Prompt”| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
text | string | yes | |
selected | boolean | yes | Whether the next run asks this prompt. |
angleId | string | yes | |
angleLabel | string | yes | |
querySubject | string | ||
funnelStage | string | null | ||
isCustom | boolean | yes | Written by a person rather than generated. |
branded | boolean | yes | Whether the prompt names the brand. |
language | string | null | ||
promptType | “UNBRANDED” | “BRANDED” | “RECALL” | yes | |
topicId | string | null | ||
region | string | null | ||
firstParty | object | ||
firstParty.source | string | yes | |
firstParty.term | string | yes | |
mined | object | ||
mined.questionId | string | yes | |
mined.seedKeyword | string | ||
mined.sourceKind | string | ||
mined.seedSource | string | ||
mined.firstSeenAt | string | ||
mined.answerDomains | string[] | yes |