> ## Documentation Index > Fetch the complete documentation index at: https://geoptie.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Ad creatives > The ads themselves: headline, text, image and landing link, with how often each appeared, most first. Narrow to one advertiser or prompt. ## OpenAPI ````yaml /openapi.json get /v1/brands/{id}/ads/creatives openapi: 3.1.0 info: title: Geoptie API version: 1.0.0 summary: Read and manage your AI-search visibility data. description: >- Everything the Geoptie dashboard can do, over HTTP. **Authentication.** Every request needs an API key as `Authorization: Bearer `, and the workspace must have an active or trialing subscription. Keys are created in the dashboard and scoped to one workspace. **Pagination** is cursor-based. Pass `next_cursor` back as `cursor` and stop when `has_more` is false. The cursor is opaque; do not parse it. **Dates** are ISO 8601. `from` is inclusive, `to` is exclusive. Omitting both gives the last 30 days. **Limits** exist to stop runaway clients, not to meter you: there is no monthly request ceiling. Every response carries `X-RateLimit-*`, and endpoints that spend money carry `X-Endpoint-*` as well. A 429 names which limit was hit. **Errors** always carry a stable `error.code`. Match on that, never on the message text. A verb that an endpoint does not declare returns 405 `method_not_allowed`. contact: name: Geoptie support email: support@geoptie.com servers: - url: https://api.geoptie.com description: Production security: - bearerAuth: [] tags: - name: Brands description: The brands you track. A brand owns its prompts, engines and country. - name: Prompts description: >- The questions you track across engines, the answers they returned, and the brands named in those answers. Plan limits apply to how many you can track. - name: Visibility description: How often and how prominently a brand appears in engine answers. - name: Citations description: Which pages engines cited when answering your prompts. - name: Ads description: >- The sponsored ads ChatGPT shows in answers to your prompts: who advertises, the ads themselves, and which prompts and answers carry them. - name: Competitors description: >- Your share of voice against the other brands appearing in your prompts, the tracked set that share of voice is computed over, and per-competitor trends. - name: Topics description: Optional grouping for prompts within a brand. - name: Recommendations description: Generated actions for improving visibility, and their lifecycle. - name: Audit reports description: On-demand GEO analysis of a single URL. - name: Content generations description: >- New articles, written from the pages engines already cite for the prompts you track. Research a brief first, then write the article from it. - name: Content optimizations description: >- Pages you already have, scored for AI search with the specific changes that would raise the score. paths: /v1/brands/{id}/ads/creatives: get: tags: - Ads summary: Ad creatives description: >- The ads themselves: headline, text, image and landing link, with how often each appeared, most first. Narrow to one advertiser or prompt. operationId: listAdCreatives parameters: - name: id in: path required: true description: Brand id. schema: type: string format: uuid example: b7c1e5a0-4f3d-42a8-9c6b-1e8d5a2f7043 - name: engine in: query required: false description: Ads are tracked on ChatGPT only, so this is `chatgpt` or omitted. schema: type: string enum: - chatgpt - name: from in: query required: false description: Inclusive start date. Defaults to 30 days before `to`. schema: type: string format: date example: '2026-11-08' - name: to in: query required: false description: Exclusive end date. Defaults to tomorrow. schema: type: string format: date example: '2026-11-11' - name: country in: query required: false description: >- Restrict to one market: a two-letter code, or `global` for checks run without a market. The summary's `markets` lists the values this brand has. schema: type: string example: US - name: topic_id in: query required: false explode: true description: Repeatable. Restrict to prompts in these topics. schema: type: array items: type: string format: uuid - name: branding in: query required: false description: >- Restrict to prompts that name this brand (`branded`) or to those that do not (`non_branded`). Omit, or `all`, for every prompt. schema: type: string enum: - all - branded - non_branded default: all - name: advertiser_key in: query required: false description: >- Restrict to one advertiser, by the `advertiser_key` other ads endpoints return. schema: type: string example: globex.com - name: prompt_id in: query required: false description: >- Restrict to one prompt this brand tracks. Cannot be combined with `topic_id`. schema: type: string format: uuid - name: search in: query required: false description: Match headline, body or advertiser name. schema: type: string maxLength: 200 - name: limit in: query required: false description: Rows per page. Max 500. schema: type: integer default: 100 maximum: 500 example: 100 - name: cursor in: query required: false description: >- Opaque cursor from the previous page's `next_cursor`. Use it with the same other parameters. schema: type: string responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/AdCreative' has_more: type: boolean next_cursor: type: - string - 'null' description: Pass back as `cursor`. Null when there are no more rows. total_count: type: integer description: How many rows match in total, across all pages. example: data: - creative_id: 3f2a9c1e7b4d4e0f9a8b6c5d4e3f2a1b advertiser_key: globex.com advertiser_name: Globex headline: Project planning your team will actually use body: >- Plan sprints, track work and ship on time. Free for teams up to 10. image_url: https://images.openai.com/static-rsc-5/globex-planning.png landing_url: >- https://globex.com/lp/project-planning?utm_source=chatgpt&utm_medium=paid&utm_campaign=pm_nonbrand appearances: 31 prompts: 12 first_seen: '2026-10-15' last_seen: '2026-11-13' is_competitor: true is_own: false has_more: true next_cursor: WyJvIiwxXQ total_count: 96 '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '402': $ref: '#/components/responses/E402' '403': $ref: '#/components/responses/E403' '404': $ref: '#/components/responses/E404' '429': $ref: '#/components/responses/E429' '500': $ref: '#/components/responses/E500' components: schemas: AdCreative: type: object properties: creative_id: type: string description: 'Stable id of this ad: same advertiser, headline and body.' advertiser_key: $ref: '#/components/schemas/AdvertiserKey' advertiser_name: type: - string - 'null' headline: type: - string - 'null' body: type: - string - 'null' image_url: type: - string - 'null' landing_url: type: - string - 'null' description: Where the ad links, with its campaign parameters. appearances: type: integer description: Answers it appeared in. prompts: type: integer first_seen: type: string format: date last_seen: type: string format: date is_competitor: type: boolean is_own: type: boolean AdvertiserKey: type: string description: >- Stable advertiser id. Usually the advertiser's domain (`globex.com`); `name:` plus a folded name when the ad links through a redirect or a marketplace. Treat it as opaque and pass it back unchanged, percent-encoded in a path. example: globex.com Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine code. Match on this, not the message. message: type: string example: error: code: not_found message: No such brand in this workspace. responses: E400: description: >- Bad request. `missing_parameter`, `invalid_parameter`, `invalid_request`, `invalid_engine` or `invalid_date`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_date message: Dates must be ISO 8601, e.g. 2026-08-01. E401: description: '`missing_api_key` or `invalid_api_key`.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: This API key is not valid or has been revoked. E402: description: >- `subscription_required`. The workspace has no active or trialing subscription. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: subscription_required message: >- This workspace does not have an active subscription. API access requires an active or trialing plan. E403: description: '`plan_not_eligible` or `forbidden`.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: This workspace cannot perform that action. E404: description: '`not_found`. Also returned for records belonging to another workspace.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: No such brand in this workspace. E429: description: >- `rate_limited`, `quota_exceeded`, `endpoint_rate_limited` or `concurrency_limited`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Rate limit of 120 requests per minute exceeded. E500: description: '`internal_error`. Quote the `X-Request-Id` when reporting it.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: Something went wrong on our side. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key, e.g. `Authorization: Bearer gp_live_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.