# ────────────────────────────────────────────────────────────────── # AUTOGENERATED — do not edit by hand. # # Source of truth: AIsa-team/docs (openapi/*.json). # Producer: scripts/consolidate_openapi.py # Sync workflow: .github/workflows/sync-openapi.yml # # To change this file, edit the per-API spec under # https://github.com/AIsa-team/docs/tree/main/openapi # and merge to main. The sync workflow regenerates and commits # the consolidated spec here, then notifies Tool Router. # # Direct edits here will be overwritten on the next sync. # ────────────────────────────────────────────────────────────────── openapi: 3.1.0 info: title: AIsa API description: Capability layer for the agentic economy. Models, skills, payments, and deployment — everything AI agents need to reason, act, and transact. This spec consolidates all AIsa API endpoints into a single reference. version: 1.0.0 contact: name: AIsa url: https://aisa.one email: developer@aisa.one license: name: MIT url: https://opensource.org/licenses/MIT termsOfService: https://aisa.one/tos servers: - url: https://api.aisa.one/apis/v1 description: AIsa Data APIs (Bearer auth — register at https://aisa.one) - url: https://api.aisa.one/apis/v2 description: 'AIsa Data APIs (x402 pay-per-call) — same surface as /apis/v1, mirrored. No registration; receive HTTP 402 challenge, settle with stablecoin micropayment. Spec: https://www.x402.org. Open-source gateway implementation: https://github.com/AIsa-team/aisa-proxy' x-implementation: https://github.com/AIsa-team/aisa-proxy - url: https://api.aisa.one/v1 description: AIsa LLM Inference (OpenAI-compatible, Bearer auth) - url: https://api.aisa.one/v1beta description: AIsa Gemini-compatible GenerateContent (Bearer auth) security: - BearerAuth: [] tags: - name: AI Models description: Access 50+ LLMs via OpenAI-compatible, Anthropic, and Google Gemini interfaces - name: Account & Usage description: Programmatic account balance and usage endpoints for cost monitoring and alerting - name: Agent Email description: AI-agent email accounts, inboxes, threads, drafts, and message send/reply via AgentMail.to - name: Crypto Data description: Cryptocurrency prices, markets, and exchange data via CoinGecko - name: Financial Data description: Stock prices, financials, analyst estimates, SEC filings, and macro data - name: Image Generation description: Generate and edit images using AI models - name: Instagram description: Read public Instagram data — profiles, posts, reels, highlights, comments, and Google-backed search - name: Market Intelligence description: '' - name: Other description: '' - name: Pinterest description: Read public Pinterest data — search pins, fetch pin details, and browse boards - name: Prediction Markets description: Query prediction markets — Polymarket, Kalshi, and matching markets - name: Reddit description: Read public Reddit data — search posts, browse subreddits, and fetch comments - name: SEO & Search Data description: SERP, keywords, backlinks, domain and competitor analysis — DataForSEO, Semrush, and Ahrefs - name: Sales Intelligence description: B2B contact and company enrichment, search, and outreach via Apollo.io - name: Scholar Search description: Search academic papers and research - name: Twitter / X description: Read, search, and interact with Twitter/X — profiles, tweets, communities, trends, and engagement - name: WaveInflu description: '' - name: Web & News Search description: Search the web and news — Tavily search, Oxylabs AI-answer-engine queries, and model-grounded search - name: YouTube Search description: Search YouTube videos paths: /credits/balance: get: summary: Account Balance description: Return the current account credit balance. Accepts either an API key or an OAuth access token. No parameters. operationId: accountCreditsBalance parameters: [] responses: '200': description: Current balance snapshot. content: application/json: example: currency: USD account_balance_micros_usd: 1855591 available_balance_micros_usd: 1855591 api_key: unlimited: true remaining_micros_usd: 0 used_micros_usd: 0 as_of: '2026-08-27T10:36:29Z' schema: type: object properties: currency: type: string description: ISO currency code (always USD). account_balance_micros_usd: type: integer format: int64 description: Total account balance in micro-USD. available_balance_micros_usd: type: integer format: int64 description: Spendable balance in micro-USD (total minus any holds/reserves). api_key: type: object description: Per-key limit view for the calling API key (absent for OAuth callers). properties: unlimited: type: boolean description: True when the key has no per-key spend cap. remaining_micros_usd: type: integer format: int64 description: Remaining per-key allowance in micro-USD (0 when unlimited). used_micros_usd: type: integer format: int64 description: Amount spent by this key in micro-USD. as_of: type: string format: date-time description: Snapshot timestamp (RFC 3339, UTC). tags: - Account & Usage servers: - url: https://api.aisa.one/v1 /usage: get: summary: Account Usage description: Return request and spend usage over a time window, split into daily buckets. Accepts either an API key or an OAuth access token. The scope reflects the credential used (e.g. a single key vs the whole account). operationId: accountUsage parameters: - name: start_time in: query required: true description: Window start as a Unix timestamp in seconds. schema: type: integer format: int64 - name: end_time in: query required: false description: Window end as a Unix timestamp in seconds. Defaults to the current time. schema: type: integer format: int64 responses: '200': description: Usage totals and per-day buckets over the window. content: application/json: example: scope: key currency: USD start_time: 1785513600 end_time: 1787760000 bucket_width: 1d totals: requests: 1162 failed_requests: 401 input_tokens: 206393 output_tokens: 5031 cache_read_tokens: 0 cache_write_tokens: 0 usage_value_micros_usd: 128398109 charged_micros_usd: 128398109 buckets: - start_time: 1785513600 end_time: 1785600000 requests: 42 failed_requests: 3 input_tokens: 8123 output_tokens: 210 cache_read_tokens: 0 cache_write_tokens: 0 usage_value_micros_usd: 5123400 charged_micros_usd: 5123400 schema: type: object properties: scope: type: string description: Aggregation scope implied by the credential (e.g. key or account). currency: type: string description: ISO currency code (always USD). start_time: type: integer format: int64 description: Echoed window start (Unix seconds). end_time: type: integer format: int64 description: Echoed window end (Unix seconds). bucket_width: type: string description: Bucket granularity (e.g. 1d). totals: type: object description: Aggregate totals across the whole window. properties: requests: type: integer format: int64 failed_requests: type: integer format: int64 input_tokens: type: integer format: int64 output_tokens: type: integer format: int64 cache_read_tokens: type: integer format: int64 cache_write_tokens: type: integer format: int64 usage_value_micros_usd: type: integer format: int64 description: Metered value of usage in micro-USD. charged_micros_usd: type: integer format: int64 description: Amount actually charged in micro-USD. buckets: type: array description: Per-bucket usage, ordered by time. items: type: object properties: start_time: type: integer format: int64 end_time: type: integer format: int64 requests: type: integer format: int64 failed_requests: type: integer format: int64 input_tokens: type: integer format: int64 output_tokens: type: integer format: int64 cache_read_tokens: type: integer format: int64 cache_write_tokens: type: integer format: int64 usage_value_micros_usd: type: integer format: int64 charged_micros_usd: type: integer format: int64 '400': description: Invalid or missing time window (e.g. start_time not a positive Unix timestamp). content: application/json: example: error: start_time must be a positive Unix timestamp tags: - Account & Usage servers: - url: https://api.aisa.one/v1 /agentmail/threads/{thread_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_thread summary: Get Any Thread description: 'Fetches one thread by id without naming an inbox: `thread_id`, `inbox_id`, `labels`, `timestamp`, `received_timestamp`, `sent_timestamp`, `senders`, `recipients`, `subject`, `preview`, attachments and messages. Because no inbox is named, this resolves against the whole account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so a thread id that is not yours still resolves — check the returned `inbox_id`. The scoped twin is `get_agentmail_inbox_thread`.' tags: - Agent Email parameters: - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_Thread' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/threads/{thread_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: patch_agentmail_thread summary: Update Any Thread Labels description: 'Adds or removes labels on a thread addressed by id alone, returning `thread_id` and the resulting `labels`. No inbox is named, so it resolves account-wide. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller. The scoped twin is `patch_agentmail_inbox_thread`.' tags: - Agent Email parameters: - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_UpdateThreadResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '422': description: Error response with status 422 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_threads_UpdateThreadRequest' x-x402: path: /apis/v2/agentmail/threads/{thread_id} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_thread summary: Delete Any Thread description: Permanently deletes a thread addressed by id alone, and every message in it. Returns no body. **This cannot be undone, deletes more than one message, and names no inbox** — Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so it can destroy a conversation belonging to another caller. Read it first with `get_agentmail_thread`; the scoped twin is `delete_agentmail_inbox_thread`. tags: - Agent Email parameters: - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: permanent in: query description: If true, permanently delete the thread instead of moving to trash. required: false schema: type: boolean - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/threads/{thread_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/drafts/{draft_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_draft summary: Get Draft description: 'Fetches one unsent draft in full: `draft_id`, `inbox_id`, `client_id`, `labels`, `reply_to`, `to`, `cc`, `bcc`, `subject`, `preview`, `text`, `html`, `attachments`, `in_reply_to` and `references`. Edit it with `patch_agentmail_inbox_draft`, send it with `post_agentmail_inbox_draft_send`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_drafts_Draft' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts/{draft_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: patch_agentmail_inbox_draft summary: Update Draft description: 'Rewrites an unsent draft''s recipients, subject, body or attachments and returns the full draft after the change. Still sends nothing — `post_agentmail_inbox_draft_send` does that. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_drafts_Draft' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_drafts_UpdateDraftRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts/{draft_id} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_inbox_draft summary: Delete Draft description: Permanently deletes an unsent draft. Returns no body. Nothing was ever sent, so this is the least destructive delete in this API — but it cannot be undone and Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created. Read it first with `get_agentmail_inbox_draft` if unsure. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts/{draft_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox summary: Get Inbox description: Fetches one inbox by `inbox_id`. Returns `inbox_id`, `email`, `display_name`, `client_id`, `pod_id`, `metadata`, `created_at` and `updated_at` — settings only, no mail. For the messages in it use `get_agentmail_inbox_messages`, for conversations `get_agentmail_inbox_threads`. Discover ids with `get_agentmail_inboxes`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_inboxes_Inbox' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: patch_agentmail_inbox summary: Update Inbox description: 'Updates one inbox''s `display_name` and `metadata`; the address itself cannot change. Returns the full inbox after the update. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller. To read without changing anything use `get_agentmail_inbox`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_inboxes_Inbox' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: description: Expects an object; provide at least one of `display_name` or `metadata`. content: application/json: schema: $ref: '#/components/schemas/type_inboxes_UpdateInboxRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_inbox summary: Delete Inbox description: Permanently deletes an inbox and the mail in it. Returns no body. **This cannot be undone, and the inbox may not be yours** — Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so confirm ownership from `get_agentmail_inbox` before calling. To stop using an inbox without destroying it, simply leave it alone. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/lists/{direction}/{type}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_list_entries summary: List Account List Entries description: Lists the account-wide allow or block entries that apply to every inbox. `direction` selects inbound or outbound and `type` the list kind. Returns `count`, `limit`, `next_page_token` and `entries`; page with `next_page_token`. Each entry carries `entry`, `entry_type`, `reason`, `direction`, `list_type`, `created_at` and `read_only`. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_list_entries` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_lists_ListListEntriesResponse' x-x402: path: /apis/v2/agentmail/lists/{direction}/{type} source: https://github.com/AIsa-team/aisa-proxy post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_list_entry summary: Create Account List Entry description: Adds one address or domain to an **account-wide** allow or block list and returns the created entry. 🔴 This is a standing rule that changes mail handling for **every inbox in the account, including other callers'** — the inbox-scoped `post_agentmail_inbox_list_entry` affects only one inbox and is almost always the one you want. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created. tags: - Agent Email parameters: - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_lists_ListEntry' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_lists_CreateListEntryRequest' x-x402: path: /apis/v2/agentmail/lists/{direction}/{type} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/{message_id}/reply-all: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_message_reply_all summary: Reply All To Message description: Replies to one message and **every other recipient on it**, returning `message_id` and `thread_id`. 🔴 **This sends real email to everyone in the thread and it cannot be recalled.** Use `post_agentmail_inbox_message_reply` when only the sender should receive the answer — that is the safer default and the two differ only in recipients. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '403': description: Error response with status 403 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_messages_ReplyAllMessageRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id}/reply-all source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/send: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_message_send summary: Send Message description: Sends a new email from one inbox and returns `message_id` and `thread_id`. Takes `to`, `cc`, `bcc`, `subject`, `text`, `html`, `labels` and `attachments`. 🔴 **This sends real email and it cannot be recalled.** Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so the sending address may not be one you created — check `get_agentmail_inbox` first. To answer an existing message use `post_agentmail_inbox_message_reply`; to write without sending, `post_agentmail_inbox_draft`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '403': description: Error response with status 403 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/send source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/threads/{thread_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_thread summary: Get Thread description: 'Fetches one thread with its full message list: `thread_id`, `inbox_id`, `labels`, `timestamp`, `received_timestamp`, `sent_timestamp`, `senders`, `recipients`, `subject`, `preview`, attachments and the messages themselves. For a single message use `get_agentmail_inbox_message`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_Thread' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/threads/{thread_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: patch_agentmail_inbox_thread summary: Update Thread Labels description: 'Adds or removes labels on a whole thread and returns `thread_id` with the resulting `labels`. Applies to every message in the thread at once; the per-message twin is `patch_agentmail_inbox_message`. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_UpdateThreadResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '422': description: Error response with status 422 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_threads_UpdateThreadRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/threads/{thread_id} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_inbox_thread summary: Delete Thread description: Permanently deletes a thread and every message in it. Returns no body. **This cannot be undone and it removes more than one message** — Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so read the thread with `get_agentmail_inbox_thread` first. To hide it instead, relabel with `patch_agentmail_inbox_thread`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: permanent in: query description: If true, permanently delete the thread instead of moving to trash. required: false schema: type: boolean - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/threads/{thread_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/threads: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_threads summary: List All Threads description: Lists conversation threads across **every inbox in the account**. Returns `count`, `limit`, `next_page_token` and `threads`; page with `next_page_token`. Each thread carries `thread_id`, `inbox_id`, `labels`, `timestamp`, `senders`, `recipients`, `subject`, `preview`, `message_count` and `last_message_id`. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_threads` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: labels in: query required: false schema: $ref: '#/components/schemas/type__Labels' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: include_spam in: query required: false schema: $ref: '#/components/schemas/type__IncludeSpam' - name: include_blocked in: query required: false schema: $ref: '#/components/schemas/type__IncludeBlocked' - name: include_unauthenticated in: query required: false schema: $ref: '#/components/schemas/type__IncludeUnauthenticated' - name: include_trash in: query required: false schema: $ref: '#/components/schemas/type__IncludeTrash' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_ListThreadsResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/threads source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/threads: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_threads summary: List Threads description: Lists conversation threads in one inbox, newest first. Returns `count`, `limit`, `next_page_token` and `threads`; page with `next_page_token`. Each thread carries `thread_id`, `labels`, `timestamp`, `senders`, `recipients`, `subject`, `preview`, `message_count`, `last_message_id`, `size` and attachment metadata. Threads group messages; for the individual messages use `get_agentmail_inbox_messages`. To query rather than page, `get_agentmail_inbox_threads_search`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: labels in: query required: false schema: $ref: '#/components/schemas/type__Labels' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: include_spam in: query required: false schema: $ref: '#/components/schemas/type__IncludeSpam' - name: include_blocked in: query required: false schema: $ref: '#/components/schemas/type__IncludeBlocked' - name: include_unauthenticated in: query required: false schema: $ref: '#/components/schemas/type__IncludeUnauthenticated' - name: include_trash in: query required: false schema: $ref: '#/components/schemas/type__IncludeTrash' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_ListThreadsResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/threads source: https://github.com/AIsa-team/aisa-proxy /agentmail/drafts/{draft_id}/attachments/{attachment_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_draft_attachment summary: Get Any Draft Attachment description: Fetches metadata for one attachment on a draft addressed by id alone. Returns `attachment_id`, `filename`, `size`, `content_type`, `content_disposition`, `content_id` and a short-lived `download_url` with `expires_at`. The bytes are not inlined — fetch `download_url` before it expires. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_draft_attachment` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: attachment_id in: path required: true schema: $ref: '#/components/schemas/type_attachments_AttachmentId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_attachments_AttachmentResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/drafts/{draft_id}/attachments/{attachment_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/events: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_events summary: List Inbox Events description: Lists delivery and activity events for one inbox — the audit trail behind sends and receipts. Returns `count`, `limit`, `next_page_token` and `events`; page with `next_page_token`. Each event carries `event_id`, `event_type`, `message_id`, `label`, `event_at` and `inbox_id`. Use this to find out what happened to a message after `post_agentmail_inbox_message_send` returned, which the send call itself cannot tell you. For aggregate counts rather than individual events use `get_agentmail_inbox_metrics`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_inbox-events_ListInboxEventsResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/events source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/{message_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_message summary: Get Message description: 'Fetches one message in full: `message_id`, `thread_id`, `labels`, `timestamp`, `from`, `reply_to`, `to`, `cc`, `bcc`, `subject`, `preview`, `text`, `html`, `extracted_text` and attachment metadata. For the original MIME source use `get_agentmail_inbox_message_raw`; for an attachment''s download URL, `get_agentmail_inbox_message_attachment`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_Message' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: patch_agentmail_inbox_message summary: Update Message Labels description: 'Adds or removes labels on one message and returns `message_id` with the resulting `labels`. Labels are the only mutable part of a received message. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller. Read the current labels with `get_agentmail_inbox_message`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_UpdateMessageResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_messages_UpdateMessageRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_inbox_message summary: Delete Message description: Permanently deletes one message. Returns no body. **This cannot be undone** and Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so the message may not be yours. To hide a message from a workflow without destroying it, relabel it with `patch_agentmail_inbox_message` instead. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/drafts: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_drafts summary: List Drafts description: Lists unsent drafts in one inbox. Returns `count`, `limit`, `next_page_token` and `drafts`; page with `next_page_token`. Each draft carries `draft_id`, `labels`, `to`, `cc`, `bcc`, `subject`, `preview`, `attachments`, `in_reply_to`, `send_status`, `send_at` and `updated_at`. List items carry `preview` only — `text` and `html` come from `get_agentmail_inbox_draft`. Drafts are not sent until `post_agentmail_inbox_draft_send`. The account-wide view is `get_agentmail_drafts`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: labels in: query required: false schema: $ref: '#/components/schemas/type__Labels' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_drafts_ListDraftsResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts source: https://github.com/AIsa-team/aisa-proxy post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_draft summary: Create Draft description: 'Composes a draft in one inbox without sending it. Takes `to`, `cc`, `bcc`, `subject`, `text`, `html`, `labels`, `attachments`, and `in_reply_to` / `references` to thread it. Returns the full draft including `draft_id`. Nothing leaves the account until you call `post_agentmail_inbox_draft_send`, which makes this the safe way to stage outbound mail for review. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_drafts_Draft' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_drafts_CreateDraftRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts source: https://github.com/AIsa-team/aisa-proxy /agentmail/threads/{thread_id}/attachments/{attachment_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_thread_attachment summary: Get Any Thread Attachment description: Fetches metadata for one attachment in a thread addressed by id alone. Returns `attachment_id`, `filename`, `size`, `content_type`, `content_disposition`, `content_id` and a short-lived `download_url` with `expires_at`. The bytes are not inlined — fetch `download_url` before it expires. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_thread_attachment` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: attachment_id in: path required: true schema: $ref: '#/components/schemas/type_attachments_AttachmentId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_attachments_AttachmentResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/threads/{thread_id}/attachments/{attachment_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_messages summary: List Messages description: Lists messages in one inbox, newest first. Returns `count`, `limit`, `next_page_token` and `messages`; page with `next_page_token`. Each message carries `message_id`, `thread_id`, `labels`, `timestamp`, `from`, `to`, `cc`, `bcc`, `subject` and a `preview`; full bodies come from `get_agentmail_inbox_message`. To search rather than page, use `get_agentmail_inbox_messages_search`; to group by conversation, `get_agentmail_inbox_threads`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: labels in: query required: false schema: $ref: '#/components/schemas/type__Labels' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: include_spam in: query required: false schema: $ref: '#/components/schemas/type__IncludeSpam' - name: include_blocked in: query required: false schema: $ref: '#/components/schemas/type__IncludeBlocked' - name: include_unauthenticated in: query required: false schema: $ref: '#/components/schemas/type__IncludeUnauthenticated' - name: include_trash in: query required: false schema: $ref: '#/components/schemas/type__IncludeTrash' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_ListMessagesResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_list_entry summary: Get Inbox List Entry description: 'Fetches one allow or block entry on an inbox: `entry`, `entry_type`, `reason`, `direction`, `list_type`, `created_at`, `read_only`, `inbox_id`, `pod_id` and `organization_id`. `read_only` marks entries the platform manages, which cannot be deleted. List them all with `get_agentmail_inbox_list_entries`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: entry in: path description: Email address or domain. required: true schema: type: string - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_lists_PodListEntry' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/lists/{direction}/{type}/{entry} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_inbox_list_entry summary: Delete Inbox List Entry description: 'Removes one entry from an inbox''s allow or block list. Returns no body. This changes what the inbox will accept or send from that point on. Entries whose `read_only` is true are platform managed and cannot be removed — check with `get_agentmail_inbox_list_entry` first. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: entry in: path description: Email address or domain. required: true schema: type: string - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/lists/{direction}/{type}/{entry} source: https://github.com/AIsa-team/aisa-proxy /agentmail/metrics: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_metrics summary: Query Account Metrics description: Returns aggregate counters for the whole account as a flat map of counter name to an array of data points. Measured live on 2026-08-24 the keys are `message.received`, `message.received.spam`, `message.received.blocked`, `message.received.unauthenticated`, `message.sent`, `message.delivered`, `message.bounced`, `message.complained`, `message.rejected`, `message.opened` and `domain.verified`, each an empty array on an account with no traffic — an empty array means no activity, not an error. The shape is not pinned in this spec, so read the keys actually returned rather than assuming this list is closed. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_metrics` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: event_types in: query required: false schema: $ref: '#/components/schemas/type_metrics_MetricEventTypes' - name: start in: query required: false schema: $ref: '#/components/schemas/type_metrics_Start' - name: end in: query required: false schema: $ref: '#/components/schemas/type_metrics_End' - name: period in: query required: false schema: $ref: '#/components/schemas/type_metrics_Period' - name: limit in: query required: false schema: $ref: '#/components/schemas/type_metrics_MetricLimit' - name: descending in: query required: false schema: $ref: '#/components/schemas/type_metrics_Descending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_metrics_QueryMetricsResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' x-x402: path: /apis/v2/agentmail/metrics source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/drafts/{draft_id}/send: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_draft_send summary: Send Draft description: Sends an existing draft and returns `message_id` and `thread_id`. 🔴 **This sends real email and it cannot be recalled** — review the draft with `get_agentmail_inbox_draft` first, since this call takes no content of its own and sends whatever the draft currently holds. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '403': description: Error response with status 403 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_messages_UpdateMessageRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts/{draft_id}/send source: https://github.com/AIsa-team/aisa-proxy /agentmail/lists/{direction}/{type}/{entry}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_list_entry summary: Get Account List Entry description: 'Fetches one account-wide allow or block entry: `entry`, `entry_type`, `reason`, `direction`, `list_type`, `created_at`, `read_only` and `organization_id`. `read_only` marks platform-managed entries, which cannot be deleted. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_list_entry` is the one to use when a single inbox is meant.' tags: - Agent Email parameters: - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: entry in: path description: Email address or domain. required: true schema: type: string - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_lists_ListEntry' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/lists/{direction}/{type}/{entry} source: https://github.com/AIsa-team/aisa-proxy delete: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: delete_agentmail_list_entry summary: Delete Account List Entry description: Removes one entry from an **account-wide** allow or block list. Returns no body. 🔴 This changes mail handling for **every inbox in the account, including other callers'**; the inbox-scoped `delete_agentmail_inbox_list_entry` is the narrower action. Entries whose `read_only` is true are platform managed and cannot be removed — check with `get_agentmail_list_entry` first. tags: - Agent Email parameters: - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: entry in: path description: Email address or domain. required: true schema: type: string - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Successful response '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/lists/{direction}/{type}/{entry} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/metrics: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_metrics summary: Query Inbox Metrics description: 'Returns the same aggregate counters as `get_agentmail_metrics` but for one inbox: a flat map of counter name to an array of data points, keyed by `message.received`, `message.received.spam`, `message.received.blocked`, `message.received.unauthenticated`, `message.sent`, `message.delivered`, `message.bounced`, `message.complained`, `message.rejected`, `message.opened` and `domain.verified`. An empty array means no activity, not an error. The shape is not pinned in this spec, so read the keys actually returned. For individual events rather than counts use `get_agentmail_inbox_events`; for the account-wide totals, `get_agentmail_metrics`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: event_types in: query required: false schema: $ref: '#/components/schemas/type_metrics_MetricEventTypes' - name: start in: query required: false schema: $ref: '#/components/schemas/type_metrics_Start' - name: end in: query required: false schema: $ref: '#/components/schemas/type_metrics_End' - name: period in: query required: false schema: $ref: '#/components/schemas/type_metrics_Period' - name: limit in: query required: false schema: $ref: '#/components/schemas/type_metrics_MetricLimit' - name: descending in: query required: false schema: $ref: '#/components/schemas/type_metrics_Descending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_metrics_QueryMetricsResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/metrics source: https://github.com/AIsa-team/aisa-proxy /agentmail/drafts: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_drafts summary: List All Drafts description: Lists unsent drafts across **every inbox in the account**. Returns `count`, `limit`, `next_page_token` and `drafts`; page with `next_page_token`. Each draft carries `draft_id`, `inbox_id`, `to`, `cc`, `bcc`, `subject`, `preview`, `attachments`, `send_status` and `send_at`. List items carry `preview` only — `text` and `html` come from `get_agentmail_draft`. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_drafts` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: labels in: query required: false schema: $ref: '#/components/schemas/type__Labels' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_drafts_ListDraftsResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/drafts source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/{message_id}/forward: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_message_forward summary: Forward Message description: Forwards one message to new recipients and returns `message_id` and `thread_id`. 🔴 **This sends real email and it cannot be recalled, and it passes along the original content including attachments** — check what you are forwarding with `get_agentmail_inbox_message` first. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created. To answer instead of forward, use `post_agentmail_inbox_message_reply`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '403': description: Error response with status 403 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id}/forward source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/{message_id}/raw: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_message_raw summary: Get Raw Message description: Returns the original RFC 822 source of one message as `message_id`, `size`, a short-lived `download_url` and `expires_at`. The bytes are not inlined — fetch `download_url` before it expires. Use this for headers, DKIM or exact MIME structure; for parsed text and HTML use `get_agentmail_inbox_message`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_RawMessageResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id}/raw source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_message_attachment summary: Get Message Attachment description: Fetches metadata for one attachment on a message. Returns `attachment_id`, `filename`, `size`, `content_type`, `content_disposition`, `content_id` and a short-lived `download_url` with `expires_at`. The bytes are not inlined — fetch `download_url` before it expires. Attachment ids come from the `attachments` array on `get_agentmail_inbox_message`. The thread-level and draft-level twins are `get_agentmail_inbox_thread_attachment` and `get_agentmail_inbox_draft_attachment`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: attachment_id in: path required: true schema: $ref: '#/components/schemas/type_attachments_AttachmentId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_attachments_AttachmentResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inboxes summary: List Inboxes description: Lists every inbox in the AgentMail account. Returns `count`, `limit`, `next_page_token` and `inboxes`; page with `next_page_token`. Each inbox carries `inbox_id`, `email`, `display_name`, `client_id`, `pod_id`, `metadata`, `created_at` and `updated_at`. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so this list is not scoped to you and the inboxes it returns may belong to someone else. Use `get_agentmail_inbox` for one inbox you already know the id of, and `post_agentmail_inbox` to create one. tags: - Agent Email parameters: - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_inboxes_ListInboxesResponse' x-x402: path: /apis/v2/agentmail/inboxes source: https://github.com/AIsa-team/aisa-proxy post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox summary: Create Inbox description: 'Creates a new inbox — a real address that can send and receive. Optional `username` picks the local part (`support@agentmail.to`); omit it for a generated one such as `livelyspirit481@agentmail.to`. The domain is always `agentmail.to` here because AIsa does not expose domain management. Returns `inbox_id`, `email`, `display_name`, `client_id`, `pod_id`, `metadata` and timestamps. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller. Read one back with `get_agentmail_inbox`, list them with `get_agentmail_inboxes`.' tags: - Agent Email parameters: - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_inboxes_Inbox' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_inboxes_CreateInboxRequest' x-x402: path: /apis/v2/agentmail/inboxes source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/{message_id}/reply: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_message_reply summary: Reply To Message description: Replies to one message, threading the response correctly, and returns `message_id` and `thread_id`. 🔴 **This sends real email and it cannot be recalled.** It answers the sender only — `post_agentmail_inbox_message_reply_all` answers every recipient, which is a materially different blast radius, so pick deliberately. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created. To send to a fresh set of recipients use `post_agentmail_inbox_message_send`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: message_id in: path required: true schema: $ref: '#/components/schemas/type_messages_MessageId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_SendMessageResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '403': description: Error response with status 403 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_messages_ReplyToMessageRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/{message_id}/reply source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_thread_attachment summary: Get Thread Attachment description: Fetches metadata for one attachment anywhere in a thread. Returns `attachment_id`, `filename`, `size`, `content_type`, `content_disposition`, `content_id` and a short-lived `download_url` with `expires_at`. The bytes are not inlined — fetch `download_url` before it expires. Ids come from the thread's `attachments` array on `get_agentmail_inbox_thread`. The message-level twin is `get_agentmail_inbox_message_attachment`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: thread_id in: path required: true schema: $ref: '#/components/schemas/type_threads_ThreadId' - name: attachment_id in: path required: true schema: $ref: '#/components/schemas/type_attachments_AttachmentId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_attachments_AttachmentResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/drafts/{draft_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_draft summary: Get Any Draft description: 'Fetches one unsent draft by id without naming an inbox: `draft_id`, `inbox_id`, `client_id`, `labels`, `reply_to`, `to`, `cc`, `bcc`, `subject`, `preview`, `text`, `html`, `attachments`, `in_reply_to` and `references`. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_draft` is the one to use when a single inbox is meant.' tags: - Agent Email parameters: - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_drafts_Draft' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/drafts/{draft_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/lists/{direction}/{type}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_list_entries summary: List Inbox List Entries description: Lists one inbox's allow or block entries. `direction` selects inbound or outbound and `type` the list kind. Returns `count`, `limit`, `next_page_token` and `entries`; page with `next_page_token`. Each entry carries `entry`, `entry_type`, `reason`, `direction`, `list_type`, `created_at`, `read_only`, `inbox_id` and `pod_id`. The account-wide twin is `get_agentmail_list_entries`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_lists_PodListListEntriesResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/lists/{direction}/{type} source: https://github.com/AIsa-team/aisa-proxy post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: post_agentmail_inbox_list_entry summary: Create Inbox List Entry description: 'Adds one address or domain to an inbox''s allow or block list and returns the created entry. This changes which mail the inbox will accept or send from that point on, so it is a standing rule rather than a one-off action. Writes to the shared AgentMail workspace: Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, and what you write here is visible and editable by the next caller. Remove one with `delete_agentmail_inbox_list_entry`.' tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: direction in: path required: true schema: $ref: '#/components/schemas/type_lists_Direction' - name: type in: path required: true schema: $ref: '#/components/schemas/type_lists_ListType' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_lists_PodListEntry' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/type_lists_CreateListEntryRequest' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/lists/{direction}/{type} source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_inbox_draft_attachment summary: Get Draft Attachment description: Fetches metadata for one attachment on an unsent draft. Returns `attachment_id`, `filename`, `size`, `content_type`, `content_disposition`, `content_id` and a short-lived `download_url` with `expires_at`. The bytes are not inlined — fetch `download_url` before it expires. Ids come from the draft's `attachments` array on `get_agentmail_inbox_draft`. The sent-message twin is `get_agentmail_inbox_message_attachment`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: draft_id in: path required: true schema: $ref: '#/components/schemas/type_drafts_DraftId' - name: attachment_id in: path required: true schema: $ref: '#/components/schemas/type_attachments_AttachmentId' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_attachments_AttachmentResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id} source: https://github.com/AIsa-team/aisa-proxy /agentmail/api-keys: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_api_keys summary: List Account API Keys description: 'Lists API key metadata for the AgentMail account: `count`, `next_page_token` and `api_keys`, each with `api_key_id`, `prefix`, `name`, `pod_id`, `inbox_id`, `used_at`, `permissions` and `created_at`. The key secret itself is never returned, only its `prefix`. 🔴 **This is the account-management surface, not a per-caller one.** Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so the keys listed are the AIsa platform''s own, not yours. Nothing in normal mail workflows needs this — use `get_agentmail_inboxes` to find inboxes and `get_agentmail_inbox_messages` to read mail.' tags: - Agent Email parameters: - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_api-keys_ListApiKeysResponse' security: - Bearer: [] x-x402: path: /apis/v2/agentmail/api-keys source: https://github.com/AIsa-team/aisa-proxy /agentmail/domains: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med operationId: get_agentmail_domains summary: List Account Domains description: 'Lists custom sending domains configured on the AgentMail account: `count`, `limit`, `next_page_token` and `domains`. 🔴 **This is the account-management surface, not a per-caller one.** Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created, so the domains listed belong to the AIsa platform. Inboxes created through AIsa always use `agentmail.to`, so this list does not change what `post_agentmail_inbox` can do.' tags: - Agent Email parameters: - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: ascending in: query required: false schema: $ref: '#/components/schemas/type__Ascending' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_domains_ListDomainsResponse' security: - Bearer: [] x-x402: path: /apis/v2/agentmail/domains source: https://github.com/AIsa-team/aisa-proxy /agentmail/threads/search: get: operationId: get_agentmail_threads_search summary: Search All Threads description: Full-text search over threads in **every inbox in the account**. Returns `count`, `limit`, `next_page_token` and `threads`; page with `next_page_token`. Same fields as `get_agentmail_threads`, which is the one to use for everything in date order. This is the organization-wide view spanning every inbox in the account. Every AIsa caller shares one AgentMail account, so this reaches inboxes other callers created; the inbox-scoped twin `get_agentmail_inbox_threads_search` is the one to use when a single inbox is meant. tags: - Agent Email parameters: - name: q in: query required: true schema: $ref: '#/components/schemas/type__Query' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_SearchThreadsResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' security: - Bearer: [] x-x402: path: /apis/v2/agentmail/threads/search source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/threads/search: get: operationId: get_agentmail_inbox_threads_search summary: Search Threads description: Full-text search across one inbox's threads. Returns `count`, `limit`, `next_page_token` and `threads`; page with `next_page_token`. Same thread fields as `get_agentmail_inbox_threads`, which is the one to use for everything in date order. To search individual messages rather than conversations use `get_agentmail_inbox_messages_search`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: q in: query required: true schema: $ref: '#/components/schemas/type__Query' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_threads_SearchThreadsResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' security: - Bearer: [] x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/threads/search source: https://github.com/AIsa-team/aisa-proxy /agentmail/inboxes/{inbox_id}/messages/search: get: operationId: get_agentmail_inbox_messages_search summary: Search Messages description: Full-text search across one inbox's messages. Returns `count`, `limit`, `next_page_token` and `messages`; page with `next_page_token`. Same message fields as `get_agentmail_inbox_messages`, which is the one to use when you want everything in date order rather than a query. Searching conversations instead of individual messages is `get_agentmail_inbox_threads_search`. tags: - Agent Email parameters: - name: inbox_id in: path required: true schema: $ref: '#/components/schemas/type_inboxes_InboxId' - name: q in: query required: true schema: $ref: '#/components/schemas/type__Query' - name: limit in: query required: false schema: $ref: '#/components/schemas/type__Limit' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type__PageToken' - name: before in: query required: false schema: $ref: '#/components/schemas/type__Before' - name: after in: query required: false schema: $ref: '#/components/schemas/type__After' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Response with status 200 content: application/json: schema: $ref: '#/components/schemas/type_messages_SearchMessagesResponse' '400': description: Error response with status 400 content: application/json: schema: $ref: '#/components/schemas/type__ValidationErrorResponse' '404': description: Error response with status 404 content: application/json: schema: $ref: '#/components/schemas/type__ErrorResponse' security: - Bearer: [] x-x402: path: /apis/v2/agentmail/inboxes/{inbox_id}/messages/search source: https://github.com/AIsa-team/aisa-proxy /ahrefs/site-explorer/domain-rating: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.08 cost_tier: med note: self / already-verified-domain lookups bill ~$0.02 (reduced-unit floor); $0.08 otherwise summary: Domain Rating description: Return the Ahrefs Domain Rating (0-100 authority score) and Ahrefs Rank for a target domain on a given date. Billed $0.02 per successful call; 4xx/5xx are not charged. operationId: get_ahrefs_domain_rating parameters: - name: target in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string - name: date in: query required: true description: Snapshot date in `YYYY-MM-DD` format. schema: type: string format: date example: '2026-08-01' responses: '200': description: Domain Rating result. content: application/json: example: domain_rating: domain_rating: 91.0 ahrefs_rank: 619 schema: type: object properties: domain_rating: type: object properties: domain_rating: type: number description: Domain Rating (0-100). ahrefs_rank: type: integer description: Global Ahrefs Rank. tags: - SEO & Search Data x-x402: path: /apis/v2/ahrefs/site-explorer/domain-rating source: https://github.com/AIsa-team/aisa-proxy /ahrefs/site-explorer/metrics: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.18 cost_tier: med summary: Site Metrics description: 'Return core Site Explorer metrics for a target domain on a given date: organic and paid keyword counts, top-3 keyword count, organic traffic, and traffic value. Billed $0.18 per successful call; 4xx/5xx are not charged.' operationId: get_ahrefs_site_metrics parameters: - name: target in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string - name: date in: query required: true description: Snapshot date in `YYYY-MM-DD` format. schema: type: string format: date example: '2026-08-01' responses: '200': description: Core site metrics. content: application/json: example: metrics: org_keywords: 1843000 paid_keywords: 6790 org_keywords_1_3: 412000 org_traffic: 20413900 org_cost: 42474500 schema: type: object properties: metrics: type: object properties: org_keywords: type: integer description: Organic keyword count. paid_keywords: type: integer description: Paid keyword count. org_keywords_1_3: type: integer description: Organic keywords ranking in top 3. org_traffic: type: integer description: Estimated monthly organic traffic. org_cost: type: integer description: Estimated organic traffic value. tags: - SEO & Search Data x-x402: path: /apis/v2/ahrefs/site-explorer/metrics source: https://github.com/AIsa-team/aisa-proxy /financial/analyst-estimates: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.12 cost_tier: med summary: Analyst Estimates description: 'Forward analyst consensus for one stock: `fiscal_period`, `period`, `revenue` and `earnings_per_share` per estimated period. `ticker` is required; `period` selects annual or quarterly and `limit` caps how many periods come back. Deliberately narrow — no analyst names, no ratings, no price targets, no high/low dispersion. Use it for what the street expects. For what was actually reported, and by how much it beat or missed, use `get_financial_earnings`.' operationId: get_financial_analyst_estimates parameters: - name: ticker in: query description: The ticker to get analyst estimates for. required: true schema: type: string - name: period in: query description: The period to get analyst estimates for. Use the /analyst-estimates/periods endpoint to get a list of available periods. Defaults to 'annual'. required: false schema: type: string enum: - annual - quarterly - name: limit in: query description: The maximum number of estimates to return (max 3 for annual, 12 for quarterly). required: false schema: type: integer responses: '200': description: Analyst estimates response content: application/json: schema: $ref: '#/components/schemas/AnalystEstimatesResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' tags: - Financial Data x-x402: path: /apis/v2/financial/analyst-estimates source: https://github.com/AIsa-team/aisa-proxy /apollo/people/match: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.01975 max: 0.17775 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: People Enrichment description: 'Enrich one person: give whatever identifiers you have and get back Apollo''s full record for them. Accepts `email`, `first_name` plus `last_name`, `name`, `domain`, `organization_name`, `linkedin_url` or `hashed_email` — the more you supply, the likelier the match. Returns a `person` object with `id`, `name`, `title`, `headline`, `linkedin_url`, `twitter_url`, `github_url`, `photo_url`, `organization_id` and an `employment_history` array, plus a `request_id`. Personal emails and phone numbers are withheld unless `reveal_personal_emails` or `reveal_phone_number` is set, and those cost extra credits. A 200 does not guarantee a match — check whether `person` actually came back. Use `post_apollo_people_bulk_match` for up to 10 people in one call; use `post_apollo_mixed_people_api_search` when you do not have an identifier and need to find candidates first.' operationId: post_apollo_people_match parameters: - name: first_name in: query required: false schema: type: string description: 'The first name of the person. This is typically used in combination with the last_name parameter. Example: tim' - name: last_name in: query required: false schema: type: string description: 'The last name of the person. This is typically used in combination with the first_name parameter. Example: zheng' - name: name in: query required: false schema: type: string description: 'The full name of the person. This will typically be a first name and last name separated by a space. If you use this parameter, you do not need to use the first_name and last_name parameters. Example: tim zheng' - name: email in: query required: false schema: type: string description: 'The email address of the person. Example: example@email.com' - name: hashed_email in: query required: false schema: type: string description: 'The hashed email of the person. The email should adhere to either the MD5 or SHA-256 hash format. Example: 8d935115b9ff4489f2d1f9249503cadf (MD5) or 97817c0c49994eb500ad0a5e7e2d8aed51977b26424d508f66e4e8887746a152 (SHA-256)' - name: organization_name in: query required: false schema: type: string description: 'The name of the person''s employer. This can be the current employer or a previous employer. Example: apollo' - name: domain in: query required: false schema: type: string description: 'The domain name for the person''s employer. This can be the current employer or a previous employer. Do not include www., the @ symbol, or similar. Example: apollo.io or microsoft.com' - name: id in: query required: false schema: type: string description: 'The Apollo ID for the person. Each person in the Apollo database is assigned a unique ID. To find IDs, call the People API Search endpoint and identify the values for person_id. Example: 587cf802f65125cad923a266' - name: linkedin_url in: query required: false schema: type: string description: 'The URL for the person''s LinkedIn profile. Example: http://www.linkedin.com/in/tim-zheng-677ba010' - name: run_waterfall_email in: query required: false schema: type: boolean description: Set to true to enable email waterfall enrichment - name: run_waterfall_phone in: query required: false schema: type: boolean description: Set to true to enable phone waterfall enrichment - name: reveal_personal_emails in: query required: false schema: type: boolean description: Set to true if you want to enrich the person's data with personal emails. This potentially consumes credits as part of your Apollo pricing plan . The default value is false. If a person resides in a GDPR -compliant region, Apollo will not reveal their personal email. - name: reveal_phone_number in: query required: false schema: type: boolean description: Set to true if you want to enrich the person's data with all available phone numbers, including mobile phone numbers. This potentially consumes credits as part of your Apollo pricing plan . The default value is false. If this parameter is set to true, you must enter a webhook URL for the webhook_url parameter. Apollo will asynchronously verify phone numbers for you, then send a JSON response that includes only details about the person's phone numbers to the webhook URL you provide. It can take several minutes for the phone numbers to be delivered. - name: webhook_url in: query required: false schema: type: string description: 'If you set the reveal_phone_number parameter to true, this parameter becomes mandatory. Otherwise, do not use this parameter. Enter the webhook URL that specifies where Apollo should send a JSON response that includes the phone number you requested. Apollo suggests testing this flow to ensure you receive the separate response with the phone number. If phone numbers are not revealed delivered to the webhook URL, try applying UTF-8 encoding to the webhook URL. Example: https://webhook.site/cc4cf44e-e047-4774-8dac-473d28474e40; https%3A%2F%2Fwebhook.site%2Fcc4cf44e-e047-4774-8dac-473d28474e40' responses: '200': description: Successful response content: application/json: schema: type: object properties: person: type: object description: Response object waterfall: type: object description: Response object '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/people/match source: https://github.com/AIsa-team/aisa-proxy /apollo/people/bulk_match: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.1975 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk People Enrichment description: 'Enrich up to 10 people in one call. Body takes `details`, an array of the same identifier objects `post_apollo_people_match` accepts. Returns `matches` alongside `status`, `total_requested_enrichments`, `unique_enriched_records`, `missing_records` and `credits_consumed` — read `missing_records` rather than assuming every input matched. Costs one credit per record enriched, not per call. Use this over a loop of single calls: same credits, one round trip. For a single person `post_apollo_people_match` is simpler.' operationId: post_apollo_people_bulk_match parameters: - name: run_waterfall_email in: query required: false schema: type: boolean description: Set to true to enable email waterfall enrichment - name: run_waterfall_phone in: query required: false schema: type: boolean description: Set to true to enable phone waterfall enrichment - name: reveal_personal_emails in: query required: false schema: type: boolean description: Set to true if you want to enrich all matched people with personal emails. This potentially consumes credits as part of your Apollo pricing plan . The default value is false. If a person resides in a GDPR -compliant region, Apollo will not reveal their personal email. - name: reveal_phone_number in: query required: false schema: type: boolean description: Set to true if you want to enrich the data of all matched people with all available phone numbers, including mobile phone numbers. This potentially consumes credits as part of your Apollo pricing plan . The default value is false. If this parameter is set to true, you must enter a webhook URL for the webhook_url parameter. Apollo will asynchronously verify phone numbers for you, then send a JSON response that includes only details about the phone numbers to the webhook URL you provide. It can take several minutes for the phone numbers to be delivered. - name: webhook_url in: query required: false schema: type: string description: 'If you set the reveal_phone_number parameter to true, this parameter becomes mandatory. Otherwise, do not use this parameter. Enter the webhook URL that specifies where Apollo should send a JSON response that includes the phone number you requested. Apollo suggests testing this flow to ensure you receive the separate response with the phone number. If phone numbers are not revealed delivered to the webhook URL, try applying UTF-8 encoding to the webhook URL. Example: https://webhook.site/cc4cf44e-e047-4774-8dac-473d28474e40; https%3A%2F%2Fwebhook.site%2Fcc4cf44e-e047-4774-8dac-473d28474e40' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: string description: Response field error_code: type: string description: Response field error_message: type: string description: Response field total_requested_enrichments: type: integer description: Response field unique_enriched_records: type: integer description: Response field missing_records: type: integer description: Response field credits_consumed: type: integer description: Response field matches: type: array items: type: string description: Response array waterfall: type: object description: Response object '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: details: type: array items: type: object description: One person to enrich. Give whatever identifiers you have — the more, the likelier the match. properties: first_name: type: string description: 'First name, used with last_name. Example: tim' last_name: type: string description: 'Last name, used with first_name. Example: zheng' name: type: string description: Full name, e.g. "tim zheng"; replaces first_name + last_name. email: type: string description: Email address of the person. hashed_email: type: string description: MD5 or SHA-256 hash of the email address. organization_name: type: string description: 'Name of the person''s employer. Example: apollo' domain: type: string description: 'Domain of the person''s employer, without www. Example: apollo.io' id: type: string description: Apollo person id, e.g. from a people search. linkedin_url: type: string description: LinkedIn profile URL of the person. description: Provide info for each person you want to enrich as an object within this array. Add up to 10 people. required: - details tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/people/bulk_match source: https://github.com/AIsa-team/aisa-proxy /apollo/organizations/enrich: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.0395 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Organization Enrichment description: Enrich one company by domain. `domain` is the only parameter and it must be the bare domain (apple.com), not a full URL. Returns an `organization` object with `id`, `name`, `website_url`, `linkedin_url`, `twitter_url`, `facebook_url`, `angellist_url`, `phone`, `founded_year`, `alexa_ranking`, `publicly_traded_symbol`, `publicly_traded_exchange` and `languages`. Use it as the entry point when all you have is a domain. For several domains at once use `post_apollo_organizations_bulk_enrich`; for the full record including funding and technology detail use `get_apollo_organizations_id`, which needs the Apollo organization id this call returns. operationId: get_apollo_organizations_enrich parameters: - name: domain in: query required: true schema: type: string description: 'The domain of the company that you want to enrich. Do not include www., the @ symbol, or similar. Example: apollo.io or microsoft.com' responses: '200': description: Successful response content: application/json: schema: type: object properties: organization: type: object description: Response object '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/organizations/enrich source: https://github.com/AIsa-team/aisa-proxy /apollo/organizations/bulk_enrich: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.0395 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Organization Enrichment description: Enrich up to 10 companies in one call. Body takes `domains`, an array of bare domains. Returns the enriched organizations alongside `status`, `total_requested_domains`, `unique_domains`, `unique_records` and `unique_enriched_records` — compare the requested and enriched counts rather than assuming every domain resolved. For one domain `get_apollo_organizations_enrich` is a plain GET. operationId: post_apollo_organizations_bulk_enrich parameters: - name: domains[] in: query required: true schema: type: array items: type: string description: 'The domain of each company that you want to enrich. Do not include www., the @ symbol, or similar. Example: apollo.io and microsoft.com' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: string description: Response field error_code: type: string description: Response field error_message: type: string description: Response field total_requested_domains: type: integer description: Response field unique_domains: type: integer description: Response field unique_enriched_records: type: integer description: Response field missing_records: type: integer description: Response field organizations: type: array items: type: string description: Response array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/organizations/bulk_enrich source: https://github.com/AIsa-team/aisa-proxy /apollo/mixed_people/api_search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: People API Search description: 'Find people matching criteria rather than enriching someone you already identified. Filter by job title, seniority, location, company domain, headcount and industry, and page with `page` and `per_page`. Returns `total_entries` and a `people` array. Note what search deliberately withholds: entries carry `last_name_obfuscated` and boolean flags — `has_email`, `has_direct_phone`, `has_city`, `has_state`, `has_country` — instead of the values themselves. Search tells you a match exists; enrichment reveals the contact details. Feed the ids into `post_apollo_people_match` or `post_apollo_people_bulk_match` to get emails and phone numbers, which is also where the credits are spent.' operationId: post_apollo_mixed_people_api_search parameters: - name: person_titles[] in: query required: false schema: type: array items: type: string description: 'Job titles held by the people you want to find. For a person to be included in search results, they only need to match 1 of the job titles you add. Adding more job titles expands your search results. Results also include job titles with the same terms, even if they are not exact matches. For example, searching for marketing manager might return people with the job title content marketing manager. Use this parameter in combination with the person_seniorities[] parameter to find people based on specific job functions and seniority levels. Examples: sales development representative; marketing manager; research analyst' - name: include_similar_titles in: query required: false schema: type: boolean description: This parameter determines whether people with job titles similar to the titles you define in the person_titles[] parameter are returned in the response. Set this parameter to false when using person_titles[] to return only strict matches for job titles. - name: q_keywords in: query required: false schema: type: string description: A string of words over which we want to filter the results. - name: person_locations[] in: query required: false schema: type: array items: type: string description: 'The location where people live. You can search across cities, US states, and countries. To find people based on the headquarters locations of their current employer, use the organization_locations parameter. Examples: california; ireland; chicago' - name: person_seniorities[] in: query required: false schema: type: array items: type: string description: 'The job seniority that people hold within their current employer. This enables you to find people that currently hold positions at certain reporting levels, such as Director level or senior IC level. For a person to be included in search results, they only need to match 1 of the seniorities you add. Adding more seniorities expands your search results. Searches only return results based on their current job title, so searching for Director-level employees only returns people that currently hold a Director-level title. If someone was previously a Director, but is currently a VP, they would not be included in your search results. Use this parameter in combination with the person_titles[] parameter to find people based on specific job functions and seniority levels. The following options can be used for this parameter: owner founder c_suite partner vp head director manager senior entry intern' - name: organization_locations[] in: query required: false schema: type: array items: type: string description: 'The location of the company headquarters for a person''s current employer. You can search across cities, US states, and countries. If a company has several office locations, results are still based on the headquarters location. For example, if you search chicago but a company''s HQ location is in boston, people that work for the Boston-based company will not appear in your results, even if they match other parameters. To find people based on their personal location, use the person_locations parameter. Examples: texas; tokyo; spain' - name: q_organization_domains_list[] in: query required: false schema: type: array items: type: string description: 'The domain name for the person''s employer. This can be the current employer or a previous employer. Do not include www., the @ symbol, or similar. This parameter accepts up to 1,000 domains in a single request. Examples: apollo.io; microsoft.com' - name: contact_email_status[] in: query required: false schema: type: array items: type: string description: 'The email statuses for the people you want to find. You can add multiple statuses to expand your search. The statuses you can search include: verified unverified likely to engage unavailable' - name: organization_ids[] in: query required: false schema: type: array items: type: string description: 'The Apollo IDs for the companies (employers) you want to include in your search results. Each company in the Apollo database is assigned a unique ID. To find IDs, call the Organization Search endpoint and identify the values for organization_id. Example: 5e66b6381e05b4008c8331b8' - name: organization_num_employees_ranges[] in: query required: false schema: type: array items: type: string description: 'The number range of employees working for the person''s current company. This enables you to find people based on the headcount of their employer. You can add multiple ranges to expand your search results. Each range you add needs to be a string, with the upper and lower numbers of the range separated only by a comma. Examples: 1,10; 250,500; 10000,20000' - name: revenue_range[min] in: query required: false schema: type: integer description: 'The minimum revenue the person''s current employer generates. Use this parameter in combination with revenue_range[max] to set a revenue range. Do not enter currency symbols, commas, or decimal points in the figure. Examples: 500000; 1500000' - name: revenue_range[max] in: query required: false schema: type: integer description: 'The maximum revenue the person''s current employer generates. Use this parameter in combination with revenue_range[min] to set a revenue range. Do not enter currency symbols, commas, or decimal points in the figure. Examples: 500000; 1500000' - name: currently_using_all_of_technology_uids[] in: query required: false schema: type: array items: type: string description: 'Find people based on all of the technologies their current employer uses. Apollo supports filtering by 1,500+ technologies. Apollo calculates technologies data from multiple sources. This data is updated regularly. Check out the full list of supported technologies by downloading this CSV file . Use underscores (_) to replace spaces and periods for the technologies listed in the CSV file. Examples: salesforce; google_analytics; wordpress_org' - name: currently_using_any_of_technology_uids[] in: query required: false schema: type: array items: type: string description: 'Find people based on any of the technologies their current employer uses. Apollo supports filtering by 1,500+ technologies. Apollo calculates technologies data from multiple sources. This data is updated regularly. Check out the full list of supported technologies by downloading this CSV file . Use underscores (_) to replace spaces and periods for the technologies listed in the CSV file. Examples: salesforce; google_analytics; wordpress_org' - name: currently_not_using_any_of_technology_uids[] in: query required: false schema: type: array items: type: string description: 'Exclude people from your search based on any of the technologies their current employer uses. Apollo supports filtering by 1,500+ technologies. Apollo calculates technologies data from multiple sources. This data is updated regularly. Check out the full list of supported technologies by downloading this CSV file . Use underscores (_) to replace spaces and periods for the technologies listed in the CSV file. Examples: salesforce; google_analytics; wordpress_org' - name: q_organization_job_titles[] in: query required: false schema: type: array items: type: string description: 'The job titles that are listed in active job postings at the person''s current employer. Examples: sales manager; research analyst' - name: organization_job_locations[] in: query required: false schema: type: array items: type: string description: 'The locations of the jobs being actively recruited by the person''s employer. Examples: atlanta; japan' - name: organization_num_jobs_range[min] in: query required: false schema: type: integer description: 'The minimum number of job postings active at the person''s current employer. Use this parameter in combination with organization_num_jobs_range[max] to set a job postings range. Examples: 50; 500' - name: organization_num_jobs_range[max] in: query required: false schema: type: integer description: 'The maximum number of job postings active at the person''s current employer. Use this parameter in combination with organization_num_jobs_range[min] to set a job postings range. Examples: 50; 500' - name: organization_job_posted_at_range[min] in: query required: false schema: type: string description: 'The earliest date when jobs were posted by the person''s current employer. Use this parameter in combination with organization_job_posted_at_range[max] to set a date range for when jobs posted. Example: 2025-07-25' - name: organization_job_posted_at_range[max] in: query required: false schema: type: string description: 'The latest date when jobs were posted by the person''s current employer. Use this parameter in combination with organization_job_posted_at_range[min] to set a date range for when jobs posted. Example: 2025-09-25' - name: page in: query required: false schema: type: integer description: 'The page number of the Apollo data that you want to retrieve. Use this parameter in combination with the per_page parameter to make search results for navigable and improve the performance of the endpoint. Example: 4' - name: per_page in: query required: false schema: type: integer description: 'The number of search results that should be returned for each page. Limiting the number of results per page improves the endpoint''s performance. Use the page parameter to search the different pages of data. Example: 10' responses: '200': description: Successful response content: application/json: schema: type: object properties: total_entries: type: integer description: Response field people: type: array items: type: string description: Response array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/mixed_people/api_search source: https://github.com/AIsa-team/aisa-proxy /apollo/mixed_companies/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.0395 max: 0.0395 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Organization Search description: 'Find companies matching criteria: name, domain, headcount, industry, location, funding stage and technologies in use. Returns `organizations` and `accounts` side by side — organizations are Apollo''s global database, accounts are records that already exist in this Apollo workspace — plus `pagination` and `breadcrumbs` echoing the filters that were applied. Use it to build a target list. When you already know the domain, `get_apollo_organizations_enrich` answers directly and costs less.' operationId: post_apollo_mixed_companies_search parameters: - name: q_organization_domains_list[] in: query required: false schema: type: array items: type: string description: 'The domain name for the person''s employer. This can be the current employer or a previous employer. Do not include www., the @ symbol, or similar. This parameter accepts up to 1,000 domains in a single request. Examples: apollo.io; microsoft.com' - name: organization_num_employees_ranges[] in: query required: false schema: type: array items: type: string description: 'The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results. Each range you add needs to be a string, with the upper and lower numbers of the range separated only by a comma. Examples: 1,10; 250,500; 10000,20000' - name: organization_locations[] in: query required: false schema: type: array items: type: string description: 'The location of the company headquarters. You can search across cities, US states, and countries. If a company has several office locations, results are still based on the headquarters location. For example, if you search chicago but a company''s HQ location is in boston, any Boston-based companies will not appearch in your search results, even if they match other parameters.. To exclude companies based on location, use the organization_not_locations parameter. Examples: texas; tokyo; spain' - name: organization_not_locations[] in: query required: false schema: type: array items: type: string description: 'Exclude companies from search results based on the location of the company headquarters. You can use cities, US states, and countries as locations to exclude. This parameter is useful for ensuring you do not prospect in an undesirable territory. For example, if you use ireland as a value, no Ireland-based companies will appear in your search results. Examples: minnesota; ireland; seoul' - name: revenue_range[min] in: query required: false schema: type: integer description: 'Search for organizations based on their revenue. Use this parameter to set the lower range of organization revenue. Use the revenue_range[max] parameter to set the upper range of revenue. Do not enter currency symbols, commas, or decimal points in the figure. Example: 300000' - name: revenue_range[max] in: query required: false schema: type: integer description: 'Search for organizations based on their revenue. Use this parameter to set the upper range of organization revenue. Use the revenue_range[min] parameter to set the lower range of revenue. Do not enter currency symbols, commas, or decimal points in the figure. Example: 50000000' - name: currently_using_any_of_technology_uids[] in: query required: false schema: type: array items: type: string description: 'Find organizations based on the technologies they currently use. Apollo supports filtering by 1,500+ technologies. Apollo calculates technologies data from multiple sources. This data is updated regularly. Check out the full list of supported technologies by downloading this CSV file . Use underscores (_) to replace spaces and periods for the technologies listed in the CSV file. Examples: salesforce; google_analytics; wordpress_org' - name: q_organization_keyword_tags[] in: query required: false schema: type: array items: type: string description: 'Filter search results based on keywords associated with companies. For example, you can enter mining as a value to return only companies that have an association with the mining industry. Examples: mining; sales strategy; consulting' - name: q_organization_name in: query required: false schema: type: string description: 'Filter search results to include a specific company name. If the value you enter for this parameter does not match with a company''s name, the company will not appear in search results, even if it matches other parameters. Partial matches are accepted. For example, if you filter by the value marketing, a company called NY Marketing Unlimited would still be eligible as a search result, but NY Market Analysis would not be eligible. Example: apollo or mining' - name: organization_ids[] in: query required: false schema: type: array items: type: string description: 'The Apollo IDs for the companies you want to include in your search results. Each company in the Apollo database is assigned a unique ID. To find IDs, identify the values for organization_id when you call this endpoint. Example: 5e66b6381e05b4008c8331b8' - name: latest_funding_amount_range[min] in: query required: false schema: type: integer description: 'The minimum amount the company received with its most recent funding round. Use this parameter in combination with latest_funding_amount_range[max] to set a monetary range for the company''s most recent funding round. Do not enter currency symbols, commas, or decimal points in the figure. Examples: 5000000; 15000000' - name: latest_funding_amount_range[max] in: query required: false schema: type: integer description: 'The maximium amount the company received with its most recent funding round. Use this parameter in combination with latest_funding_amount_range[min] to set a monetary range for the company''s most recent funding round. Do not enter currency symbols, commas, or decimal points in the figure. Examples: 5000000; 15000000' - name: total_funding_range[min] in: query required: false schema: type: integer description: 'The minimum amount the company received during all of its funding rounds combined. Use this parameter in combination with total_funding_range[max] to set a monetary range for all of the company''s funding rounds. Do not enter currency symbols, commas, or decimal points in the figure. Examples: 50000000; 350000000' - name: total_funding_range[max] in: query required: false schema: type: integer description: 'The maximum amount the company received during all of its funding rounds combined. Use this parameter in combination with total_funding_range[min] to set a monetary range for all of the company''s funding rounds. Do not enter currency symbols, commas, or decimal points in the figure. Examples: 50000000; 350000000' - name: latest_funding_date_range[min] in: query required: false schema: type: string description: 'The earliest date when the company received its most recent funding round. Use this parameter in combination with latest_funding_date_range[max] to set a date range for when the company received its most recent funding round. Example: 2025-07-25' - name: latest_funding_date_range[max] in: query required: false schema: type: string description: 'The latest date when the company received its most recent funding round. Use this parameter in combination with latest_funding_date_range[min] to set a date range for when the company received its most recent funding round. Example: 2025-09-25' - name: q_organization_job_titles[] in: query required: false schema: type: array items: type: string description: 'The job titles that are listed in active job postings at the company. Examples: sales manager; research analyst' - name: organization_job_locations[] in: query required: false schema: type: array items: type: string description: 'The locations of the jobs being actively recruited by the company. Examples: atlanta; japan' - name: organization_num_jobs_range[min] in: query required: false schema: type: integer description: 'The minimum number of job postings active at the company. Use this parameter in combination with organization_num_jobs_range[max] to set a job postings range. Examples: 50; 500' - name: organization_num_jobs_range[max] in: query required: false schema: type: integer description: 'The maximum number of job postings active at the company. Use this parameter in combination with organization_num_jobs_range[min] to set a job postings range. Examples: 50; 500' - name: organization_job_posted_at_range[min] in: query required: false schema: type: string description: 'The earliest date when jobs were posted by the company. Use this parameter in combination with organization_job_posted_at_range[max] to set a date range for when jobs posted. Example: 2025-07-25' - name: organization_job_posted_at_range[max] in: query required: false schema: type: string description: 'The latest date when jobs were posted by the company. Use this parameter in combination with organization_job_posted_at_range[min] to set a date range for when jobs posted. Example: 2025-09-25' - name: page in: query required: false schema: type: integer description: 'The page number of the Apollo data that you want to retrieve. Use this parameter in combination with the per_page parameter to make search results for navigable and improve the performance of the endpoint. Example: 4' - name: per_page in: query required: false schema: type: integer description: 'The number of search results that should be returned for each page. Limiting the number of results per page improves the endpoint''s performance. Use the page parameter to search the different pages of data. Example: 10' responses: '200': description: Successful response content: application/json: schema: type: object properties: breadcrumbs: type: array items: type: string description: Response array partial_results_only: type: boolean description: Response field has_join: type: boolean description: Response field disable_eu_prospecting: type: boolean description: Response field partial_results_limit: type: integer description: Response field pagination: type: object description: Response object accounts: type: array items: type: string description: Response array organizations: type: array items: type: string description: Response array model_ids: type: array items: type: string description: Response array num_fetch_result: type: string description: Response field derived_params: type: string description: Response field '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/mixed_companies/search source: https://github.com/AIsa-team/aisa-proxy /apollo/organizations/{organization_id}/job_postings: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.01975 observed_usd: min: 0.012 max: 0.01975 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Organization Job Postings description: Live job postings for one company, by Apollo organization id. Each posting carries its title, location, posted date and source URL. Useful as a hiring signal — which functions a company is expanding, and where. Get the organization id from `get_apollo_organizations_enrich` first. This reads Apollo's job board data, not the company's own careers page, so absence of postings is not proof a company is not hiring. operationId: get_apollo_organizations_organization_id_job_postings parameters: - name: organization_id in: path required: true schema: type: string description: 'The organization ID of the company for which you want to find job postings. Each company in the Apollo database is assigned a unique ID. To find IDs, call the Organization Search endpoint and identify the values for organization_id. Example: 5e66b6381e05b4008c8331b8' - name: page in: query required: false schema: type: integer description: 'The page number of the Apollo data that you want to retrieve. Use this parameter in combination with the per_page parameter to make search results for navigable and improve the performance of the endpoint. Example: 4' - name: per_page in: query required: false schema: type: integer description: 'The number of search results that should be returned for each page. Limiting the number of results per page improves the endpoint''s performance. Use the page parameter to search the different pages of data. Example: 10' responses: '200': description: Successful response content: application/json: schema: type: object properties: organization_job_postings: type: array items: type: string description: Response array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/organizations/{organization_id}/job_postings source: https://github.com/AIsa-team/aisa-proxy /apollo/organizations/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Complete Organization Info description: 'The complete Apollo record for one company, by Apollo organization id (not by domain). Returns an `organization` object carrying everything enrichment returns plus the deeper fields: funding history, technology stack, department headcounts and related organizations. Get the id from `get_apollo_organizations_enrich` or `post_apollo_mixed_companies_search` first — this endpoint cannot take a domain.' operationId: get_apollo_organizations_id parameters: - name: id in: path required: true schema: type: string description: 'The Apollo ID for the organization that you want to research. To find organization IDs, call the Organization Search endpoint and identify the organizaton_id value for the organization. Example: 5e66b6381e05b4008c8331b8' responses: '200': description: Successful response content: application/json: schema: type: object properties: organization: type: object description: Response object '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/organizations/{id} source: https://github.com/AIsa-team/aisa-proxy /apollo/news_articles/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.01975 observed_usd: min: 0.012 max: 0.01975 cost_drivers: - param: records returned effect: charge scales with number of records enriched/returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: News Articles Search description: News coverage for specific companies. `organization_ids[]` is required — omitting it returns HTTP 422 with "organization_ids is required", so resolve the companies first with `get_apollo_organizations_enrich` or `post_apollo_mixed_companies_search`. Narrow further with `categories[]` (funding, hires, launches and similar), `published_at[min]`, `published_at[max]`, and page with `page` and `per_page`. Returns `news_articles` and `pagination`. Use it to catch a trigger event before reaching out. operationId: post_apollo_news_articles_search parameters: - name: organization_ids[] in: query required: true schema: type: array items: type: string description: 'The Apollo IDs for the companies you want to include in your search results. Each company in the Apollo database is assigned a unique ID. To find IDs, call the Organization Search endpoint and identify the values for organization_id. Example: 5e66b6381e05b4008c8331b8' - name: categories[] in: query required: false schema: type: array items: type: string description: 'Filter your search to include only certain categories or sub-categories of news. Use the News search filter for companies within Apollo to uncover all possible categories and sub-categories. Examples: hires; investment; contract' - name: published_at[min] in: query required: false schema: type: string description: 'Set the lower bound of the date range you want to search. Use this parameter in combination with the published_at[max] parameter. This date should fall before the published_at[max] date. The date should be formatted as YYYY-MM-DD. Example: 2025-02-15' - name: published_at[max] in: query required: false schema: type: string description: 'Set the upper bound of the date range you want to search. Use this parameter in combination with the published_at[min] parameter. This date should fall after the published_at[min] date. The date should be formatted as YYYY-MM-DD. Example: 2025-05-15' - name: page in: query required: false schema: type: integer description: 'The page number of the Apollo data that you want to retrieve. Use this parameter in combination with the per_page parameter to make search results for navigable and improve the performance of the endpoint. Example: 4' - name: per_page in: query required: false schema: type: integer description: 'The number of search results that should be returned for each page. Limiting the number of results per page improves the endpoint''s performance. Use the page parameter to search the different pages of data. Example: 10' responses: '200': description: Successful response content: application/json: schema: type: object properties: pagination: type: object description: Response object news_articles: type: array items: type: string description: Response array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/news_articles/search source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Create an Account description: 'Create an account — a company saved into this workspace. Duplicate domains are rejected, so search with `post_apollo_accounts_search` before creating. Requires a master API key. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. To enrich a company without saving it, use `get_apollo_organizations_enrich`.' operationId: post_apollo_accounts responses: '200': description: Successful response content: application/json: schema: type: object properties: account: type: object description: Created account additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Account name domain: type: string description: Account domain owner_id: type: string description: Owner ID account_stage_id: type: string description: Account stage ID required: - name - domain tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts/{account_id}: patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update an Account description: 'Update one account by its Apollo id. Send only the fields you intend to change; anything you omit keeps its current value. Stage fields expect an id from `get_apollo_account_stages`. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: patch_apollo_accounts_account_id parameters: - name: account_id in: path required: true schema: type: string description: Account ID responses: '200': description: Successful response content: application/json: schema: type: object properties: account: type: object description: Updated account additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: Account name domain: type: string description: Account domain owner_id: type: string description: Owner ID account_stage_id: type: string description: Account stage ID raw_address: type: string description: Raw address phone: type: string description: Phone number typed_custom_fields: type: object description: Typed custom fields object tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts/{account_id} source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts/bulk_create: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Bulk Create Accounts description: 'Create several accounts in one call. Same duplicate-domain rule as `post_apollo_accounts`, applied per record, so a partial success is normal — read the response rather than assuming every row was created. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_accounts_bulk_create responses: '200': description: Successful response content: application/json: schema: type: object properties: created_accounts: type: string description: Accounts created in this request created_accounts[].id: type: string description: Account ID created_accounts[].name: type: string description: Account name created_accounts[].domain: type: string description: Account domain created_accounts[].team_id: type: string description: Team ID created_accounts[].owner_id: type: string description: Owner ID created_accounts[].account_stage_id: type: string description: Account stage ID created_accounts[].phone: type: string description: Phone number created_accounts[].created_at: type: string description: Created timestamp created_accounts[].updated_at: type: string description: Updated timestamp existing_accounts: type: string description: Accounts that already existed (dedupe matches) existing_accounts[].id: type: string description: Account ID existing_accounts[].name: type: string description: Account name existing_accounts[].domain: type: string description: Account domain existing_accounts[].team_id: type: string description: Team ID existing_accounts[].owner_id: type: string description: Owner ID existing_accounts[].account_stage_id: type: string description: Account stage ID existing_accounts[].phone: type: string description: Phone number existing_accounts[].created_at: type: string description: Created timestamp existing_accounts[].updated_at: type: string description: Updated timestamp '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: accounts: type: string description: Array of accounts to create append_label_names: type: string description: Label names to append to each created account run_dedupe: type: boolean description: Enable deduplication. Default false. required: - accounts tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts/bulk_create source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts/bulk_update: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Bulk Update Accounts description: 'Update several accounts in one call, each identified by its Apollo id. Partial success is normal; check the response per record. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_accounts_bulk_update responses: '200': description: Successful response content: application/json: schema: type: object properties: accounts: type: string description: Updated accounts accounts[].id: type: string description: Account ID accounts[].account_stage_id: type: string description: Account stage ID '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: account_ids: type: string description: IDs of accounts to update account_attributes: type: string description: List of account attribute update objects account_attributes[].name: type: string description: Account name account_attributes[].owner_id: type: string description: Owner ID account_attributes[].account_stage_id: type: string description: Account stage ID async: type: boolean description: Run asynchronously. Default false. required: - account_ids - account_attributes tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts/bulk_update source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts/search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Search for Accounts description: Search accounts — the companies saved in this Apollo workspace, as opposed to Apollo's global database. Filter by name, owner, stage and custom fields; page with `page` and `per_page`. Returns `accounts` and `pagination`, plus `breadcrumbs` echoing the filters applied. ⚠️ This workspace is shared by every AIsa caller, so results include records other callers created. To search Apollo's global company database instead, use `post_apollo_mixed_companies_search`. operationId: post_apollo_accounts_search responses: '200': description: Successful response content: application/json: schema: type: object properties: breadcrumbs: type: array items: type: object description: Breadcrumb additionalProperties: true description: Response array partial_results_only: type: boolean description: Response field has_join: type: boolean description: Response field disable_eu_prospecting: type: boolean description: Response field partial_results_limit: type: integer description: Response field pagination: type: object description: Pagination metadata additionalProperties: true accounts: type: array items: type: object description: Account additionalProperties: true description: Response array num_fetch_result: type: object nullable: true description: Fetch-result metadata additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: q_organization_name: type: string description: Organization name query account_stage_ids: type: string description: Filter by account stage IDs account_label_ids: type: string description: Filter by account label IDs sort_by_field: type: string description: Sort field (e.g. account_last_activity_date, account_created_at, account_updated_at) sort_ascending: type: boolean description: Sort ascending page: type: integer description: Page number per_page: type: integer description: Items per page tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts/search source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts/{id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: View an Account description: One saved account by its Apollo id, with its full field set including custom fields and owner. Find the id with `post_apollo_accounts_search`. This reads the shared AIsa workspace, not Apollo's global database — for a company you have not saved, use `get_apollo_organizations_enrich`. operationId: get_apollo_accounts_id parameters: - name: id in: path required: true schema: type: string description: Account ID responses: '200': description: Successful response content: application/json: schema: type: object properties: account: type: object description: Account additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts/{id} source: https://github.com/AIsa-team/aisa-proxy /apollo/accounts/update_owners: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update Account Owner for Multiple Accounts description: 'Reassign the owner of several accounts at once. Owner ids come from `get_apollo_users_search`. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. Reassignment is visible to whoever owned them before.' operationId: post_apollo_accounts_update_owners parameters: - name: account_ids[] in: query required: true schema: type: string description: Account IDs - name: owner_id in: query required: true schema: type: string description: New owner ID responses: '200': description: Successful response content: application/json: schema: type: object properties: accounts: type: string description: Updated accounts accounts[].id: type: string description: Account ID accounts[].owner_id: type: string description: Owner ID accounts[].crm_owner_id: type: string description: CRM owner ID '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/accounts/update_owners source: https://github.com/AIsa-team/aisa-proxy /apollo/account_stages: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: List Account Stages description: 'The account stages configured in this workspace, as an `account_stages` array of `id`, `name`, `display_name`, `display_order`, `category` and `is_meeting_set`. Takes no parameters. Call it before creating or updating accounts: stage fields expect a stage id, and the set is workspace-specific rather than a fixed enum.' operationId: get_apollo_account_stages responses: '200': description: Successful response content: application/json: schema: type: object properties: account_stages: type: string description: Account stages list account_stages[].id: type: string description: Stage ID account_stages[].team_id: type: string description: Team ID account_stages[].display_name: type: string description: Display name account_stages[].name: type: string description: Name account_stages[].display_order: type: integer description: Display order account_stages[].default_exclude_for_leadgen: type: boolean description: Default exclude for leadgen account_stages[].category: type: string description: Category account_stages[].is_meeting_set: type: boolean description: Is meeting set '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/account_stages source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Create a Contact description: 'Create a contact — a person saved into this workspace. Search with `post_apollo_contacts_search` first to avoid duplicates, which Apollo does not reject here the way it rejects duplicate account domains. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. To look someone up without saving them, use `post_apollo_people_match`.' operationId: post_apollo_contacts responses: '200': description: Successful response content: application/json: schema: type: object properties: contact: type: object description: Created contact additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: first_name: type: string description: First name last_name: type: string description: Last name organization_name: type: string description: Organization name title: type: string description: Title account_id: type: string description: Account ID email: type: string description: Email website_url: type: string description: Website URL label_names: type: string description: Labels to set on the contact contact_stage_id: type: string description: Contact stage ID present_raw_address: type: string description: Raw address direct_phone: type: string description: Direct phone corporate_phone: type: string description: Corporate phone mobile_phone: type: string description: Mobile phone home_phone: type: string description: Home phone other_phone: type: string description: Other phone typed_custom_fields: type: object description: Typed custom fields object run_dedupe: type: boolean description: Enable deduplication. Default false. tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts/{contact_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: View a Contact description: One saved contact by its Apollo id, with the full field set including custom fields, owner and stage. Find the id with `post_apollo_contacts_search`. Reads the shared workspace, not Apollo's global database. operationId: get_apollo_contacts_contact_id parameters: - name: contact_id in: path required: true schema: type: string description: Contact ID responses: '200': description: Successful response content: application/json: schema: type: object properties: contact: type: object description: Contact object contact.id: type: string description: Contact ID contact.first_name: type: string description: First name contact.last_name: type: string description: Last name contact.organization_name: type: string description: Organization name contact.title: type: string description: Title contact.email: type: string description: Email contact.phone_numbers: type: string description: Phone numbers contact.phone_numbers[].raw_number: type: string description: Raw number contact.phone_numbers[].sanitized_number: type: string description: Sanitized number contact.owner_id: type: string description: Owner ID contact.account_id: type: string description: Account ID contact.present_raw_address: type: string description: Raw address contact.linkedin_url: type: string description: LinkedIn URL contact.updated_at: type: string description: Updated timestamp '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/{contact_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update a Contact description: 'Update one contact by its Apollo id. Send only the fields you intend to change. Stage fields expect an id from `get_apollo_contact_stages`. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: patch_apollo_contacts_contact_id parameters: - name: contact_id in: path required: true schema: type: string description: Contact ID responses: '200': description: Successful response content: application/json: schema: type: object properties: contact: type: object description: Updated contact contact.id: type: string description: Contact ID contact.first_name: type: string description: First name contact.last_name: type: string description: Last name contact.email: type: string description: Email contact.title: type: string description: Title contact.organization_name: type: string description: Organization name contact.owner_id: type: string description: Owner ID contact.account_id: type: string description: Account ID contact.present_raw_address: type: string description: Raw address '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: first_name: type: string description: First name last_name: type: string description: Last name organization_name: type: string description: Organization name title: type: string description: Title account_id: type: string description: Account ID email: type: string description: Email website_url: type: string description: Website URL label_names: type: string description: Labels to set on the contact contact_stage_id: type: string description: Contact stage ID present_raw_address: type: string description: Raw address direct_phone: type: string description: Direct phone corporate_phone: type: string description: Corporate phone mobile_phone: type: string description: Mobile phone home_phone: type: string description: Home phone other_phone: type: string description: Other phone typed_custom_fields: type: object description: Typed custom fields object tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/{contact_id} source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts/bulk_create: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Bulk Create Contacts description: 'Create several contacts in one call. Partial success is normal; read the response per record rather than assuming every row landed. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_contacts_bulk_create responses: '200': description: Successful response content: application/json: schema: type: object properties: created_contacts: type: string description: Contacts created in this request created_contacts[].id: type: string description: Contact ID created_contacts[].first_name: type: string description: First name created_contacts[].last_name: type: string description: Last name created_contacts[].organization_name: type: string description: Organization name created_contacts[].title: type: string description: Title created_contacts[].owner_id: type: string description: Owner ID created_contacts[].account_id: type: string description: Account ID created_contacts[].email: type: string description: Email created_contacts[].phone_numbers: type: string description: Phone numbers created_contacts[].typed_custom_fields: type: object description: Typed custom fields object created_contacts[].updated_at: type: string description: Updated timestamp existing_contacts: type: string description: Contacts that already existed (dedupe matches) existing_contacts[].id: type: string description: Contact ID existing_contacts[].first_name: type: string description: First name existing_contacts[].last_name: type: string description: Last name existing_contacts[].organization_name: type: string description: Organization name existing_contacts[].title: type: string description: Title existing_contacts[].owner_id: type: string description: Owner ID existing_contacts[].account_id: type: string description: Account ID existing_contacts[].email: type: string description: Email existing_contacts[].phone_numbers: type: string description: Phone numbers existing_contacts[].typed_custom_fields: type: object description: Typed custom fields object existing_contacts[].updated_at: type: string description: Updated timestamp '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: contacts: type: string description: Array of contacts to create append_label_names: type: string description: Label names to append to each created contact run_dedupe: type: boolean description: Enable deduplication. Default false. required: - contacts tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/bulk_create source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts/bulk_update: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Bulk Update Contacts description: 'Update several contacts in one call, each identified by its Apollo id. Partial success is normal. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_contacts_bulk_update responses: '200': description: Successful response content: application/json: schema: type: object properties: contacts: type: string description: Updated contacts contacts[].id: type: string description: Contact ID contacts[].first_name: type: string description: First name contacts[].last_name: type: string description: Last name contacts[].email: type: string description: Email contacts[].title: type: string description: Title contacts[].organization_name: type: string description: Organization name contacts[].owner_id: type: string description: Owner ID contacts[].account_id: type: string description: Account ID contacts[].present_raw_address: type: string description: Raw address contacts[].linkedin_url: type: string description: LinkedIn URL contacts[].updated_at: type: string description: Updated timestamp '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/bulk_update source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts/search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Search for Contacts description: Search contacts — the people saved in this Apollo workspace. Filter by name, title, account, owner, stage and custom fields; page with `page` and `per_page`. Returns `contacts` with `id`, `name`, `first_name`, `last_name`, `title`, `organization_name`, `linkedin_url`, `contact_stage_id`, `owner_id`, `person_id` and `source`, alongside `pagination` and `model_ids`. ⚠️ The workspace is shared across AIsa callers, so results include contacts other callers created. To find people who are not saved here, use `post_apollo_mixed_people_api_search`. operationId: post_apollo_contacts_search responses: '200': description: Successful response content: application/json: schema: type: object properties: contacts: type: array items: type: object description: Contact additionalProperties: true description: Response array breadcrumbs: type: array items: type: object description: Breadcrumb additionalProperties: true description: Response array partial_results_only: type: boolean description: Response field has_join: type: boolean description: Response field disable_eu_prospecting: type: boolean description: Response field partial_results_limit: type: integer description: Response field pagination: type: object description: Pagination metadata additionalProperties: true num_fetch_result: type: object nullable: true description: Fetch-result metadata additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: q_keywords: type: string description: Keyword query contact_stage_ids: type: string description: Filter by contact stage IDs contact_label_ids: type: string description: Filter by contact label IDs sort_by_field: type: string description: Sort field (e.g. contact_last_activity_date, contact_created_at, contact_updated_at) sort_ascending: type: boolean description: Sort ascending. Default false. per_page: type: integer description: Items per page page: type: integer description: Page number tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/search source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts/update_stages: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update Contact Stage for Multiple Contacts description: 'Move several contacts to a different stage at once. The stage id must come from `get_apollo_contact_stages` — stages are workspace-specific rather than a fixed enum, and an unknown id is rejected. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. Stage changes can trigger workspace automations.' operationId: post_apollo_contacts_update_stages parameters: - name: contact_ids[] in: query required: true schema: type: string description: Contact IDs - name: contact_stage_id in: query required: true schema: type: string description: New contact stage ID responses: '200': description: Successful response content: application/json: schema: type: object properties: contacts: type: string description: Updated contacts contacts[].id: type: string description: Contact ID contacts[].first_name: type: string description: First name contacts[].last_name: type: string description: Last name contacts[].contact_stage_id: type: string description: Contact stage ID contacts[].owner_id: type: string description: Owner ID contacts[].email: type: string description: Email contacts[].organization_name: type: string description: Organization name '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/update_stages source: https://github.com/AIsa-team/aisa-proxy /apollo/contacts/update_owners: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update Contact Owner for Multiple Contacts description: 'Reassign the owner of several contacts at once. Owner ids come from `get_apollo_users_search`. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_contacts_update_owners parameters: - name: contact_ids[] in: query required: true schema: type: string description: Contact IDs - name: owner_id in: query required: true schema: type: string description: New owner ID responses: '200': description: Successful response content: application/json: schema: type: object properties: contacts: type: string description: Updated contacts contacts[].id: type: string description: Contact ID contacts[].owner_id: type: string description: Owner ID contacts[].crm_owner_id: type: string description: CRM owner ID '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contacts/update_owners source: https://github.com/AIsa-team/aisa-proxy /apollo/contact_stages: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: List Contact Stages description: 'The contact stages configured in this workspace, as a `contact_stages` array of `id`, `name`, `display_name`, `display_order`, `category` and `is_meeting_set`. Takes no parameters. Call it before setting a contact''s stage: `post_apollo_contacts_update_stages` expects a stage id from this list, and the set is workspace-specific.' operationId: get_apollo_contact_stages responses: '200': description: Successful response content: application/json: schema: type: object properties: contact_stages: type: string description: Contact stages list contact_stages[].id: type: string description: Stage ID contact_stages[].team_id: type: string description: Team ID contact_stages[].display_name: type: string description: Display name contact_stages[].name: type: string description: Name contact_stages[].display_order: type: integer description: Display order contact_stages[].ignore_trigger_override: type: boolean description: Ignore trigger override contact_stages[].category: type: string description: Category contact_stages[].is_meeting_set: type: boolean description: Is meeting set '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/contact_stages source: https://github.com/AIsa-team/aisa-proxy /apollo/opportunities: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Create Deal description: 'Create a deal. Stage ids come from `get_apollo_opportunity_stages`, and the account it belongs to comes from `post_apollo_accounts_search`. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. Deals feed the workspace''s forecast, so a test record distorts numbers other people read.' operationId: post_apollo_opportunities responses: '200': description: Successful response content: application/json: schema: type: object properties: opportunity: type: object description: Created opportunity additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Deal name owner_id: type: string description: Owner ID account_id: type: string description: Account ID amount: type: number description: Deal amount opportunity_stage_id: type: string description: Deal stage ID closed_date: type: string description: Closed date (date string) typed_custom_fields: type: object description: Typed custom fields object required: - name tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/opportunities source: https://github.com/AIsa-team/aisa-proxy /apollo/opportunities/search: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: List All Deals description: 'Search deals in this workspace. Filter by owner, stage, amount and close date; page with `page` and `per_page`. Returns `opportunities` with `id`, `name`, `amount`, `closed_date`, `stage_name`, `opportunity_stage_id`, `account_id`, `owner_id`, `is_closed`, `is_won` and `description`. ⚠️ Shared workspace: results include deals other AIsa callers created.' operationId: get_apollo_opportunities_search parameters: - name: sort_by_field in: query required: false schema: type: string description: Sort field - name: page in: query required: false schema: type: integer description: Page number - name: per_page in: query required: false schema: type: integer description: Items per page responses: '200': description: Successful response content: application/json: schema: type: object properties: opportunities: type: string description: Opportunities list opportunities[].id: type: string description: Opportunity ID opportunities[].owner_id: type: string description: Owner ID opportunities[].account_id: type: string description: Account ID opportunities[].amount: type: number description: Amount opportunities[].name: type: string description: Name opportunities[].opportunity_stage_id: type: string description: Stage ID opportunities[].is_closed: type: boolean description: Is closed opportunities[].is_won: type: boolean description: Is won opportunities[].created_at: type: string description: Created timestamp pagination: type: object description: Pagination object pagination.page: type: integer description: Page number pagination.per_page: type: integer description: Items per page pagination.total_entries: type: integer description: Total entries pagination.total_pages: type: integer description: Total pages '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/opportunities/search source: https://github.com/AIsa-team/aisa-proxy /apollo/opportunities/{opportunity_id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: View Deal description: One deal by its Apollo id, with the full field set. Find the id with `get_apollo_opportunities_search`. operationId: get_apollo_opportunities_opportunity_id parameters: - name: opportunity_id in: path required: true schema: type: string description: Opportunity ID responses: '200': description: Successful response content: application/json: schema: type: object properties: opportunity: type: object description: Opportunity object opportunity.id: type: string description: Opportunity ID opportunity.owner_id: type: string description: Owner ID opportunity.account_id: type: string description: Account ID opportunity.amount: type: number description: Amount opportunity.name: type: string description: Name opportunity.opportunity_stage_id: type: string description: Stage ID opportunity.is_closed: type: boolean description: Is closed opportunity.is_won: type: boolean description: Is won opportunity.created_at: type: string description: Created timestamp '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/opportunities/{opportunity_id} source: https://github.com/AIsa-team/aisa-proxy patch: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update Deal description: 'Update one deal by its Apollo id — amount, close date, stage or owner. Send only what changes. Moving a deal to a closed stage is what marks it won or lost, since `is_won` and `is_closed` come from the stage rather than being set directly. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: patch_apollo_opportunities_opportunity_id parameters: - name: opportunity_id in: path required: true schema: type: string description: Opportunity ID responses: '200': description: Successful response content: application/json: schema: type: object properties: opportunity: type: object description: Updated opportunity additionalProperties: true '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: owner_id: type: string description: Owner ID name: type: string description: Opportunity name amount: type: number description: Amount opportunity_stage_id: type: string description: Stage ID closed_date: type: string description: Closed date (date string) typed_custom_fields: type: object description: Typed custom fields object tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/opportunities/{opportunity_id} source: https://github.com/AIsa-team/aisa-proxy /apollo/opportunity_stages: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: List Deal Stages description: 'The deal stages configured in this workspace, as an `opportunity_stages` array of `id`, `name`, `display_order`, `probability`, `is_won`, `is_closed`, `forecast_category_cd` and `type`. Takes no parameters. Call it before creating or moving a deal: stage fields expect an id from this list, and `probability` is what turns a stage into a forecast number.' operationId: get_apollo_opportunity_stages responses: '200': description: Successful response content: application/json: schema: type: object properties: opportunity_stages: type: string description: Opportunity stages list opportunity_stages[].id: type: string description: Stage ID opportunity_stages[].team_id: type: string description: Team ID opportunity_stages[].name: type: string description: Name opportunity_stages[].display_order: type: integer description: Display order opportunity_stages[].forecast_category_cd: type: string description: Forecast category code opportunity_stages[].is_won: type: boolean description: Is won opportunity_stages[].is_closed: type: boolean description: Is closed opportunity_stages[].probability: type: number description: Probability opportunity_stages[].description: type: string description: Description opportunity_stages[].opportunity_pipeline_id: type: string description: Opportunity pipeline ID opportunity_stages[].type: type: string description: Type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/opportunity_stages source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_campaigns/search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Search for Sequences description: 'Search email sequences in this workspace. Returns `emailer_campaigns` with `pagination` and `breadcrumbs`. Use it to find a sequence id before adding contacts to it or changing its state. ⚠️ Sequences here are shared: activating or archiving one affects every AIsa caller, and a live sequence sends real email from the workspace''s connected accounts.' operationId: post_apollo_emailer_campaigns_search parameters: - name: q_name in: query required: false schema: type: string description: Keywords to match sequence names. - name: page in: query required: false schema: type: integer description: Page number. - name: per_page in: query required: false schema: type: integer description: Results per page. responses: '200': description: Successful response content: application/json: schema: type: object properties: emailer_campaigns: type: array items: type: string description: Sequence records (when returned). pagination: type: object description: Pagination metadata (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_campaigns/search source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_campaigns/{sequence_id}/add_contact_ids: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Add Contacts to a Sequence description: 'Add contacts to an email sequence. ⚠️ This is the endpoint that causes real email to be sent: once added to an active sequence, contacts start receiving its steps from the workspace''s connected mailboxes. Get the sequence id from `post_apollo_emailer_campaigns_search` and confirm its state before adding anyone. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. Sending cannot be recalled once a step goes out.' operationId: post_apollo_emailer_campaigns_add_contact_ids parameters: - name: sequence_id in: path required: true schema: type: string description: Sequence (emailer campaign) ID. - name: emailer_campaign_id in: query required: true schema: type: string description: Sequence ID (same as sequence_id). - name: contact_ids[] in: query required: false schema: type: array items: type: string description: Contact IDs to add. Provide either contact_ids[] or label_names[] (or both). - name: label_names[] in: query required: false schema: type: array items: type: string description: Label names for contacts to add. Provide either label_names[] or contact_ids[] (or both). - name: send_email_from_email_account_id in: query required: true schema: type: string description: Email account ID (or IDs) to send from. - name: send_email_from_email_address in: query required: false schema: type: string description: Optional from-address alias. - name: sequence_no_email in: query required: false schema: type: boolean description: Allow contacts without email. - name: sequence_unverified_email in: query required: false schema: type: boolean description: Allow contacts with unverified email. - name: sequence_job_change in: query required: false schema: type: boolean description: Allow contacts with job change. - name: sequence_active_in_other_campaigns in: query required: false schema: type: boolean description: Allow contacts active in other sequences. - name: sequence_finished_in_other_campaigns in: query required: false schema: type: boolean description: Allow contacts finished in other sequences. responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the add succeeded (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_campaigns/{sequence_id}/add_contact_ids source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_campaigns/remove_or_stop_contact_ids: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update Contact Status in a Sequence description: 'Remove contacts from a sequence, or stop it for them without removing them. Use it to halt sending to someone who replied or asked to stop. Already-sent messages are unaffected — this only prevents future steps. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_emailer_campaigns_remove_or_stop_contact_ids parameters: - name: emailer_campaign_ids[] in: query required: true schema: type: array items: type: string description: Sequence IDs. - name: contact_ids[] in: query required: true schema: type: array items: type: string description: Contact IDs. - name: mode in: query required: true schema: type: string description: 'One of: mark_as_finished, remove, stop.' responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the update succeeded (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_campaigns/remove_or_stop_contact_ids source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_campaigns/{sequence_id}/approve: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Activate a Sequence description: 'Activate a sequence, which makes it start sending. ⚠️ Every contact already in it begins receiving steps from the workspace''s connected mailboxes. Check membership with `post_apollo_emailer_campaigns_search` and mailbox health with `get_apollo_email_accounts` first. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation. Activation affects everyone using this workspace.' operationId: post_apollo_emailer_campaigns_sequence_id_approve parameters: - name: sequence_id in: path required: true schema: type: string description: Sequence ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: emailer_campaign: type: object description: Sequence object (when returned). emailer_steps: type: array items: type: string description: Sequence steps (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_campaigns/{sequence_id}/approve source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_campaigns/{sequence_id}/abort: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Deactivate a Sequence description: 'Deactivate a sequence so it stops sending. Contacts stay in it and already-sent messages are unaffected; only future steps are halted. Use it as the stop switch when something is going wrong. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_emailer_campaigns_sequence_id_abort parameters: - name: sequence_id in: path required: true schema: type: string description: Sequence ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: emailer_campaign: type: object description: Sequence object (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_campaigns/{sequence_id}/abort source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_campaigns/{sequence_id}/archive: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Archive a Sequence description: 'Archive a sequence, removing it from the active list while keeping its history. Archiving does not stop an active sequence on its own — deactivate it with `post_apollo_emailer_campaigns_sequence_id_abort` first if it is still sending. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_emailer_campaigns_sequence_id_archive parameters: - name: sequence_id in: path required: true schema: type: string description: Sequence ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: emailer_campaign: type: object description: Archived sequence object (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_campaigns/{sequence_id}/archive source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_messages/search: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Search for Outreach Emails description: Search individual outreach emails already sent or scheduled from this workspace. Returns `emailer_messages` alongside `emailer_steps`, which say where in a sequence each message sits. Use it to see what actually went out. For per-message engagement — opens, clicks, replies — use `get_apollo_emailer_messages_id_activities`. operationId: get_apollo_emailer_messages_search parameters: - name: emailer_message_stats[] in: query required: false schema: type: array items: type: string description: Filter by message stats (e.g., open, click). - name: emailer_message_reply_classes[] in: query required: false schema: type: array items: type: string description: Filter by reply classes. - name: user_ids[] in: query required: false schema: type: array items: type: string description: Filter by user IDs. - name: email_account_id_and_aliases in: query required: false schema: type: string description: Filter by email account and aliases. - name: emailer_campaign_ids[] in: query required: false schema: type: array items: type: string description: Only include these sequence IDs. - name: not_emailer_campaign_ids[] in: query required: false schema: type: array items: type: string description: Exclude these sequence IDs. - name: page in: query required: false schema: type: integer description: Page number. - name: per_page in: query required: false schema: type: integer description: Results per page. responses: '200': description: Successful response content: application/json: schema: type: object properties: emailer_messages: type: array items: type: string description: Outreach emails (when returned). pagination: type: object description: Pagination metadata (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_messages/search source: https://github.com/AIsa-team/aisa-proxy /apollo/emailer_messages/{id}/activities: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Check Email Stats description: 'Engagement events for one sent email: opens, clicks, replies and bounces, with timestamps. Get the message id from `get_apollo_emailer_messages_search`. Use this rather than inferring engagement from the message record itself, which carries delivery state but not recipient behaviour.' operationId: get_apollo_emailer_messages_id_activities parameters: - name: id in: path required: true schema: type: string description: Emailer message ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: emailer_message: type: object description: Email object (when returned). activities: type: array items: type: string description: Activity events (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/emailer_messages/{id}/activities source: https://github.com/AIsa-team/aisa-proxy /apollo/tasks: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Create a Task description: 'Create a task assigned to a workspace user, optionally linked to a contact or account. Owner ids come from `get_apollo_users_search`. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_tasks responses: '200': description: Successful response content: application/json: schema: type: object properties: task: type: object description: Created task (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: Task owner user ID. contact_id: type: string description: Contact ID. type: type: string description: Task type. priority: type: string description: 'Task priority (default: medium).' status: type: string description: Task status. due_at: type: string description: ISO 8601 due datetime. title: type: string description: Optional title. required: - user_id - contact_id - type - status - due_at tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/tasks source: https://github.com/AIsa-team/aisa-proxy /apollo/tasks/bulk_create: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Bulk Create Tasks description: 'Create several tasks in one call. Partial success is normal; read the response per record. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_tasks_bulk_create responses: '200': description: Successful response content: application/json: schema: type: object properties: tasks: type: array items: type: string description: Created tasks (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: Task owner user ID. contact_ids: type: array items: type: string description: Contact IDs. type: type: string description: Task type. priority: type: string description: 'Task priority (default: medium).' status: type: string description: Task status. due_at: type: string description: ISO 8601 due datetime. title: type: string description: Optional title. required: - user_id - contact_ids - type - status - due_at tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/tasks/bulk_create source: https://github.com/AIsa-team/aisa-proxy /apollo/tasks/search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Search for Tasks description: 'Search tasks in this workspace. Returns `tasks` with `pagination`, `breadcrumbs`, `faceting` and `pipeline_total`. ⚠️ Shared workspace: results include tasks other AIsa callers created.' operationId: post_apollo_tasks_search parameters: - name: sort_by_field in: query required: false schema: type: string description: Sort field. - name: open_factor_names[] in: query required: false schema: type: array items: type: string description: Optional open factors. - name: page in: query required: false schema: type: integer description: Page number. - name: per_page in: query required: false schema: type: integer description: Results per page. responses: '200': description: Successful response content: application/json: schema: type: object properties: tasks: type: array items: type: string description: Tasks (when returned). pagination: type: object description: Pagination metadata (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/tasks/search source: https://github.com/AIsa-team/aisa-proxy /apollo/reports/sync_report: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Query Analytics Report description: Run an analytics report and get its rows back. Despite being a POST this reads rather than writes; the method reflects that the query goes in the body. Reports cover the shared workspace, so figures include other callers' activity. operationId: post_apollo_reports_sync_report responses: '200': description: Successful response content: application/json: schema: type: object properties: report: type: object description: Report result (shape depends on request). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: metrics: type: array items: type: string description: Metrics to compute. group_by: type: array items: type: string description: Dimensions to group by. pivot_group_by: type: array items: type: string description: Optional pivot dimensions. sorts: type: array items: type: string description: Sort specs. filters: type: string description: Filter specs. date_range: type: object description: Date range filter (when supported). tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/reports/sync_report source: https://github.com/AIsa-team/aisa-proxy /apollo/phone_calls: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Create Call Records description: 'Log a call record against a contact. This writes history into Apollo — it does not place a call and does not connect to any telephony system. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_phone_calls parameters: - name: logged in: query required: false schema: type: boolean description: Whether to create an individual record. - name: user_id[] in: query required: false schema: type: array items: type: string description: Caller user IDs. - name: contact_id in: query required: false schema: type: string description: Contact ID. - name: account_id in: query required: false schema: type: string description: Account ID. - name: to_number in: query required: false schema: type: string description: Dialed phone number. - name: from_number in: query required: false schema: type: string description: Caller phone number. - name: status in: query required: false schema: type: string description: Call status. - name: start_time in: query required: false schema: type: string description: ISO 8601 start time. - name: end_time in: query required: false schema: type: string description: ISO 8601 end time. - name: duration in: query required: false schema: type: integer description: Duration in seconds. - name: phone_call_purpose_id in: query required: false schema: type: string description: Purpose ID. - name: phone_call_outcome_id in: query required: false schema: type: string description: Outcome ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: phone_call: type: object description: Call record (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/phone_calls source: https://github.com/AIsa-team/aisa-proxy /apollo/phone_calls/search: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Search for Calls description: Search logged calls in this workspace. Returns `phone_calls` with `pagination`, `breadcrumbs`, `faceting` and `pipeline_total`. These are call records written into Apollo, not telephony data — a call only appears here if something logged it. operationId: get_apollo_phone_calls_search parameters: - name: date_range[max] in: query required: false schema: type: string description: Upper bound for call date range (YYYY-MM-DD). - name: date_range[min] in: query required: false schema: type: string description: Lower bound for call date range (YYYY-MM-DD). - name: duration[max] in: query required: false schema: type: integer description: Upper bound for duration (seconds). - name: duration[min] in: query required: false schema: type: integer description: Lower bound for duration (seconds). - name: inbound in: query required: false schema: type: string description: Inbound or outbound. - name: user_ids[] in: query required: false schema: type: array items: type: string description: User IDs. - name: contact_label_ids[] in: query required: false schema: type: array items: type: string description: Contact label IDs. - name: phone_call_purpose_ids[] in: query required: false schema: type: array items: type: string description: Purpose IDs. - name: phone_call_outcome_ids[] in: query required: false schema: type: array items: type: string description: Outcome IDs. - name: q_keywords in: query required: false schema: type: string description: Keyword filter. - name: page in: query required: false schema: type: integer description: Page number. - name: per_page in: query required: false schema: type: integer description: Results per page. responses: '200': description: Successful response content: application/json: schema: type: object properties: phone_calls: type: array items: type: string description: Calls (when returned). pagination: type: object description: Pagination metadata (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/phone_calls/search source: https://github.com/AIsa-team/aisa-proxy /apollo/phone_calls/{id}: put: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Update Call Records description: 'Update a logged call by its id — outcome, notes, duration. Send only what changes. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: put_apollo_phone_calls_id parameters: - name: id in: path required: true schema: type: string description: Call record ID. - name: logged in: query required: false schema: type: boolean description: Whether to create an individual record. - name: user_id[] in: query required: false schema: type: array items: type: string description: Caller user IDs. - name: contact_id in: query required: false schema: type: string description: Contact ID. - name: account_id in: query required: false schema: type: string description: Account ID. - name: to_number in: query required: false schema: type: string description: Dialed phone number. - name: from_number in: query required: false schema: type: string description: Caller phone number. - name: status in: query required: false schema: type: string description: Call status. - name: start_time in: query required: false schema: type: string description: ISO 8601 start time. - name: end_time in: query required: false schema: type: string description: ISO 8601 end time. - name: duration in: query required: false schema: type: integer description: Duration in seconds. - name: phone_call_purpose_id in: query required: false schema: type: string description: Purpose ID. - name: phone_call_outcome_id in: query required: false schema: type: string description: Outcome ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: phone_call: type: object description: Updated call record (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/phone_calls/{id} source: https://github.com/AIsa-team/aisa-proxy /apollo/usage_stats/api_usage_stats: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: View API Usage Stats and Rate Limits description: 'Current API usage and rate-limit state for the Apollo key in use: consumption per window and how much headroom is left. Despite being a POST this reads rather than writes. ⚠️ The limits are the AIsa account''s, shared across all callers — one caller exhausting a window affects everyone. Check it when calls start failing on rate limits rather than on their arguments.' operationId: post_apollo_usage_stats_api_usage_stats responses: '200': description: Successful response content: application/json: schema: type: object properties: api_usage_stats: type: object description: Usage stats and rate limits (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/usage_stats/api_usage_stats source: https://github.com/AIsa-team/aisa-proxy /apollo/users/search: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get a List of Users description: The user accounts in this Apollo workspace, as a `users` array with `id`, `first_name`, `last_name`, `email`, `title`, `team_id` and the various credit limits, plus `pagination`. Use it to resolve an `owner_id` seen on a contact, account or deal into a person. ⚠️ This exposes the workspace's own members and their email addresses, and the workspace belongs to AIsa rather than to the caller. Expect it to be slow — measured at roughly 16 seconds. operationId: get_apollo_users_search parameters: - name: page in: query required: false schema: type: integer description: Page number. - name: per_page in: query required: false schema: type: integer description: Results per page. responses: '200': description: Successful response content: application/json: schema: type: object properties: users: type: array items: type: string description: Users (when returned). pagination: type: object description: Pagination metadata (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/users/search source: https://github.com/AIsa-team/aisa-proxy /apollo/email_accounts: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get a List of Email Accounts description: 'The mailboxes connected to this workspace, as an `email_accounts` array with sending limits and per-account state. Takes no parameters. Check it before activating a sequence: a sequence with no healthy connected mailbox will not send.' operationId: get_apollo_email_accounts responses: '200': description: Successful response content: application/json: schema: type: object properties: email_accounts: type: array items: type: string description: Email accounts (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/email_accounts source: https://github.com/AIsa-team/aisa-proxy /apollo/labels: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get a List of All Lists description: 'The lists (labels) defined in this workspace. The HTTP response is a bare JSON array; called as an MCP tool it arrives wrapped as `{"result": [...]}`, because a top-level array is not a valid structured result. Takes no parameters. Empty is a normal answer when no lists exist. Use it to resolve a list name into the id that contact and account filters expect.' operationId: get_apollo_labels responses: '200': description: Successful response content: application/json: schema: type: object properties: '[]': type: array items: type: string description: List objects (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/labels source: https://github.com/AIsa-team/aisa-proxy /apollo/typed_custom_fields: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get a List of All Custom Fields description: 'The custom fields defined in this workspace, as a `typed_custom_fields` array of `id`, `name`, `system_name`, `type`, `modality`, `picklist_options` and CRM mapping state. Takes no parameters. Call it before writing a custom field: the field key and, for picklists, the allowed values are workspace-specific, and a wrong value is rejected rather than coerced.' operationId: get_apollo_typed_custom_fields responses: '200': description: Successful response content: application/json: schema: type: object properties: typed_custom_fields: type: array items: type: string description: Custom field definitions (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/typed_custom_fields source: https://github.com/AIsa-team/aisa-proxy /apollo/fields: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get a List of Fields description: Every field Apollo exposes, standard and custom, as `fields` (roughly 323 entries with `id`, `field_name`, `label`, `type`, `category`, `modality`, `description` and `example`) plus `field_groups` describing how they are organised. Takes no parameters. This is the reference for what can be filtered or written anywhere else in the API. For custom fields alone, `get_apollo_typed_custom_fields` is much smaller. operationId: get_apollo_fields responses: '200': description: Successful response content: application/json: schema: type: object properties: fields: type: array items: type: string description: Field definitions (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/fields source: https://github.com/AIsa-team/aisa-proxy post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Create a Custom Field description: 'Create a custom field. ⚠️ This changes the workspace''s schema rather than its data: the field appears on every record of that modality, for every caller, and removing it later is not something this API offers. Check `get_apollo_typed_custom_fields` first — the field you want may already exist. Writes land in the AIsa workspace, which every caller shares: the record becomes visible and editable by others, and there is no per-caller isolation.' operationId: post_apollo_fields responses: '200': description: Successful response content: application/json: schema: type: object properties: typed_custom_fields: type: array items: type: string description: Created field(s) (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: object properties: label: type: string description: Field label. modality: type: string description: Entity modality (e.g., contact). type: type: string description: Field type (e.g., textarea). meta: type: object description: Additional field config. tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/fields source: https://github.com/AIsa-team/aisa-proxy /apollo/notes: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get a List of Notes description: Notes attached to workspace records. ⚠️ At least one filter is required — calling it bare returns HTTP 400 with "At least one argument is required". Pass one of `contact_id`, `account_id`, `opportunity_id`, `calendar_event_id`, `conversation_id`, `conversation_ids`, `contact_ids` or a `start_date`. The spec marks every one of them optional individually, which is true only in the sense that no single one is mandatory. operationId: get_apollo_notes parameters: - name: contact_id in: query required: false schema: type: string description: Filter by a contact ID. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: account_id in: query required: false schema: type: string description: Filter by an account ID. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: opportunity_id in: query required: false schema: type: string description: Filter by an opportunity ID. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: calendar_event_id in: query required: false schema: type: string description: Filter by a calendar event ID. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: conversation_id in: query required: false schema: type: string description: Filter by a conversation ID. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: conversation_ids in: query required: false schema: type: array items: type: string description: Filter by conversation IDs. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: contact_ids in: query required: false schema: type: array items: type: string description: Filter by contact IDs. At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: start_date in: query required: false schema: type: string description: Only include notes created on/after this date (when supported). At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: page in: query required: false schema: type: integer description: Page number (when supported). At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". - name: per_page in: query required: false schema: type: integer description: Results per page (when supported). At least one filter is required on this endpoint; calling it with none returns HTTP 400 "At least one argument is required". responses: '200': description: Successful response content: application/json: schema: type: object properties: notes: type: array items: type: string description: Notes (when returned). pagination: type: object description: Pagination metadata (when returned). '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - Sales Intelligence x-x402: path: /apis/v2/apollo/notes source: https://github.com/AIsa-team/aisa-proxy /byteplus/web-search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.00528 cost_tier: low tags: - Web & News Search summary: AI-oriented real-time web search. description: Run a real-time web search built for AI agents and return a ranked list of titled results with links and snippets. `Query` is required; narrow the result set with `Count` (≤ 20), `Filter` (restrict to `Sites` or exclude `BlockHosts`), `Language`, and `TimeRange`. The response wraps `ResponseMetadata.RequestId` and a `Result` list of web results. Use it for RAG retrieval augmentation, competitive/PR monitoring, fact-checking, and content sourcing; pair each result URL with `post_byteplus_fetch` to pull full page content. Billed at a flat $0.00528 per successful call; failed requests are not charged. requestBody: required: true content: application/json: schema: type: object properties: Query: type: string description: The search query. Required. Max 400 characters; the upstream engine also effectively caps around 50 words. example: OpenAI news maxLength: 400 Count: type: integer description: Number of results to return. Optional; default 10, maximum 20. maximum: 20 example: 10 default: 10 Filter: type: object description: Optional result filter. Both fields are pipe-separated strings of full domains (max 5 each). properties: Sites: type: string description: Restrict results to these full domains. Pipe-separated, max 5, e.g. "bytedance.com|byteplus.com". (Sending an array returns 10400 Invalid Parameter.) example: bytedance.com|byteplus.com BlockHosts: type: string description: Exclude results from these full domains. Pipe-separated, max 5, e.g. "reddit.com|quora.com". example: reddit.com|quora.com Language: type: string description: Optional language hint in the upstream format, e.g. EN, ZH-HANS, ZH-HANT. example: EN TimeRange: description: 'Optional recency window. One of the named windows OneDay / OneWeek / OneMonth / OneYear, or a custom range "YYYY-MM-DD..YYYY-MM-DD". Omit for no time filter. NOTE: values like "week"/"month" are silently ignored upstream.' oneOf: - type: string enum: - OneDay - OneWeek - OneMonth - OneYear - type: string pattern: ^\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}$ description: Custom range, e.g. 2026-08-01..2026-09-01. example: OneWeek required: - Query examples: basic: summary: Minimal query value: Query: OpenAI news filtered: summary: Query with count, domain filter, language and time window value: Query: OpenAI product launch Count: 10 Filter: Sites: openai.com|bytedance.com BlockHosts: reddit.com Language: EN TimeRange: OneWeek responses: '200': description: Search completed successfully. `Result` holds the ranked web results. content: application/json: schema: type: object properties: ResponseMetadata: type: object description: Upstream request metadata. properties: RequestId: type: string description: Unique identifier for this request. Action: type: string Version: type: string Service: type: string Region: type: string Result: type: object description: Search result payload. properties: ResultCount: type: integer description: Number of web results returned. WebResults: type: array description: Ranked list of web results. items: type: object properties: Id: type: string description: Opaque result id. SortId: type: integer description: 1-based rank of the result. Title: type: string description: Result title. SiteName: type: string description: Source site name (may be empty). Url: type: string description: Result URL. Snippet: type: string description: Short text snippet from the page. Summary: type: string description: Longer summary of the page content. PublishTime: type: string description: Publish time in ISO 8601 (may be empty). PublishTimeUnix: type: integer description: Publish time as Unix seconds (0 if unknown). LogoUrl: type: string description: Signed site logo URL (time-limited). SearchContext: type: object description: Echo of the resolved query context. properties: OriginQuery: type: string SearchType: type: string TimeCost: type: integer description: Upstream processing time in milliseconds. LogId: type: string description: Upstream log id (equals ResponseMetadata.RequestId). Choices: type: array nullable: true description: Reserved; null unless applicable. items: type: object Usage: type: object nullable: true description: Reserved; null unless applicable. examples: success: summary: Live gateway 200 response value: ResponseMetadata: RequestId: 20260904155503A787EC832774768DC56F Action: '' Version: '' Service: '' Region: '' Result: ResultCount: 3 WebResults: - Id: 19b903d59c017bbb04c7832574500d49 SortId: 1 Title: OpenAI News | OpenAI SiteName: OpenAI Url: https://openai.com/news/ Snippet: Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity. Summary: Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity. PublishTime: '2026-09-03T07:50:20+08:00' PublishTimeUnix: 1788393020 LogoUrl: https://p16-bpsearch-sign.ibyteimg.com/... SearchContext: OriginQuery: OpenAI latest news SearchType: web TimeCost: 935 LogId: 20260904155503A787EC832774768DC56F Choices: null Usage: null operationId: post_byteplus_web_search x-x402: path: /apis/v2/byteplus/web-search source: https://github.com/AIsa-team/aisa-proxy /byteplus/fetch: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.00088 cost_tier: low tags: - Web & News Search summary: Fetch clean, structured content for a URL. description: Fetch a single URL and return clean, structured page content — title, body text, and publish time. `Url` is required. The response wraps `ResponseMetadata.RequestId` and a `Result` object with the parsed content. Use it to extract full page content for URLs you already have, typically pairing it with `post_byteplus_web_search` results. Billed at a flat $0.00088 per successful call; failed requests are not charged. requestBody: required: true content: application/json: schema: type: object properties: Url: type: string description: The URL to fetch. Required. example: https://example.com required: - Url examples: basic: summary: Fetch a page value: Url: https://example.com responses: '200': description: Fetch completed successfully. `Result` holds the structured page content. content: application/json: schema: type: object properties: ResponseMetadata: type: object description: Upstream request metadata. properties: RequestId: type: string description: Unique identifier for this request. Action: type: string Version: type: string Service: type: string Region: type: string Result: type: object description: Fetch result payload. properties: Data: type: object description: Structured page content. properties: StatusCode: type: integer description: HTTP status code of the fetched page. Url: type: string description: The fetched URL. Title: type: string description: Page title. PublishTime: type: integer description: Detected publish time as Unix seconds (0 if unknown). ContentText: type: string description: Clean body text extracted from the page. LogId: type: string description: Upstream log id (equals ResponseMetadata.RequestId). examples: success: summary: Live gateway 200 response value: ResponseMetadata: RequestId: 20260904155514D7EA140BFD77348BC3FC Action: '' Version: '' Service: '' Region: '' Result: Data: StatusCode: 200 Url: https://example.com Title: Example Domain PublishTime: 0 ContentText: |- This domain is for use in documentation examples without needing permission. Avoid use in operations. Learn more LogId: 20260904155514D7EA140BFD77348BC3FC operationId: post_byteplus_fetch x-x402: path: /apis/v2/byteplus/fetch source: https://github.com/AIsa-team/aisa-proxy /chat/completions: post: summary: Generate images via Chat Completions description: |- Generate images over the chat route. Request shape matches OpenAI Chat Completions with multimodal content; the response contains `choices[].message.content[]` where each item is `{type: "image", image: ""}`. **Important:** `messages[].content` must be an **array of typed parts**, not a plain string. Passing a string returns `400 invalid_parameter_error` with `Input should be a valid list: messages[*].content`. **Routing note:** `wan2.7-image`, `wan2.7-image-pro`, `seedream-5-0-260128`, and `gpt-image-2` return `400 model_route_not_supported` here — use `/v1/images/generations` for those. operationId: generateImageViaChat requestBody: required: true content: application/json: schema: type: object required: - model - messages properties: model: type: string enum: - seedream-4-5-251128 description: Image-generation model on the chat route. `seedream-4-5-251128` is billed at $0.036 per request. Wan and gpt-image-2 models use `/v1/images/generations` instead. messages: type: array description: 'Conversation messages. Image prompts go in the last user message''s `content` array as `{type: "text"}` parts.' items: type: object required: - role - content properties: role: type: string enum: - system - user - assistant content: type: array description: 'Multimodal parts. For image generation, include at least one `{type: "text"}` part with the prompt.' items: type: object required: - type properties: type: type: string enum: - text - image_url text: type: string description: 'Used when `type: "text"`.' image_url: type: object description: 'Used when `type: "image_url"` (image-to-image use cases).' properties: url: type: string format: uri n: type: integer minimum: 1 description: Number of images to generate. Each image is billed separately; pass `1` unless you want candidates. examples: basic: summary: Single-image prompt (n=1) value: model: seedream-4-5-251128 messages: - role: user content: - type: text text: A cute red panda, ultra-detailed, cinematic lighting n: 1 four_variants: summary: Default 4 candidates for selection value: model: seedream-4-5-251128 messages: - role: user content: - type: text text: A futuristic cyberpunk city, neon lights, rainy night, 8k pro: summary: Higher-fidelity pro model value: model: seedream-4-5-251128 messages: - role: user content: - type: text text: Oil painting of a rolling hillside at sunset, artstation n: 1 image_to_image: summary: Image-to-image (reference + prompt) value: model: seedream-4-5-251128 messages: - role: user content: - type: image_url image_url: url: https://example.com/reference.jpg - type: text text: Transform into an oil painting in the style of Van Gogh n: 1 responses: '200': description: Images generated. Returned as Chat Completion with `message.content[]` image parts. content: application/json: schema: type: object properties: id: type: string example: chatcmpl-fcc86dfd-9424-9523-b0bd-cdf07383bee2 object: type: string example: chat.completion created: type: integer example: 1776495713 model: type: string example: seedream-4-5-251128 choices: type: array description: One entry per generated image. items: type: object properties: index: type: integer nullable: true finish_reason: type: string example: stop message: type: object properties: role: type: string example: assistant content: type: array items: type: object required: - type properties: type: type: string enum: - image image: type: string description: Short-lived URL to the generated image (or base64-encoded data, depending on your account configuration). usage: type: object properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer example: id: chatcmpl-fcc86dfd-9424-9523-b0bd-cdf07383bee2 object: chat.completion created: 1776495713 model: seedream-4-5-251128 choices: - index: 0 finish_reason: stop message: role: assistant content: - type: image image: https://cdn.aisa.one/images/seedream/20260418-abc.png usage: prompt_tokens: 104 completion_tokens: 8 total_tokens: 112 '400': description: 'Invalid request. Most common: `content` passed as a string instead of an array → `"Input should be a valid list: messages[*].content"`.' '401': description: Missing or invalid AIsa API key. '429': description: Rate limit hit. '500': description: Internal error. '502': description: Upstream provider unreachable. tags: - Image Generation servers: - url: https://api.aisa.one/v1 /messages: post: summary: Create a message description: Send a structured conversation to a Claude model and receive a response. Compatible with the Anthropic Messages API. operationId: createMessage security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - model - max_tokens - messages properties: model: type: string description: 'Claude model identifier. Examples: claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001.' example: claude-sonnet-4-6 max_tokens: type: integer description: Maximum number of tokens to generate before stopping. example: 1024 messages: type: array description: Conversation turns. items: type: object required: - role - content properties: role: type: string enum: - user - assistant content: description: String or array of content blocks. oneOf: - type: string - type: array items: type: object example: - role: user content: Hello, Claude system: description: System prompt. String or array of text blocks. oneOf: - type: string - type: array items: type: object temperature: type: number format: float minimum: 0.0 maximum: 1.0 default: 1.0 description: Randomness. 0 = deterministic, 1 = creative. top_p: type: number format: float description: Nucleus sampling. Use instead of temperature. top_k: type: integer description: Only sample from the top K options for each token. stop_sequences: type: array items: type: string description: Custom sequences that stop generation. stream: type: boolean default: false description: Enable SSE streaming. tools: type: array description: Tools the model may use. items: type: object required: - name - input_schema properties: name: type: string description: type: string input_schema: type: object type: type: string example: custom tool_choice: type: object description: How the model uses tools. properties: type: type: string enum: - auto - any - tool - none name: type: string description: Required when type is tool. disable_parallel_tool_use: type: boolean default: false thinking: type: object description: Enable extended thinking for complex reasoning. properties: type: type: string enum: - enabled budget_tokens: type: integer example: 10000 display: type: string enum: - summarized - omitted metadata: type: object properties: user_id: type: string description: External user ID (no PII). service_tier: type: string enum: - auto - standard_only default: auto responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string example: msg_024e7cf42f5d47cfa6982b5ff8b55642 type: type: string example: message role: type: string example: assistant content: type: array description: Response content blocks (text, tool_use, thinking, etc.). items: type: object model: type: string example: claude-sonnet-4-6 stop_reason: type: string enum: - end_turn - stop_sequence - max_tokens - tool_use stop_sequence: type: string nullable: true usage: type: object properties: input_tokens: type: integer output_tokens: type: integer cache_creation_input_tokens: type: integer cache_read_input_tokens: type: integer '400': description: Invalid request parameters '401': description: Missing or invalid API key '429': description: Rate limit exceeded '500': description: Internal server error tags: - AI Models servers: - url: https://api.aisa.one/v1 /coingecko/coins/list: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coins List (ID Map) description: 'The full CoinGecko identifier map: every listed coin as `id`, `symbol` and `name`. Use it once to resolve a ticker into the `id` that every other CoinGecko tool requires — `bitcoin`, not BTC. Set `include_platform` to also get each coin''s contract address per chain. Mind the size: this returns roughly 18,000 entries and takes several seconds, so cache it instead of calling it per lookup. If you already know the ids and only want numbers, call `get_coingecko_simple_price` directly; to identify a coin from a contract address instead, use `get_coingecko_token_data`.' operationId: get_coingecko_coins_list parameters: - name: include_platform in: query description: Include platform + contract addresses. schema: type: boolean default: false responses: '200': description: Array of coins. content: application/json: example: - id: bitcoin symbol: btc name: Bitcoin - id: ethereum symbol: eth name: Ethereum schema: $ref: '#/components/schemas/CoinGeckoObjectArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/list source: https://github.com/AIsa-team/aisa-proxy /coingecko/simple/supported_vs_currencies: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Supported Currencies description: The 63 quote currencies accepted by the `vs_currency` / `vs_currencies` parameter of every other CoinGecko tool — fiat such as `usd` and `eur`, metals such as `xau`, and crypto such as `btc`. Returns a flat array of lowercase strings and takes no parameters. Call it before using a non-obvious quote currency rather than guessing at one. For the coin-side identifier map use `get_coingecko_coins_list`. operationId: get_coingecko_simple_supported_vs_currencies responses: '200': description: Array of currency codes. content: application/json: example: - btc - eth - usd - eur - jpy - gbp schema: $ref: '#/components/schemas/CoinGeckoStringArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/simple/supported_vs_currencies source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/markets: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coins Markets description: 'A ranked market table covering many coins in one call: one row per coin with `current_price`, `market_cap`, `market_cap_rank`, `total_volume`, `high_24h`, `low_24h`, `price_change_percentage_24h`, `circulating_supply`, `total_supply`, `max_supply`, `ath` and `atl` with their dates, and `image`. Page with `per_page` and `page`, sort with `order` (market cap, volume or id, ascending or descending), and narrow with `ids` or `category`. Passing `price_change_percentage` adds a matching `price_change_percentage_24h_in_currency` field. Use it for leaderboards and segment scans. For the price of a few known coins `get_coingecko_simple_price` is far lighter; for one coin in full use `get_coingecko_coins_id`.' operationId: get_coingecko_coins_markets parameters: - $ref: '#/components/parameters/VsCurrency' - name: ids in: query description: Comma-separated CoinGecko coin IDs. schema: type: string example: bitcoin,ethereum - name: category in: query description: Filter by category (see `/coins/categories/list`). schema: type: string - name: order in: query schema: type: string enum: - market_cap_desc - market_cap_asc - volume_desc - volume_asc - id_asc - id_desc default: market_cap_desc - name: per_page in: query schema: type: integer default: 100 minimum: 1 maximum: 250 - name: page in: query schema: type: integer default: 1 - name: sparkline in: query schema: type: boolean default: false - name: price_change_percentage in: query description: 'Comma-separated windows: `1h,24h,7d,14d,30d,200d,1y`.' schema: type: string - name: locale in: query schema: type: string default: en description: Response language locale. Official values include `en`, `zh`, `zh-tw`, and other supported CoinGecko locales. example: en - name: precision in: query schema: type: string description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' example: '2' - name: include_rehypothecated in: query schema: type: boolean default: false description: Include rehypothecated tokens in market data when supported by CoinGecko. responses: '200': description: Array of coin market entries. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoObjectArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/markets source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Data by ID description: 'Everything CoinGecko holds on one coin, selected by `id`: `description`, `links`, `image`, `categories`, `platforms` and `detail_platforms` (contract addresses per chain), `market_cap_rank`, and a `market_data` block carrying `current_price`, `market_cap`, `total_volume`, `fully_diluted_valuation`, `ath` and `atl` with dates and change percentages. The heavy sections are opt-in via `market_data`, `community_data`, `developer_data`, `tickers`, `sparkline` and `localization` — leave them off unless needed, the full payload is large. Use it for a coin profile. For a price table across many coins use `get_coingecko_coins_markets`; to look the same coin up by contract address use `get_coingecko_token_data`.' operationId: get_coingecko_coins_id parameters: - $ref: '#/components/parameters/CoinId' - name: localization in: query schema: type: boolean default: true - name: tickers in: query schema: type: boolean default: true - name: market_data in: query schema: type: boolean default: true - name: community_data in: query schema: type: boolean default: true - name: developer_data in: query schema: type: boolean default: true - name: sparkline in: query schema: type: boolean default: false responses: '200': description: Coin object. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoObject' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id} source: https://github.com/AIsa-team/aisa-proxy /coingecko/simple/price: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Simple Price description: 'The cheapest price lookup: pass comma-separated CoinGecko `ids` and `vs_currencies`, get back a map keyed by coin id. Field names are built from the quote currency — with `vs_currencies` set to usd you get `usd`, plus `usd_market_cap`, `usd_24h_vol`, `usd_24h_change` and `last_updated_at` when the matching `include_market_cap`, `include_24hr_vol`, `include_24hr_change` and `include_last_updated_at` flags are set. Use it whenever the ids are already known and only current numbers are needed. For rank, supply or all-time-high data use `get_coingecko_coins_markets`; if you hold a contract address rather than an id use `get_coingecko_simple_token_price_id`.' operationId: get_coingecko_simple_price parameters: - name: ids in: query required: true description: Comma-separated coin IDs. schema: type: string example: bitcoin,ethereum - name: vs_currencies in: query required: true description: Comma-separated target currencies. schema: type: string example: usd,eur - name: include_market_cap in: query schema: type: boolean default: false - name: include_24hr_vol in: query schema: type: boolean default: false - name: include_24hr_change in: query schema: type: boolean default: false - name: include_last_updated_at in: query schema: type: boolean default: false - name: precision in: query schema: type: string responses: '200': description: Map keyed by coin id. content: application/json: example: bitcoin: usd: 67234.12 eur: 62019.45 ethereum: usd: 3412.0 eur: 3147.8 schema: $ref: '#/components/schemas/CoinGeckoSimplePriceMap' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/simple/price source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/market_chart: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Historical Chart description: 'Historical series for one coin over a trailing window set by `days`, returned as three parallel arrays: `prices`, `market_caps` and `total_volumes`. Each entry is a two-element pair of timestamp and value, and the timestamp is in milliseconds. Granularity follows `days` automatically, or force it with `interval` (`daily` or `hourly`). Use it to chart a trend ending now. For an explicit start and end use `get_coingecko_coins_id_market_chart_range`; for candlesticks use `get_coingecko_coins_id_ohlc`; for one specific past day use `get_coingecko_coins_id_history`.' operationId: get_coingecko_coins_id_market_chart parameters: - $ref: '#/components/parameters/CoinId' - $ref: '#/components/parameters/VsCurrency' - $ref: '#/components/parameters/Days' - name: interval in: query description: Data interval. CoinGecko supports `daily`; `hourly` is also available for supported ranges. schema: type: string enum: - daily - hourly - name: precision in: query schema: type: string description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' example: '2' responses: '200': description: Three time-series arrays. content: application/json: example: prices: - - 1713398400000 - 67234.12 - - 1713402000000 - 67301.55 market_caps: - - 1713398400000 - 1321498765432 total_volumes: - - 1713398400000 - 25679876543 schema: $ref: '#/components/schemas/CoinGeckoMarketChart' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/market_chart source: https://github.com/AIsa-team/aisa-proxy /coingecko/exchanges: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Exchanges List description: A paged directory of active exchanges with `id`, `name`, `year_established`, `country`, `description`, `url`, `image`, `trust_score`, `trust_score_rank`, `trade_volume_24h_btc` and `has_trading_incentive`. Page with `per_page` and `page`. Use it to rank or filter venues by trust and volume. If you only need the identifier mapping, `get_coingecko_exchanges_list` returns all of them with no market data and no paging; for one venue in full use `get_coingecko_exchanges_id`. operationId: get_coingecko_exchanges parameters: - name: per_page in: query schema: type: integer default: 100 maximum: 250 - name: page in: query schema: type: integer default: 1 responses: '200': description: Array of exchange objects. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoObjectArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/exchanges source: https://github.com/AIsa-team/aisa-proxy /coingecko/search/trending: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Trending Search description: 'CoinGecko''s current trending board, ranked by search activity on CoinGecko itself: `coins` (15 entries), `nfts` (7) and `categories` (6). Each coin carries `id`, `name`, `symbol`, `market_cap_rank`, `price_btc`, `score` and a nested `data` block. Takes no parameters. Use it as a discovery entry point when the user named no specific asset. It reflects attention rather than price action — for movers ranked by market data use `get_coingecko_coins_markets` ordered by volume.' operationId: get_coingecko_search_trending responses: '200': description: Trending coins, nfts, and categories. content: application/json: example: coins: - item: id: bitcoin name: Bitcoin symbol: BTC market_cap_rank: 1 schema: $ref: '#/components/schemas/CoinGeckoObject' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/search/trending source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/categories/list: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Categories List description: A flat identifier map of roughly 856 CoinGecko categories, each as `category_id` and `name`. These are the values accepted by the `category` filter on `get_coingecko_coins_markets`, so use this to turn a theme into a usable id. It carries no market data at all; for category market caps, 24h change and leading coins use `get_coingecko_coins_categories`. operationId: get_coingecko_coins_categories_list responses: '200': description: Array of categories. content: application/json: example: - category_id: layer-1 name: Layer 1 (L1) - category_id: meme-token name: Meme schema: $ref: '#/components/schemas/CoinGeckoObjectArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/categories/list source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/tickers: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Tickers description: 'Every trading pair for one coin across venues: `base`, `target`, `market`, `last`, `volume`, `converted_last`, `converted_volume`, `trust_score`, `bid_ask_spread_percentage`, `last_traded_at`, `trade_url`, and the anomaly flags `is_anomaly` and `is_stale`. Setting `depth` adds `cost_to_move_up_usd` and `cost_to_move_down_usd`. Narrow with `exchange_ids`, page with `page`, sort with `order` (trust score or volume). Use it to compare where one asset trades and how deep each book is. For every pair on one venue regardless of coin, use `get_coingecko_exchanges_id_tickers`.' operationId: get_coingecko_coins_id_tickers parameters: - $ref: '#/components/parameters/CoinId' - name: exchange_ids in: query description: Comma-separated exchange IDs. schema: type: string - name: page in: query schema: type: integer default: 1 - name: order in: query schema: type: string enum: - trust_score_desc - trust_score_asc - volume_desc - name: depth in: query schema: type: boolean default: false - name: include_exchange_logo in: query schema: type: boolean default: false description: Show exchange logos in ticker results. responses: '200': description: Tickers array. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoTickersResponse' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/tickers source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/history: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Historical Data description: A snapshot of one coin on a single calendar day. `date` is required and must be formatted dd-mm-yyyy (day, month, four-digit year). Returns `market_data` holding `current_price`, `market_cap` and `total_volume` as of that day, alongside `community_data`, `developer_data` and `public_interest_stats`. Use it for one fixed point in time. For a continuous series use `get_coingecko_coins_id_market_chart` for a trailing window, or `get_coingecko_coins_id_market_chart_range` for an explicit one. operationId: get_coingecko_coins_id_history parameters: - $ref: '#/components/parameters/CoinId' - name: date in: query required: true description: Date in `dd-mm-yyyy` format. schema: type: string example: 30-12-2024 - name: localization in: query schema: type: boolean default: true responses: '200': description: Snapshot object for the given date. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoObject' '401': description: CoinGecko plan restriction or authorization error returned by the upstream provider. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoError' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/history source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/ohlc: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin OHLC description: 'Candlestick data for one coin as a bare array of rows, each row positional: timestamp in milliseconds, then open, high, low and close. There are no field names in the response and no volume. Candle width is derived from `days`, which is required. Use it for candle or technical analysis. For a price line together with market cap and traded volume use `get_coingecko_coins_id_market_chart` instead.' operationId: get_coingecko_coins_id_ohlc parameters: - $ref: '#/components/parameters/CoinId' - $ref: '#/components/parameters/VsCurrency' - name: days in: query required: true description: '`1`, `7`, `14`, `30`, `90`, `180`, `365`.' schema: type: string example: '7' - name: precision in: query schema: type: string description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' example: '2' responses: '200': description: 'Array of OHLC rows: `[timestamp, open, high, low, close]`.' content: application/json: example: - - 1713398400000 - 67000 - 67500 - 66900 - 67234.12 schema: $ref: '#/components/schemas/CoinGeckoOHLC' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/ohlc source: https://github.com/AIsa-team/aisa-proxy /coingecko/exchanges/list: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Exchanges List (ID Map) description: A flat identifier map of roughly 1,500 exchanges as `id` and `name`. Use it to resolve a venue name into the `id` required by `get_coingecko_exchanges_id` and by the `exchange_ids` filter on `get_coingecko_coins_id_tickers`. It takes no parameters and carries no market data; for trust scores and volumes use `get_coingecko_exchanges`. operationId: get_coingecko_exchanges_list responses: '200': description: Array of `{id, name}`. content: application/json: example: - id: binance name: Binance - id: gdax name: Coinbase Exchange schema: $ref: '#/components/schemas/CoinGeckoObjectArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/exchanges/list source: https://github.com/AIsa-team/aisa-proxy /coingecko/exchanges/{id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Exchange Data by ID description: 'The full profile of one exchange: `name`, `year_established`, `country`, `description`, `url`, `image`, social handles, `centralized`, `trust_score`, `trust_score_rank`, `trade_volume_24h_btc`, `coins`, `pairs`, plus an embedded `tickers` sample and `status_updates`. Use it for venue due diligence. For a ranked list across many venues use `get_coingecko_exchanges`; for that venue''s complete paged pair list use `get_coingecko_exchanges_id_tickers`.' operationId: get_coingecko_exchanges_id parameters: - $ref: '#/components/parameters/ExchangeId' responses: '200': description: Exchange object. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoObject' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/exchanges/{id} source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/categories: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Categories with Market Data description: 'Roughly 749 crypto categories with market data attached: `id`, `name`, `market_cap`, `market_cap_change_24h`, `volume_24h`, `top_3_coins_id`, `top_3_coins`, `content` and `updated_at`. Sort with `order` by market cap, name or 24h market-cap change. Use it to see which sectors are moving. For the plain identifier list that the `category` filter expects, `get_coingecko_coins_categories_list` is smaller and faster.' operationId: get_coingecko_coins_categories parameters: - name: order in: query schema: type: string enum: - market_cap_desc - market_cap_asc - name_desc - name_asc - market_cap_change_24h_desc - market_cap_change_24h_asc responses: '200': description: Array of categories with market data. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoObjectArray' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/categories source: https://github.com/AIsa-team/aisa-proxy /coingecko/news: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Crypto News description: 'Crypto news headlines from CoinGecko, filterable by `coin_id`, `language` and `type` (`news` or `guides`), paged with `page` and `per_page`. Availability warning: this endpoint is restricted to CoinGecko Analyst plans and above, and on the current upstream subscription it returns HTTP 401 with an upgrade message in the body. Treat it as unavailable until the upstream plan changes. For coin context that does work today, `get_coingecko_coins_id` returns `description` and `links` including official channels.' operationId: get_coingecko_news responses: '200': description: Array of news articles. content: application/json: example: data: - title: Bitcoin hits new high url: https://example.com/article published_at: 1713398400 schema: $ref: '#/components/schemas/CoinGeckoNewsArticleArray' '401': description: CoinGecko plan restriction or authorization error returned by the upstream provider. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoError' parameters: - name: coin_id in: query schema: type: string description: Filter news by CoinGecko coin ID. example: bitcoin - name: language in: query schema: type: string description: Filter news by language. example: en - name: type in: query schema: type: string enum: - news - guides description: Filter by article type. example: news - name: page in: query schema: type: integer default: 1 description: Page through results. - name: per_page in: query schema: type: integer default: 100 description: Total results per page. tags: - Crypto Data x-x402: path: /apis/v2/coingecko/news source: https://github.com/AIsa-team/aisa-proxy /coingecko/exchanges/{id}/tickers: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Exchange Tickers description: 'Every trading pair listed on one exchange, paged: `base`, `target`, `market`, `last`, `volume`, `converted_last`, `converted_volume`, `trust_score`, `bid_ask_spread_percentage`, `timestamp`, `trade_url` and the `is_anomaly` / `is_stale` flags. Narrow to specific assets with `coin_ids`, sort with `order`, and set `depth` to add order-book move costs. Use it to audit one venue''s coverage or liquidity. For one coin''s pairs across all venues use `get_coingecko_coins_id_tickers` instead.' operationId: get_coingecko_exchanges_id_tickers parameters: - $ref: '#/components/parameters/ExchangeId' - name: coin_ids in: query description: Filter by coin IDs (comma-separated). schema: type: string - name: page in: query schema: type: integer default: 1 - name: depth in: query schema: type: boolean default: false - name: order in: query schema: type: string enum: - trust_score_desc - trust_score_asc - volume_desc - name: include_exchange_logo in: query schema: type: boolean default: false description: Show exchange logos in ticker results. responses: '200': description: Tickers array. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoTickersResponse' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/exchanges/{id}/tickers source: https://github.com/AIsa-team/aisa-proxy /coingecko/simple/token_price/{id}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Price by Token Address description: Price lookup keyed by on-chain contract address rather than CoinGecko id. `id` is the asset platform, `contract_addresses` a comma-separated list of token addresses, `vs_currencies` the quote currency. Returns a map keyed by lowercase contract address whose field names are built from the quote currency — `usd`, plus `usd_market_cap`, `usd_24h_vol`, `usd_24h_change` and `last_updated_at` when the matching `include_market_cap`, `include_24hr_vol`, `include_24hr_change` and `include_last_updated_at` flags are set. Use it when you hold an address and no id. For the token's full profile use `get_coingecko_token_data`; if you already have the CoinGecko id use `get_coingecko_simple_price`. operationId: get_coingecko_simple_token_price_id parameters: - name: id in: path required: true description: Platform ID (e.g., `ethereum`, `binance-smart-chain`, `polygon-pos`). schema: type: string example: ethereum - name: contract_addresses in: query required: true description: Comma-separated contract addresses. schema: type: string example: '0xdAC17F958D2ee523a2206206994597C13D831ec7' - name: vs_currencies in: query required: true description: Comma-separated target currencies. schema: type: string example: usd - name: include_market_cap in: query schema: type: boolean - name: include_24hr_vol in: query schema: type: boolean - name: include_24hr_change in: query schema: type: boolean - name: include_last_updated_at in: query schema: type: boolean - name: precision in: query schema: type: string description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' example: '2' responses: '200': description: Map keyed by contract address. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoSimplePriceMap' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/simple/token_price/{id} source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/contract/{contract_address}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low tags: - Crypto Data summary: Coin Data by Token Address description: A full coin profile looked up by contract address instead of CoinGecko id. `id` is the asset platform and `contract_address` the token; both are required and there are no other parameters. Returns the same shape as `get_coingecko_coins_id` — `description`, `links`, `image`, `categories`, `platforms`, `detail_platforms`, `market_cap_rank`, a `market_data` block and an embedded `tickers` array — plus `contract_address` itself. Use it to identify an unknown token from an address. If only the current price is needed, `get_coingecko_simple_token_price_id` is far lighter. operationId: get_coingecko_token_data parameters: - name: id in: path required: true description: Asset platform ID (e.g., `ethereum`). Refers to the `/asset_platforms` list on CoinGecko. schema: type: string default: ethereum example: ethereum - name: contract_address in: path required: true description: The contract address of the token. schema: type: string default: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' responses: '200': description: Get current data for a coin. content: application/json: schema: $ref: '#/components/schemas/CoinsContractAddress' x-x402: path: /apis/v2/coingecko/coins/{id}/contract/{contract_address} source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/contract/{contract_address}/market_chart: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Historical Chart by Contract description: Historical series for a token identified by contract address, over a trailing window set by `days`. `id` is the asset platform, `contract_address` the token. Returns `prices`, `market_caps` and `total_volumes` as timestamp-and-value pairs, with timestamps in milliseconds — the same shape as `get_coingecko_coins_id_market_chart`. Use it when you have an address rather than a CoinGecko id. For an explicit start and end use `get_coingecko_token_market_chart_range`. operationId: get_coingecko_token_market_chart parameters: - name: id in: path required: true description: Platform ID. schema: type: string example: ethereum - name: contract_address in: path required: true description: Contract address. schema: type: string - $ref: '#/components/parameters/VsCurrency' - $ref: '#/components/parameters/Days' - name: precision in: query schema: type: string description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' example: '2' responses: '200': description: Same shape as `/coins/{id}/market_chart`. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoMarketChart' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/contract/{contract_address}/market_chart source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/market_chart/range: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Market Chart Range description: Historical series for one coin between two explicit points in time. `from` and `to` are Unix timestamps in seconds, while the timestamps inside the response are in milliseconds — the two are not the same unit, which is the usual source of empty or misaligned results. Returns `prices`, `market_caps` and `total_volumes` as timestamp-and-value pairs; CoinGecko picks granularity from the window length. Use it to line a series up with a known event window. For a trailing window ending now, `get_coingecko_coins_id_market_chart` takes a `days` count instead. operationId: get_coingecko_coins_id_market_chart_range parameters: - $ref: '#/components/parameters/CoinId' - $ref: '#/components/parameters/VsCurrency' - name: from in: query required: true description: Start UNIX timestamp (seconds). schema: type: integer example: 1713398400 - name: to in: query required: true description: End UNIX timestamp (seconds). schema: type: integer example: 1713484800 - name: precision in: query schema: type: string description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' example: '2' responses: '200': description: Same shape as `/coins/{id}/market_chart`. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoMarketChart' '401': description: CoinGecko plan restriction or authorization error returned by the upstream provider. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoError' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/market_chart/range source: https://github.com/AIsa-team/aisa-proxy /coingecko/coins/{id}/contract/{contract_address}/market_chart/range: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.008 cost_tier: low summary: Coin Market Chart Range by Contract description: Historical series between two explicit points in time for a token identified by contract address. `id` is the asset platform and `contract_address` the token; `from` and `to` are Unix timestamps in seconds while response timestamps are in milliseconds. Returns `prices`, `market_caps` and `total_volumes` as timestamp-and-value pairs. Use it when you have an address and a fixed window. For a trailing window use `get_coingecko_token_market_chart`; if you hold a CoinGecko id rather than an address use `get_coingecko_coins_id_market_chart_range`. operationId: get_coingecko_token_market_chart_range parameters: - name: id in: path required: true description: Asset platform ID (e.g., `ethereum`). schema: type: string example: ethereum - name: contract_address in: path required: true description: Token contract address. schema: type: string example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' - $ref: '#/components/parameters/VsCurrency' - name: from in: query required: true description: Start UNIX timestamp (seconds). schema: type: integer example: 1751328000 - name: to in: query required: true description: End UNIX timestamp (seconds). schema: type: integer example: 1751414400 - name: precision in: query description: '`full` or a value from `0` to `18` to specify decimal places for currency price values.' schema: type: string example: '2' responses: '200': description: Same shape as `/coins/{id}/market_chart/range`. content: application/json: schema: $ref: '#/components/schemas/CoinGeckoMarketChart' tags: - Crypto Data x-x402: path: /apis/v2/coingecko/coins/{id}/contract/{contract_address}/market_chart/range source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/ai_keyword_data/keywords_search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.0208 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: AI Keyword Data Keyword Search Volume description: 'Search volume for `keywords` as measured inside AI assistants rather than a search engine - how often people ask assistants about a term. Returns `location_code`, `language_code`, `items_count` and `items`. Measured at 1.2 KB and **$0.0101 upstream against $0.012 billed, a thin margin**, so batch keywords into one call rather than calling per keyword. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For classical search volume use `post_dataforseo_keywords_gads_search_volume_live`; the two answer different questions and often disagree.' operationId: post_dataforseo_ai_keyword_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.items_count: type: integer description: number of results returned in the items array tasks.result.items: type: array items: type: string description: contains specified keywords with their AI search volume rates tasks.result.items.keyword: type: string description: specified keyword tasks.result.items.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.ai_monthly_searches: type: array items: type: string description: monthly AI search volume rates array of objects with AI search volume rates in a certain month of a year tasks.result.items.ai_monthly_searches.year: type: integer description: year tasks.result.items.ai_monthly_searches.month: type: integer description: month tasks.result.items.ai_monthly_searches.ai_search_volume: type: integer description: AI search volume rate in a certain month of a year learn more about this metric here '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field UTF-8 encoding The maximum number of keywords you can specify: 1000; The maximum number of characters in a single keyword: 250; The keywords will be converted to lowercase format;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if you don''t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages example: United Kingdom' location_code: type: integer description: 'unique location identifier required field if you don''t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don''t specify language_code if you use this field, you don''t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don''t specify language_name if you use this field, you don''t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/ai_keyword_data/keywords_search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/ai_keyword_data/locations_and_languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations and Languages for AI Keyword Data API description: 'The locations and languages the AI keyword endpoint accepts, as `location_code`, `location_name` and `available_languages` nested per location. Measured at 13.1 KB. Free: upstream cost is 0. Reference data - fetch once and reuse. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_ai_keyword_locales responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.available_languages: type: array items: type: string description: supported languages contains the languages which are supported for a specific location tasks.result.available_languages.language_name: type: string description: language name tasks.result.available_languages.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/ai_keyword_data/locations_and_languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_responses/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00121 p50: 0.012 p95: 0.054438 max: 0.054488 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live ChatGPT LLM Responses description: 'Sends a `user_prompt` to a ChatGPT model and returns its reply, synchronously. `model_name` picks the model - see `get_dataforseo_ai_chat_gpt_llm_responses_models`, and an unlisted name is rejected outright. `max_output_tokens`, `temperature` and `top_p` behave as they do on the vendor''s own API, and `web_search` or `force_web_search` let it browse. Returns `model_name`, `input_tokens`, `output_tokens`, `reasoning_tokens`, `web_search`, `money_spent`, `datetime`, `items` and `fan_out_queries`. 💰 **Priced by tokens upstream, not per call**: a sixteen-token reply measured $0.0006, but nothing caps a long one, and AIsa bills a flat $0.012 either way. Read `money_spent` on the response to see what a prompt actually cost. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ This is a general LLM call routed through a data provider, not an SEO measurement. If you want to know what ChatGPT tells users about a brand, `post_dataforseo_ai_chat_gpt_llm_scraper_live` reproduces the consumer experience instead.' operationId: post_dataforseo_ai_chat_gpt_llm_responses_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD includes the base task price plus the money_spent value tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.model_name: type: string description: name of the AI model used tasks.result.input_tokens: type: integer description: number of tokens in the input total count of tokens processed tasks.result.output_tokens: type: integer description: number of tokens in the output total count of tokens generated in the AI response tasks.result.reasoning_tokens: type: integer description: number of reasoning tokens total count of tokens used to generate reasoning content tasks.result.web_search: type: boolean description: indicates if web search was used tasks.result.money_spent: type: number description: cost of AI tokens, USD the price charged by the third-party AI model provider for according to its Pricing tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items: type: array items: type: string description: array of response items contains structured AI response data tasks.result.items.reasoning: type: object description: element in the response tasks.result.items.reasoning.type: type: string description: 'type of the element = ''reasoning'' Note: this element is supported only in reasoning models and is not guaranteed to be returned' tasks.result.items.reasoning.sections: type: array items: type: string description: reasoning chain sections array of objects containing the reasoning chain sections generated by the LLM tasks.result.items.reasoning.sections.type: type: string description: type of element='summary_text' tasks.result.items.reasoning.sections.text: type: string description: text of the reasoning chain section text of the reasoning chain section summarizing the model's thought process tasks.result.items.message: type: object description: element in the response tasks.result.items.message.type: type: string description: type of the element = 'message' tasks.result.items.message.sections: type: array items: type: string description: array of content sections contains different parts of the AI response tasks.result.items.message.sections.type: type: string description: type of element='text' tasks.result.items.message.sections.text: type: string description: AI-generated text content tasks.result.items.message.sections.annotations: type: array items: type: string description: 'array of references used to generate the response equals null if the web_search parameter is not set to true Note: annotations may return empty even when web_search is true, as the AI will attempt to retrieve web information but may not find relevant results' tasks.result.items.message.sections.annotations.title: type: string description: the domain name or title of the quoted source tasks.result.items.message.sections.annotations.url: type: string description: URL of the quoted source tasks.result.fan_out_queries: type: array items: type: string description: array of fan-out queries contains related search queries derived from the main query to provide a more comprehensive response '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically; you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024; minimum value for non-reasoning models: 16; maximum value: 4096; default value: 2048 Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse; lower values make output more focused; minimum value: 0 maximum value: 2 default value: 0.94 Note: not supported in reasoning models' top_p: type: number description: '' web_search: type: boolean description: 'enable web search optional field when enabled, the AI model can access and cite current web information; default value: false; Note: refer to the Models endpoint for a list of models that support web_search;' force_web_search: type: boolean description: 'force AI agent to use web search optional field to enable this parameter, web_search must also be enabled; when enabled, the AI model is forced to access and cite current web information; default value: false; Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response Note #2: not supported in reasoning models' web_search_country_iso_code: type: string description: 'ISO country code of the location optional field required if web_search_city is specified; to enable this parameter, web_search must also be enabled; when enabled, the AI model will search the web from the country you specify; Note: not supported in o3-mini, o1-pro, o1 models' web_search_city: type: string description: 'city name of the location optional field Note: specify web_search_country_iso_code to use this parameter Note #2: not supported in o3-mini, o1-pro, o1 models' system_message: type: string description: instructions for the AI behaviour optional field defines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain role and message parameters: role string with either user or ai role; message string with message content (max 500 characters); you can specify the maximum of 10 message objects in the array; example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_responses/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_responses/models: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of ChatGPT models for LLM Responses description: 'The ChatGPT models available, each with `model_name`, `reasoning`, `web_search_supported` and `task_post_supported`. Measured at 5.2 KB, the largest of the four model lists. Free: upstream cost is 0. **Read it before calling** - an unlisted `model_name` is rejected with `status_code` 40501 inside an HTTP 200, and `task_post_supported` tells you whether the queued variant will work at all.' operationId: get_dataforseo_ai_chat_gpt_llm_responses_models responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request result: type: array items: type: string description: array of results result.model_name: type: string description: name of the AI model result.reasoning: type: boolean description: indicates if the AI model supports reasoning result.web_search_supported: type: boolean description: web search support for the AI model if true, the web_search parameter can be set with the AI model result.task_post_supported: type: boolean description: indicates if Standard (POST-GET) data retrieval is supported if true, you can use the Standard (POST-GET) data retrieval method with the AI model '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_responses/models source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_responses/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get LLM Responses Chat GPT Results by id description: 'Retrieves a queued ChatGPT reply by `id`. Same shape as the live endpoint, including `money_spent`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_ai_chat_gpt_llm_responses_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_responses/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_responses/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0204 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘LLM Responses ChatGPT’ Tasks description: 'Queues a ChatGPT prompt instead of waiting for the reply, returning a task `id`. Adds `system_message` and `message_chain` over the live endpoint, so a multi-turn conversation can be sent in one task. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Not every model supports queuing - check `task_post_supported` in `get_dataforseo_ai_chat_gpt_llm_responses_models`. Retrieve with `get_dataforseo_ai_chat_gpt_llm_responses_fetch`.' operationId: post_dataforseo_ai_chat_gpt_llm_responses_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system unique task identifier in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically; you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024; minimum value for non-reasoning models: 16; maximum value: 4096; default value: 2048' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse; lower values make output more focused; minimum value: 0 maximum value: 2 default value: 0.94 Note: not supported in reasoning models' top_p: type: number description: '' system_message: type: string description: instructions for the AI behaviour optional field defines the AI's role, tone, or specific behavior; you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain role and message parameters: role string with either user or ai role; message string with message content (max 500 characters); you can specify the maximum of 10 message objects in the array; example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special character in postback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special character in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data array of the response required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_responses/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_responses/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get LLM Responses ChatGPT Completed Tasks description: 'Lists finished ChatGPT response tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_ai_chat_gpt_llm_responses_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request's URL result: type: array items: type: string description: array of results result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format result.se: type: string description: LLM model specified when setting the task result.function: type: string description: type of the task result.date_posted: type: string description: date when the task was posted (in the UTC format) result.tag: type: string description: user-defined task identifier result.endpoint: type: string description: URL for collecting the results of the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_responses/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_scraper/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live ChatGPT LLM Scraper description: 'Asks ChatGPT a `keyword` as a user would and returns the answer parsed. Returns `keyword`, `location_code`, `language_code`, `model`, `datetime`, `markdown`, `sources`, `fan_out_queries` and `brand_entities` - `markdown` is the answer as the assistant rendered it, `sources` the pages it cited, and `brand_entities` the brands it named. Measured at $0.004. Measured at 11.3 KB. `force_web_search` makes it browse rather than answer from training. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the endpoint for ''what does ChatGPT say about us''; for counting mentions across many answers use `post_dataforseo_ai_llm_mentions_aggregated_metrics_live` instead of scraping repeatedly. The raw form is `post_dataforseo_ai_chat_gpt_llm_scraper_live_html`.' operationId: post_dataforseo_ai_chat_gpt_llm_scraper_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword received in a POST array the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character) tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.model: type: string description: indicates the model version tasks.result.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided exact results tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.search_results: type: array items: type: string description: array of search results all web search outputs the model retrieved when looking up information, including duplicates and unused entries tasks.result.search_results.type: type: string description: type of element='chatgpt_search_result'n tasks.result.search_results.url: type: string description: result URL tasks.result.search_results.domain: type: string description: result domain tasks.result.search_results.title: type: string description: result title tasks.result.search_results.description: type: string description: result description tasks.result.search_results.breadcrumb: type: string description: breadcrumb tasks.result.sources: type: array items: type: string description: array of sources the sources the model actually cited or relied on in its final answer tasks.result.sources.type: type: string description: type of element='chat_gpt_source' tasks.result.sources.title: type: string description: source title tasks.result.sources.snippet: type: string description: source description tasks.result.sources.domain: type: string description: source domain tasks.result.sources.url: type: string description: source URL tasks.result.sources.thumbnail: type: string description: source thumbnail tasks.result.sources.source_name: type: string description: source name tasks.result.sources.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.sources.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.fan_out_queries: type: array items: type: string description: array of fan-out queries contains related search queries derived from the main query to provide a more comprehensive response tasks.result.brand_entities: type: array items: type: string description: array of brand entities contains information on brands mentioned in the response tasks.result.brand_entities.type: type: string description: type of the element = 'chat_gpt_brand_entity' tasks.result.brand_entities.title: type: string description: name of the brand tasks.result.brand_entities.category: type: string description: category of the brand tasks.result.brand_entities.markdown: type: string description: brand name in markdown format contains brand name formatted in the markdown markup language tasks.result.brand_entities.urls: type: array items: type: string description: array of URLs and domains relevant to the brand tasks.result.brand_entities.urls.url: type: string description: URL tasks.result.brand_entities.urls.domain: type: string description: domain tasks.result.se_results_count: type: integer description: total number of results tasks.result.item_types: type: array items: type: string description: 'types of search results contains types of search results (items) found in SERP. possible item types: chat_gpt_text, chat_gpt_table, chat_gpt_navigation_list, chat_gpt_images, chat_gpt_local_businesses, chat_gpt_products' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: elements of ChatGPT results tasks.result.items.chat_gpt_text: type: object description: element in the response tasks.result.items.chat_gpt_text.type: type: string description: type of element='chat_gpt_text' tasks.result.items.chat_gpt_text.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.chat_gpt_text.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.chat_gpt_text.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_text.sources: type: array items: type: string description: array of sources tasks.result.items.chat_gpt_text.sources.type: type: string description: type of element='chat_gpt_source'n tasks.result.items.chat_gpt_text.sources.title: type: string description: source title tasks.result.items.chat_gpt_text.sources.snippet: type: string description: source description tasks.result.items.chat_gpt_text.sources.domain: type: string description: source domain in SERP tasks.result.items.chat_gpt_text.sources.url: type: string description: source URL tasks.result.items.chat_gpt_text.sources.thumbnail: type: string description: source thumbnail tasks.result.items.chat_gpt_text.sources.source_name: type: string description: source name tasks.result.items.chat_gpt_text.sources.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.chat_gpt_text.sources.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_text.brand_entities: type: array items: type: string description: array of brand entities contains information on brands mentioned in the text tasks.result.items.chat_gpt_text.brand_entities.type: type: string description: type of the element = 'chat_gpt_brand_entity' tasks.result.items.chat_gpt_text.brand_entities.title: type: string description: name of the brand tasks.result.items.chat_gpt_text.brand_entities.category: type: string description: category of the brand tasks.result.items.chat_gpt_text.brand_entities.markdown: type: string description: brand name in markdown format contains brand name formatted in the markdown markup language tasks.result.items.chat_gpt_text.brand_entities.urls: type: array items: type: string description: array of URLs and domains relevant to the brand tasks.result.items.chat_gpt_text.brand_entities.urls.url: type: string description: URL tasks.result.items.chat_gpt_text.brand_entities.urls.domain: type: string description: domain tasks.result.items.chat_gpt_table: type: object description: element in the response tasks.result.items.chat_gpt_table.type: type: string description: type of element='chat_gpt_table' tasks.result.items.chat_gpt_table.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.chat_gpt_table.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.chat_gpt_table.text: type: string description: text of the element tasks.result.items.chat_gpt_table.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_table.table: type: object description: table present in the element the header and content of the table present in the element tasks.result.items.chat_gpt_table.table.table_header: type: array items: type: string description: content in the header of the table tasks.result.items.chat_gpt_table.table.table_content: type: array items: type: string description: array of contents of the table present in the element each array represents the table row tasks.result.items.chat_gpt_table.brand_entities: type: array items: type: string description: array of brand entities contains information on brands mentioned in the table tasks.result.items.chat_gpt_table.brand_entities.type: type: string description: type of the element = 'chat_gpt_brand_entity' tasks.result.items.chat_gpt_table.brand_entities.title: type: string description: name of the brand tasks.result.items.chat_gpt_table.brand_entities.category: type: string description: category of the brand tasks.result.items.chat_gpt_table.brand_entities.markdown: type: string description: brand name in markdown format contains brand name formatted in the markdown markup language tasks.result.items.chat_gpt_table.brand_entities.urls: type: array items: type: string description: array of URLs and domains relevant to the brand tasks.result.items.chat_gpt_table.brand_entities.urls.url: type: string description: URL tasks.result.items.chat_gpt_table.brand_entities.urls.domain: type: string description: domain tasks.result.items.chat_gpt_navigation_list: type: object description: element in the response tasks.result.items.chat_gpt_navigation_list.type: type: string description: type of element='chat_gpt_navigation_list' tasks.result.items.chat_gpt_navigation_list.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.chat_gpt_navigation_list.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.chat_gpt_navigation_list.title: type: string description: title of the element tasks.result.items.chat_gpt_navigation_list.sources: type: array items: type: string description: array of sources tasks.result.items.chat_gpt_navigation_list.sources.type: type: string description: type of element='chat_gpt_source' tasks.result.items.chat_gpt_navigation_list.sources.title: type: string description: source title tasks.result.items.chat_gpt_navigation_list.sources.snippet: type: string description: source description tasks.result.items.chat_gpt_navigation_list.sources.domain: type: string description: source domain in SERP tasks.result.items.chat_gpt_navigation_list.sources.url: type: string description: source URL tasks.result.items.chat_gpt_navigation_list.sources.thumbnail: type: string description: source thumbnail tasks.result.items.chat_gpt_navigation_list.sources.source_name: type: string description: source name tasks.result.items.chat_gpt_navigation_list.sources.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.chat_gpt_navigation_list.sources.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_images: type: object description: element in the response tasks.result.items.chat_gpt_images.type: type: string description: type of element='chat_gpt_images' tasks.result.items.chat_gpt_images.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.chat_gpt_images.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.chat_gpt_images.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_images.items: type: array items: type: string description: items present in the element tasks.result.items.chat_gpt_images.items.type: type: string description: type of element = 'chat_gpt_images_element' tasks.result.items.chat_gpt_images.items.alt: type: string description: alt tag of the image tasks.result.items.chat_gpt_images.items.url: type: string description: relevant URL tasks.result.items.chat_gpt_images.items.image_url: type: string description: URL of the image the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available) tasks.result.items.chat_gpt_images.items.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_local_businesses: type: object description: element in the response tasks.result.items.chat_gpt_local_businesses.type: type: string description: type of element='chat_gpt_local_businesses' tasks.result.items.chat_gpt_local_businesses.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.chat_gpt_local_businesses.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.chat_gpt_local_businesses.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.chat_gpt_local_businesses.items: type: array items: type: string description: items present in the element tasks.result.items.chat_gpt_local_businesses.items.type: type: string description: type of element = 'chat_gpt_local_businesses_element' tasks.result.items.chat_gpt_local_businesses.items.title: type: string description: title of the local business tasks.result.items.chat_gpt_local_businesses.items.description: type: string description: description of the local business tasks.result.items.chat_gpt_local_businesses.items.address: type: string description: address of the local business tasks.result.items.chat_gpt_local_businesses.items.phone: type: string description: phone of the local business tasks.result.items.chat_gpt_local_businesses.items.reviews_count: type: integer description: total number of reviews submitted for the local business tasks.result.items.chat_gpt_local_businesses.items.url: type: string description: website URL of the local business tasks.result.items.chat_gpt_local_businesses.items.domain: type: string description: domain name of the local business tasks.result.items.chat_gpt_local_businesses.items.rating: type: object description: rating of the corresponding local business popularity rate based on reviews and displayed in SERP tasks.result.items.chat_gpt_local_businesses.items.rating.rating_type: type: string description: 'type of rating here you can find the following elements: Max5, Percents, CustomMax' tasks.result.items.chat_gpt_local_businesses.items.rating.value: type: number description: the average rating based on all reviews tasks.result.items.chat_gpt_local_businesses.items.rating.votes_count: type: integer description: the number of votes tasks.result.items.chat_gpt_local_businesses.items.rating.rating_max: type: integer description: the maximum value for a rating_type tasks.result.items.chat_gpt_products: type: object description: element in the response tasks.result.items.chat_gpt_products.type: type: string description: type of element='chat_gpt_products' tasks.result.items.chat_gpt_products.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.chat_gpt_products.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.chat_gpt_products.items: type: array items: type: string description: items present in the element tasks.result.items.chat_gpt_products.items.type: type: string description: type of element = 'chat_gpt_products_element' tasks.result.items.chat_gpt_products.items.product_id: type: string description: product id tasks.result.items.chat_gpt_products.items.merchants: type: string description: merchant(s) offering the product tasks.result.items.chat_gpt_products.items.id_to_token_map: type: string description: product identifier token Base64-encoded token containing Google Shopping product IDs associated with the product tasks.result.items.chat_gpt_products.items.title: type: string description: title of the product tasks.result.items.chat_gpt_products.items.rating: type: object description: rating of the product popularity rate based on reviews and displayed in SERP tasks.result.items.chat_gpt_products.items.rating.rating_type: type: string description: 'type of rating here you can find the following elements: Max5, Percents, CustomMax' tasks.result.items.chat_gpt_products.items.rating.value: type: number description: the average rating based on all reviews tasks.result.items.chat_gpt_products.items.rating.votes_count: type: integer description: the number of votes tasks.result.items.chat_gpt_products.items.rating.rating_max: type: integer description: the maximum value for a rating_type tasks.result.items.chat_gpt_products.items.price: type: number description: product price tasks.result.items.chat_gpt_products.items.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.chat_gpt_products.items.tag: type: string description: tag text tasks.result.items.chat_gpt_products.items.url: type: string description: result URL tasks.result.items.chat_gpt_products.items.domain: type: string description: result domain in SERP tasks.result.items.chat_gpt_products.items.images: type: array items: type: string description: image URLs of the element contains URLs leading to the images on the original resource or DataForSEO storage (in case the original source is not available) tasks.result.items.chat_gpt_products.items.product_ids: type: array items: type: string description: Google Shopping product identifiers array of Google Shopping product IDs associated with the product tasks.result.items.chat_gpt_products.items.product_ids.type: type: string description: type of element = 'chat_gpt_google_shopping_product' tasks.result.items.chat_gpt_products.items.product_ids.ei: type: string description: event identifier internal event identifier used by Google tasks.result.items.chat_gpt_products.items.product_ids.product_id: type: string description: product identifier can be used as a data_docid in Google Shopping API endpoints tasks.result.items.chat_gpt_products.items.product_ids.catalog_id: type: string description: Google Shopping catalog identifier of the product can be used as a product_id in Google Shopping API endpoints tasks.result.items.chat_gpt_products.items.product_ids.gpcid: type: string description: Google product cluster identifier can be used as a gid in Google Shopping API endpoints tasks.result.items.chat_gpt_products.items.product_ids.headline_offer_docid: type: string description: document identifier of the main offer in the headline can be used as a data_docid in Google Shopping API endpoints tasks.result.items.chat_gpt_products.items.product_ids.image_docid: type: string description: identifier for the displayed product’s image tasks.result.items.chat_gpt_products.items.product_ids.rds: type: string description: resource descriptor string internal Google resource descriptor string that identifies the product within Google's Shopping index tasks.result.items.chat_gpt_products.items.product_ids.query: type: string description: search query search query used by ChatGPT to retrieve the product from Google Shopping tasks.result.items.chat_gpt_products.items.product_ids.mid: type: string description: merchant identifier identifier of the seller or merchant account in Google Shopping tasks.result.items.chat_gpt_products.items.product_ids.pvt: type: string description: product view type internal Google parameter that specifies the product view type used when rendering the product item tasks.result.items.chat_gpt_products.items.product_ids.uule: type: string description: encoded location parameter indicates the location for a search tasks.result.items.chat_gpt_products.items.product_ids.gl: type: string description: country code indicates the location for which search results are displayed tasks.result.items.chat_gpt_products.items.product_ids.hl: type: string description: host language code indicates the language in which search results are displayed '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 2000 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don''t specify location_code if you use this field, you don''t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations example: United States' location_code: type: integer description: 'search engine location code required field if you don''t specify location_name if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations example: 2840' language_name: type: string description: full name of search engine language required field if you don't specify language_code; if you use this field, you don't need to specify language_code; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages language_code: type: string description: search engine language code required field if you don't specify language_name; if you use this field, you don't need to specify language_name; you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages force_web_search: type: boolean description: 'force AI agent to use web search optional field when enabled, the AI model is forced to access and cite current web information; default value: false; Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code example: - keyword: What is the capital of Japan? location_code: 2840 language_code: en tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_scraper/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_scraper/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live ChatGPT LLM Scraper API HTML description: 'The same ChatGPT answer as `post_dataforseo_ai_chat_gpt_llm_scraper_live`, returned as raw HTML rather than parsed. `expand_citations` unfolds the source list. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Larger than the 11.3 KB parsed form and harder for an agent to use - take it only when you need markup the parser dropped.' operationId: post_dataforseo_ai_chat_gpt_llm_scraper_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword received in a POST array keyword is returned with decoded %## (plus character '+' will be decoded to a space character) tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: elements of search results found tasks.result.items.page: type: integer description: serial number of the returned HTML page tasks.result.items.date: type: string description: 'date and time when the HTML page was scanned in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.html: type: string description: HTML page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 2000 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don''t specify location_code if you use this field, you don''t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/locations example: United States' location_code: type: integer description: 'search engine location code required field if you don''t specify location_name if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/locations example: 2840' language_name: type: string description: 'full name of search engine language required field if you don''t specify language_code if you use this field, you don''t need to specify language_code you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/languages example: English' language_code: type: string description: search engine language code required field if you don't specify language_name if you use this field, you don't need to specify language_name you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/languages example:enn force_web_search: type: boolean description: 'force AI agent to use web search optional field when enabled, the AI model is forced to access and cite current web information; default value: false; Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response' expand_citations: type: boolean description: 'return expanded citation bar in HTML results optional field to enable this parameter, force_web_search must also be enabled; when enabled, the endpoint will return HTML data from the expanded citation bar; default value: false' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_scraper/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/chat_gpt/llm_scraper/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ChatGPT LLM Scraper Advanced Results by id description: 'Retrieves a queued ChatGPT scrape by `id`. Same parsed shape as the live endpoint. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Free - the charge was on the submit.' operationId: get_dataforseo_ai_chat_gpt_llm_scraper_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier a universally unique identifier (UUID) unique task identifier in our system you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/claude/llm_responses/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0013 p50: 0.012 p95: 0.015822 max: 0.112802 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Claude LLM Responses description: 'Sends a `user_prompt` to a Claude model and returns its reply, synchronously. `model_name` must come from `get_dataforseo_ai_claude_llm_responses_models` - names look like `claude-sonnet-5`, and a plausible-looking guess is rejected. A sixteen-token reply measured $0.000744. Returns `model_name`, `input_tokens`, `output_tokens`, `reasoning_tokens`, `web_search`, `money_spent`, `datetime`, `items` and `fan_out_queries`. 💰 **Priced by tokens upstream, not per call**: a sixteen-token reply measured $0.0006, but nothing caps a long one, and AIsa bills a flat $0.012 either way. Read `money_spent` on the response to see what a prompt actually cost. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_ai_claude_llm_responses_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD includes the base task price plus the money_spent value tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.model_name: type: string description: name of the AI model used tasks.result.input_tokens: type: integer description: number of tokens in the input total count of tokens processed tasks.result.output_tokens: type: integer description: number of tokens in the output total count of tokens generated in the AI response tasks.result.reasoning_tokens: type: integer description: number of reasoning tokens total count of tokens used to generate reasoning content tasks.result.web_search: type: boolean description: indicates if web search was used tasks.result.money_spent: type: number description: cost of AI tokens, USD the price charged by the third-party AI model provider for according to its Pricing tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items: type: array items: type: string description: array of response items contains structured AI response data tasks.result.items.reasoning: type: object description: element in the response tasks.result.items.reasoning.type: type: string description: 'type of the element = ''reasoning'' Note: this element is supported only in reasoning models and is not guaranteed to be returned' tasks.result.items.reasoning.sections: type: array items: type: string description: reasoning chain sections array of objects containing the reasoning chain sections generated by the LLM tasks.result.items.reasoning.sections.type: type: string description: type of element='summary_text' tasks.result.items.reasoning.sections.text: type: string description: text of the reasoning chain section text of the reasoning chain section summarizing the model's thought process tasks.result.items.message: type: object description: element in the response tasks.result.items.message.type: type: string description: type of the element = 'message' tasks.result.items.message.sections: type: array items: type: string description: array of content sections contains different parts of the AI response tasks.result.items.message.sections.type: type: string description: type of element='text' tasks.result.items.message.sections.text: type: string description: AI-generated text content tasks.result.items.message.sections.annotations: type: array items: type: string description: 'array of references used to generate the response equals null if the web_search parameter is not set to true Note: annotations may return empty even when web_search is true, as the AI will attempt to retrieve web information but may not find relevant results' tasks.result.items.message.sections.annotations.title: type: string description: the domain name or title of the quoted source tasks.result.items.message.sections.annotations.url: type: string description: URL of the quoted source tasks.result.fan_out_queries: type: array items: type: string description: array of fan-out queries contains related search queries derived from the main query to provide a more comprehensive response '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically; you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value: 1; maximum value: 4096; default value: 2048; Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse; lower values make output more focused; minimum value: 0 maximum value: 1 default value: 0.7Note: temperature cannot be used together with top_p in the same request' top_p: type: number description: 'diversity of the AI response optional field controls diversity of the response by limiting token selection; minimum value: 0 maximum value: 1 default value: nullNote: top_p cannot be used together with temperature in the same request' web_search: type: boolean description: 'enable web search for current information optional field when enabled, the AI model can access and cite current web information; Note: refer to the Models endpoint for a list of models that support web_search; default value: false; The cost of the parameter can be calculated on the Pricing page' force_web_search: type: boolean description: 'force AI agent to use web search optional field to enable this parameter, web_search must also be enabled; when enabled, the AI model is forced to access and cite current web information; default value: false; Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response' web_search_country_iso_code: type: string description: 'ISO country code of the location optional field possible values: ''AR'',''AT'',''AU'',''BE'',''BR'',''CA'',''CH'',''CL'',''CN'',''DE'',''DK'',''ES'',''FI'',''FR'',''GB'',''HK'',''ID'',''IN'',''IT'',''JP'',''KR'',''MX'',''MY'',''NL'',''NO'',''NZ'',''PH'',''PL'',''PT'',''RU'',''SA'',''SE'',''TR'',''TW'',''US'',''ZA''' web_search_city: type: string description: 'city name of the location optional field Note: specify web_search_country_iso_code to use this parameter' system_message: type: string description: instructions for the AI behaviour optional field defines the AI's role, tone, or specific behavior; you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain role and message parameters: role string with either user or ai role; message string with message content (max 500 characters); you can specify the maximum of 10 message objects in the array; example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' use_reasoning: type: boolean description: 'enable reasoning for the AI model optional field when enabled, the model will perform reasoning before generating a response refer to the Models endpoint for a list of models that support reasoning default value: false Note: if set to true, the minimum value for max_output_tokens is 1025 Note #2: if set to true, force_web_search must be set to false Note #3: if set to true, the temperature and top_p cannot be used' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/claude/llm_responses/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/claude/llm_responses/models: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Claude Models for LLM Responses description: 'The Claude models available, each with `model_name`, `reasoning`, `web_search_supported` and `task_post_supported`. Measured at 1.8 KB. Free: upstream cost is 0. **Read it before calling** - `model_name` is matched exactly and an unlisted name is rejected with 40501 inside an HTTP 200.' operationId: get_dataforseo_ai_claude_llm_responses_models responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request result: type: array items: type: string description: array of results result.model_name: type: string description: name of the AI model result.reasoning: type: boolean description: indicates if the AI model supports reasoning result.web_search_supported: type: boolean description: web search support for the AI model if true, the web_search parameter can be set with the AI model result.task_post_supported: type: boolean description: indicates if Standard (POST-GET) data retrieval is supported if true, you can use the Standard (POST-GET) data retrieval method with the AI model '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/claude/llm_responses/models source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/claude/llm_responses/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get LLM Responses Claude Results by id description: 'Retrieves a queued Claude reply by `id`. Same shape as the live endpoint. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_ai_claude_llm_responses_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/claude/llm_responses/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/claude/llm_responses/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0204 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting LLM Responses Claude Tasks description: 'Queues a Claude prompt instead of waiting, returning a task `id`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Check `task_post_supported` in `get_dataforseo_ai_claude_llm_responses_models` first, and retrieve with `get_dataforseo_ai_claude_llm_responses_fetch`.' operationId: post_dataforseo_ai_claude_llm_responses_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system unique task identifier in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically; you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value: 1; maximum value: 4096; default value: 2048; Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse; lower values make output more focused; minimum value: 0 maximum value: 1 default value: 0.7Note: temperature cannot be used together with top_p in the same request' top_p: type: number description: 'diversity of the AI response optional field controls diversity of the response by limiting token selection; minimum value: 0 maximum value: 1 default value: nullNote: top_p cannot be used together with temperature in the same request' web_search: type: boolean description: 'enable web search for current information optional field when enabled, the AI model can access and cite current web information; Note: refer to the Models endpoint for a list of models that support web_search; default value: false; The cost of the parameter can be calculated on the Pricing page' force_web_search: type: boolean description: 'force AI agent to use web search optional field to enable this parameter, web_search must also be enabled; when enabled, the AI model is forced to access and cite current web information; default value: false; Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response' web_search_country_iso_code: type: string description: 'ISO country code of the location optional field possible values: ''AR'',''AT'',''AU'',''BE'',''BR'',''CA'',''CH'',''CL'',''CN'',''DE'',''DK'',''ES'',''FI'',''FR'',''GB'',''HK'',''ID'',''IN'',''IT'',''JP'',''KR'',''MX'',''MY'',''NL'',''NO'',''NZ'',''PH'',''PL'',''PT'',''RU'',''SA'',''SE'',''TR'',''TW'',''US'',''ZA''' web_search_city: type: string description: 'city name of the location optional field Note: specify web_search_country_iso_code to use this parameter' system_message: type: string description: instructions for the AI behaviour optional field defines the AI's role, tone, or specific behavior; you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain role and message parameters: role string with either user or ai role; message string with message content (max 500 characters); you can specify the maximum of 10 message objects in the array; example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' use_reasoning: type: boolean description: 'enable reasoning for the AI model optional field when enabled, the model will perform reasoning before generating a response refer to the Models endpoint for a list of models that support reasoning default value: false Note: if set to true, the minimum value for max_output_tokens is 1025 Note #2: if set to true, force_web_search must be set to false Note #3: if set to true, the temperature and top_p cannot be used' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special character in postback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special character in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/claude/llm_responses/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/claude/llm_responses/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get LLM Responses Claude Completed Tasks description: 'Lists finished Claude response tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_ai_claude_llm_responses_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request's URL result: type: array items: type: string description: array of results result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format result.se: type: string description: LLM model specified when setting the task result.function: type: string description: type of the task result.date_posted: type: string description: date when the task was posted (in the UTC format) result.tag: type: string description: user-defined task identifier result.endpoint: type: string description: URL for collecting the results of the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/claude/llm_responses/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_responses/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.001206 p50: 0.012 p95: 0.111706 max: 0.1414 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Gemini LLM Responses description: 'Sends a `user_prompt` to a Gemini model and returns its reply, synchronously. `model_name` must come from `get_dataforseo_ai_gemini_llm_responses_models`. `system_message` is accepted here, unlike on the Claude and ChatGPT live endpoints. Returns `model_name`, `input_tokens`, `output_tokens`, `reasoning_tokens`, `web_search`, `money_spent`, `datetime`, `items` and `fan_out_queries`. 💰 **Priced by tokens upstream, not per call**: a sixteen-token reply measured $0.0006, but nothing caps a long one, and AIsa bills a flat $0.012 either way. Read `money_spent` on the response to see what a prompt actually cost. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_ai_gemini_llm_responses_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD includes the base task price plus the money_spent value tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.model_name: type: string description: name of the AI model used tasks.result.input_tokens: type: integer description: number of tokens in the input total count of tokens processed tasks.result.output_tokens: type: integer description: number of tokens in the output total count of tokens generated in the AI response tasks.result.reasoning_tokens: type: integer description: number of reasoning tokens total count of tokens used to generate reasoning content tasks.result.web_search: type: boolean description: indicates if web search was used tasks.result.money_spent: type: number description: cost of AI tokens, USD the price charged by the third-party AI model provider for according to its Pricing tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items: type: array items: type: string description: array of response items contains structured AI response data tasks.result.items.reasoning: type: object description: element in the response tasks.result.items.reasoning.type: type: string description: 'type of the element = ''reasoning'' Note: this element is supported only in reasoning models and is not guaranteed to be returned' tasks.result.items.reasoning.sections: type: array items: type: string description: reasoning chain sections array of objects containing the reasoning chain sections generated by the LLM tasks.result.items.reasoning.sections.type: type: string description: type of element='summary_text' tasks.result.items.reasoning.sections.text: type: string description: text of the reasoning chain section text of the reasoning chain section summarizing the model's thought process tasks.result.items.message: type: object description: element in the response tasks.result.items.message.type: type: string description: type of the element = 'message' tasks.result.items.message.sections: type: array items: type: string description: array of content sections contains different parts of the AI response tasks.result.items.message.sections.type: type: string description: type of element='text' tasks.result.items.message.sections.text: type: string description: AI-generated text content tasks.result.items.message.sections.annotations: type: array items: type: string description: 'array of references used to generate the response equals null if the web_search parameter is not set to true Note: annotations may return empty even when web_search is true, as the AI will attempt to retrieve web information but may not find relevant results' tasks.result.items.message.sections.annotations.title: type: string description: the domain name or title of the quoted source tasks.result.items.message.sections.annotations.url: type: string description: redirect URL to the quoted source contains a Vertex AI redirect that leads to the original source tasks.result.fan_out_queries: type: array items: type: string description: array of fan-out queries contains related search queries derived from the main query to provide a more comprehensive response '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically; you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value: 1 maximum value: 4096; default value: 2048; Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse lower values make output more focused minimum value: 0 maximum value: 2 default value: 1.3' top_p: type: number description: 'diversity of the AI response optional field controls diversity of the response by limiting token selection minimum value: 0 maximum value: 1 default value: 0.9' web_search: type: boolean description: 'enable web search for current information optional field when enabled, the AI model can access and cite current web information; Note: refer to the Models endpoint for a list of models that support web_search; default value: false; The cost of the parameter can be calculated on the Pricing page' system_message: type: string description: instructions for the AI behavior optional field defines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain role and message parameters: role string with either user or ai role; message string with message content (max 500 characters); you can specify the maximum of 10 message objects in the array; example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' use_reasoning: type: boolean description: 'enable reasoning for the AI model optional field when enabled, the model will perform reasoning before generating a response refer to the Models endpoint for a list of models that support reasoning default value: false Note: if set to true, the minimum value for max_output_tokens is 1024 Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_responses/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_responses/models: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Gemini models for LLM Responses description: 'The Gemini models available, each with `model_name`, `reasoning`, `web_search_supported` and `task_post_supported`. Measured at 1.5 KB. Free: upstream cost is 0. Read it before calling; an unlisted `model_name` is rejected with 40501 inside an HTTP 200.' operationId: get_dataforseo_ai_gemini_llm_responses_models responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request result: type: array items: type: string description: array of results result.model_name: type: string description: name of the AI model result.reasoning: type: boolean description: indicates if the AI model supports reasoning result.web_search_supported: type: boolean description: web search support for the AI model if true, the web_search parameter can be set with the AI model result.task_post_supported: type: boolean description: indicates if Standard (POST-GET) data retrieval is supported if true, you can use the Standard (POST-GET) data retrieval method with the AI model '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_responses/models source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_responses/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get LLM Responses Gemini Results by id description: 'Retrieves a queued Gemini reply by `id`. Same shape as the live endpoint. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_ai_gemini_llm_responses_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_responses/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_responses/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0204 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘LLM Responses Gemini’ Tasks description: 'Queues a Gemini prompt instead of waiting, returning a task `id`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Check `task_post_supported` in `get_dataforseo_ai_gemini_llm_responses_models`, and retrieve with `get_dataforseo_ai_gemini_llm_responses_fetch`.' operationId: post_dataforseo_ai_gemini_llm_responses_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system unique task identifier in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically; you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value: 1; maximum value: 4096; default value: 2048; Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse lower values make output more focused minimum value: 0 maximum value: 2 default value: 1.3' top_p: type: number description: 'diversity of the AI response optional field controls diversity of the response by limiting token selection minimum value: 0 maximum value: 1 default value: 0.9' web_search: type: boolean description: 'enable web search for current information optional field when enabled, the AI model can access and cite current web information; Note: refer to the Models endpoint for a list of models that support web_search; default value: false; The cost of the parameter can be calculated on the Pricing page' system_message: type: string description: instructions for the AI behavior optional field defines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain role and message parameters: role string with either user or ai role; message string with message content (max 500 characters); you can specify the maximum of 10 message objects in the array; example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' use_reasoning: type: boolean description: 'enable reasoning for the AI model optional field when enabled, the model will perform reasoning before generating a response refer to the Models endpoint for a list of models that support reasoning default value: false Note: if set to true, the minimum value for max_output_tokens is 1024 Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special character in postback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special character in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_responses/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_responses/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get LLM Responses Gemini Completed Tasks description: 'Lists finished Gemini response tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_ai_gemini_llm_responses_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request's URL result: type: array items: type: string description: array of results result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format result.se: type: string description: LLM model specified when setting the task result.function: type: string description: type of the task result.date_posted: type: string description: date when the task was posted (in the UTC format) result.tag: type: string description: user-defined task identifier result.endpoint: type: string description: URL for collecting the results of the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_responses/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Gemini LLM Scraper Languages List description: 'The languages the Gemini scraper accepts, as `language_name` and `language_code`. Measured at 5.1 KB. Free: upstream cost is 0. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_ai_gemini_llm_scraper_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request result: type: array items: type: string description: array of results result.language_name: type: string description: language name result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 p50: 0.008 p95: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Gemini LLM Scraper Advanced description: 'Asks Gemini a `keyword` as a user would and returns the answer parsed. Returns `keyword`, `location_code`, `language_code`, `model`, `datetime`, `markdown`, `sources`, `se_results_count`, `item_types`, `items_count` and `items`. Measured at 26.1 KB and $0.004 - more than twice the ChatGPT equivalent''s payload for the same question. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The ChatGPT twin is `post_dataforseo_ai_chat_gpt_llm_scraper_live`; running both and comparing is the point of this family.' operationId: post_dataforseo_ai_gemini_llm_scraper_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword received in a POST array the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character) tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.model: type: string description: indicates the model version tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.sources: type: array items: type: string description: array of sources the sources the model actually cited or relied on in its final answer tasks.result.sources.type: type: string description: type of element='gemini_source' tasks.result.sources.title: type: string description: source title tasks.result.sources.snippet: type: string description: source description tasks.result.sources.domain: type: string description: source domain tasks.result.sources.url: type: string description: source URL tasks.result.sources.thumbnail: type: string description: source thumbnail tasks.result.sources.source_name: type: string description: source name tasks.result.sources.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.sources.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.se_results_count: type: integer description: total number of results tasks.result.item_types: type: array items: type: string description: 'types of search results contains types of search results (items) found in SERP. possible item types: gemini_text, gemini_table, gemini_images' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: elements of Gemini results tasks.result.items.gemini_text: type: object description: element in the response tasks.result.items.gemini_text.type: type: string description: type of element='gemini_text' tasks.result.items.gemini_text.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.gemini_text.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.gemini_text.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.gemini_text.original_text: type: string description: unformatted text content of the element tasks.result.items.gemini_text.sources: type: array items: type: string description: array of sources tasks.result.items.gemini_text.sources.type: type: string description: type of element='gemini_source' tasks.result.items.gemini_text.sources.title: type: string description: source title tasks.result.items.gemini_text.sources.snippet: type: string description: source description tasks.result.items.gemini_text.sources.domain: type: string description: source domain in SERP tasks.result.items.gemini_text.sources.url: type: string description: source URL tasks.result.items.gemini_text.sources.thumbnail: type: string description: source thumbnail tasks.result.items.gemini_text.sources.source_name: type: string description: source name tasks.result.items.gemini_text.sources.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.gemini_text.sources.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.gemini_table: type: object description: element in the response tasks.result.items.gemini_table.type: type: string description: type of element='gemini_table' tasks.result.items.gemini_table.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.gemini_table.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.gemini_table.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.gemini_table.original_text: type: string description: unformatted text content of the element tasks.result.items.gemini_table.table: type: object description: table present in the element the header and content of the table present in the element tasks.result.items.gemini_table.table.table_header: type: array items: type: string description: content in the header of the table tasks.result.items.gemini_table.table.table_content: type: array items: type: string description: array of contents of the table present in the element each array represents the table row tasks.result.items.gemini_images: type: object description: element in the response tasks.result.items.gemini_images.type: type: string description: type of element='gemini_images' tasks.result.items.gemini_images.rank_group: type: integer description: group rank in SERP position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.gemini_images.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.gemini_images.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.gemini_images.items: type: array items: type: string description: items present in the element tasks.result.items.gemini_images.items.type: type: string description: type of element = 'gemini_images_element' tasks.result.items.gemini_images.items.url: type: string description: relevant URL tasks.result.items.gemini_images.items.alt: type: string description: alt tag of the image tasks.result.items.gemini_images.items.image_url: type: string description: URL of the image the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available) tasks.result.items.gemini_images.items.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 2000 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don''t specify location_code if you use this field, you don''t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations example: United States' location_code: type: integer description: 'search engine location code required field if you don''t specify location_name if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations example: 2840' language_name: type: string description: 'full name of search engine language required field if you don''t specify language_code; if you use this field, you don''t need to specify language_code; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages example: English' language_code: type: string description: 'search engine language code required field if you don''t specify language_name; if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages example: enn' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response location_coordinate: type: string description: Search location as latitude,longitude,radius. Use instead of location_name or location_code. required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Gemini LLM Scraper HTML description: 'The same Gemini answer as `post_dataforseo_ai_gemini_llm_scraper_live`, returned as raw HTML. `expand_citations` unfolds the source list. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Larger than the 26.1 KB parsed form; take it only when you need markup the parser dropped.' operationId: post_dataforseo_ai_gemini_llm_scraper_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword received in a POST array keyword is returned with decoded %## (plus character '+' will be decoded to a space character) tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: elements of search results found tasks.result.items.page: type: integer description: serial number of the returned HTML page tasks.result.items.date: type: string description: 'date and time when the HTML page was scanned in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.html: type: string description: HTML page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 2000 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don''t specify location_code if you use this field, you don''t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations example: United States' location_code: type: integer description: 'search engine location code required field if you don''t specify location_name if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations example: 2840' language_name: type: string description: 'full name of search engine language required field if you don''t specify language_code if you use this field, you don''t need to specify language_code you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages example: English' language_code: type: string description: search engine language code required field if you don't specify language_name if you use this field, you don't need to specify language_name you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages example:enn expand_citations: type: boolean description: 'return expanded citation bar in HTML results optional field when enabled, the endpoint will return HTML data from the expanded citation bar; default value: false' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response location_coordinate: type: string description: Search location as latitude,longitude,radius. Use instead of location_name or location_code. required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Gemini LLM Scraper Locations List description: 'The locations the Gemini scraper accepts, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 42 MB** - every city and region worldwide, and the third Google-side location catalogue in this provider to measure over 40 MB. Do not call it from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s documentation. Free upstream, so nothing warns you.' operationId: get_dataforseo_ai_gemini_llm_scraper_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.location_code_parent: type: integer description: 'the code of the superordinate location example: "location_code": 9041134, "location_name": "Vienna International Airport,Lower Austria,Austria", "location_code_parent": 20044where location_code_parent corresponds to:"location_code": 20044, "location_name": "Lower Austria,Austria"' tasks.result.country_iso_code: type: string description: ISO country code of the location tasks.result.location_type: type: string description: location type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Gemini LLM Scraper Advanced description: 'Retrieves a queued Gemini scrape by `id`, parsed. Same shape as `post_dataforseo_ai_gemini_llm_scraper_live`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_ai_gemini_llm_scraper_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier a universally unique identifier (UUID) unique task identifier in our system you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Gemini LLM Scraper HTML description: 'Retrieves a queued Gemini scrape by `id` as raw HTML. ⚠️ Larger than the parsed twin `get_dataforseo_ai_gemini_llm_scraper_fetch`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_ai_gemini_llm_scraper_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Gemini LLM Scraper description: 'Queues a Gemini scrape instead of waiting for one, returning a task `id`. `priority` moves it up the queue. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_ai_gemini_llm_scraper_fetch`, or the HTML form with `get_dataforseo_ai_gemini_llm_scraper_fetch_html`. Use it when a batch of keywords would outlast a tool call''s patience; the live endpoint is simpler for one.' operationId: post_dataforseo_ai_gemini_llm_scraper_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 2000 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priorityYou will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of search engine location required field if you don''t specify location_code if you use this field, you don''t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations example: United States' location_code: type: integer description: 'search engine location code required field if you don''t specify location_name if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations example: 2840' language_name: type: string description: 'full name of search engine language required field if you don''t specify language_code; if you use this field, you don''t need to specify language_code; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages example: English' language_code: type: string description: 'search engine language code required field if you don''t specify language_name; if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages example: en' expand_citations: type: boolean description: 'return expanded citation bar in HTML results optional field when enabled, the HTML endpoint will return data from the expanded citation bar; default value: false' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the function you used for setting a task possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' location_coordinate: type: string description: Search location as latitude,longitude,radius. Use instead of location_name or location_code. required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/gemini/llm_scraper/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Gemini LLM Scraper Completed Tasks description: 'Lists finished Gemini scrape tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_ai_gemini_llm_scraper_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request's URL result: type: array items: type: string description: array of results result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format result.se: type: string description: search engine specified when setting the task result.function: type: string description: 'search engine function example: llm_scraper' result.date_posted: type: string description: date when the task was posted (in the UTC format) result.tag: type: string description: user-defined task identifier result.endpoint_advanced: type: string description: URL for collecting the results of the Advanced task if the Advanced function is not supported in the specified endpoint, the value will be null result.endpoint_html: type: string description: URL for collecting the results of the HTML task if the HTML function is not supported in the specified endpoint, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/gemini/llm_scraper/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/aggregated_metrics/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.202 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live LLM Mentions Aggregated Metrics description: 'How often assistants mention your target, as totals rather than individual answers: `total` and `items`. Measured at 7.0 KB. 🔴 **Measured at $0.101 upstream, roughly eight times the flat rate billed** - among the most expensive endpoints in this provider. ⚠️ `target` is an **array of objects**, each `{"domain": "..."}` or `{"keyword": "..."}`; a bare string is rejected as the wrong type and an array of strings as ''Each target item must be an object''. Filter fields come from `get_dataforseo_ai_llm_mentions_available_filters`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the headline visibility number; `post_dataforseo_ai_llm_mentions_search_live` shows the answers behind it, and `post_dataforseo_ai_llm_mentions_cross_metrics_live` compares several targets at once.' operationId: post_dataforseo_ai_llm_mentions_aggregated_metrics_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total: type: object description: aggregated mentions metrics summary contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions tasks.result.total.location: type: array items: type: string description: location-based grouping array of objects containing mention metrics segmented by geographical location tasks.result.total.location.type: type: string description: type of the element = 'group_element' tasks.result.total.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.language: type: array items: type: string description: language-based grouping array of objects containing mention metrics segmented by content language tasks.result.total.language.type: type: string description: type of the element = 'group_element' tasks.result.total.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.platform: type: array items: type: string description: platform-based grouping array of group elements containing mention metrics segmented by AI platform tasks.result.total.platform.type: type: string description: type of the element = 'group_element' tasks.result.total.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.sources_domain: type: array items: type: string description: found top source domains relevant to the target array of objects containing data on top domains that are cited as sources in LLM responses tasks.result.total.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.search_results_domain: type: array items: type: string description: found top search results domains relevant to the target array of objects containing data on top domains that appear in search results related to LLM queries tasks.result.total.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.total.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.total.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.total.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.total.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items: type: array items: type: string description: individual pages results array containing detailed mention metrics for each of the found top pages in this case, equals null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: array items: type: object properties: domain: type: string description: target domain required field if you don't specify keyword you can specify up to 63 characters in the domain field; a domain should be specified without https:// and www. keyword: type: string description: target keyword required field if you don't specify domain you can specify up to 250 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article search_filter: type: string description: 'Entity search filter: include or exclude; defaults to include.' search_scope: type: array items: type: string description: 'Search scope. Domain entities: any, sources, search_results. Keyword entities: any, question, answer, brand_entities, fan_out_queries. Default: any.' include_subdomains: type: boolean description: 'indicates if the subdomains of the target domain will be included in the search optional field if set to true, the subdomains will be included in the search default value: false' match_type: type: string description: 'target keyword match type optional field word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for “light” will return results with “light bulb”, “light switch”); partial_match - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for “light” will return results with “lighting”, “highlight”); possible values: word_match, partial_match default value: word_match' oneOf: - required: - domain - required: - keyword description: 'array of objects containing target entities required field you can specify up to 10 entities (objects) in the target field one target entity can contain either one domain or one keyword and related parametersexamples: target array with a domain entity [{"domain": "en.wikipedia.org", "search_filter": "exclude"}] target array with a keyword entity [{"keyword": "bmw", "search_scope": ["question"], "match_type ": "partial_match"}] target array with multiple entities [{"domain": "en.wikipedia.org", "search_filter": "exclude"}, {"keyword": "bmw", "match_type ": "partial_match", "search_scope": ["answer"]}]' location_name: type: string description: 'full name of search location optional field if you use this field, you don''t need to specify location_code if you don''t specify this field, the location_code with 2840 value will be used by default; you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for United States only' location_code: type: integer description: 'search location code optional field if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: 2840 Note: chat_gpt data is available for 2840 only' language_name: type: string description: 'full name of search language optional field if you use this field, you don''t need to specify language_code; if you don''t specify this field, the language_code with en value will be used by default; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for English only' language_code: type: string description: 'search language code optional field if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: en Note: chat_gpt data is available for en onlyn' platform: type: string description: 'target platform optional field possible values: chat_gpt, google default value: google Note: the data returned depends on the selected platform Note #2:chat_gpt data is available for the United States and English only' initial_dataset_filters: type: array items: {} description: 'array of filter expressions applied before aggregation optional field you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["ai_search_volume",">","1000"]the full list of possible filters is available here. learn more about the initial dataset filters in this help center article.' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: sources_domain search_results_domain minimum value: 1 maximum value: 20 default value: 10' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target example: - target: - domain: en.wikipedia.org tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/aggregated_metrics/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/cross_aggregated_metrics/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.202 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live LLM Mentions Cross Aggregated Metrics description: 'Compares mention metrics across several targets in one call, grouped by `aggregation_key`. Takes `targets` as a list of target arrays rather than the single `target` its siblings take - the shapes differ, and mixing them up is rejected as an unknown field. 🔴 **Measured at $0.101 upstream, roughly eight times the flat rate billed** - among the most expensive endpoints in this provider. ⚠️ `target` is an **array of objects**, each `{"domain": "..."}` or `{"keyword": "..."}`; a bare string is rejected as the wrong type and an array of strings as ''Each target item must be an object''. Filter fields come from `get_dataforseo_ai_llm_mentions_available_filters`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Running `post_dataforseo_ai_llm_mentions_aggregated_metrics_live` once per target costs the same per call, so use this when the comparison itself is the point.' operationId: post_dataforseo_ai_llm_mentions_cross_metrics_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total: type: object description: aggregated mentions metrics summary contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions tasks.result.total.location: type: array items: type: string description: location-based grouping array of objects containing mention metrics segmented by geographical location tasks.result.total.location.type: type: string description: type of the element = 'group_element' tasks.result.total.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.language: type: array items: type: string description: language-based grouping array of objects containing mention metrics segmented by content language tasks.result.total.language.type: type: string description: type of the element = 'group_element' tasks.result.total.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.platform: type: array items: type: string description: platform-based grouping array of group elements containing mention metrics segmented by AI platform tasks.result.total.platform.type: type: string description: type of the element = 'group_element' tasks.result.total.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.sources_domain: type: array items: type: string description: found top source domains relevant to the target array of objects containing data on top domains that are cited as sources in LLM responses tasks.result.total.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.search_results_domain: type: array items: type: string description: found top search results domains relevant to the target array of objects containing data on top domains that appear in search results related to LLM queries tasks.result.total.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.total.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.total.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.total.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.total.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items: type: array items: type: string description: contains relevant mentions data tasks.result.items.key: type: string description: aggregation key received in a POST array tasks.result.items.location: type: array items: type: string description: location-based grouping array of objects containing mention metrics segmented by geographical location tasks.result.items.location.type: type: string description: type of the element = 'group_element' tasks.result.items.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.language: type: array items: type: string description: language-based grouping array of objects containing mention metrics segmented by content language tasks.result.items.language.type: type: string description: type of the element = 'group_element' tasks.result.items.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.platform: type: array items: type: string description: platform-based grouping array of group elements containing mention metrics segmented by AI platform tasks.result.items.platform.type: type: string description: type of the element = 'group_element' tasks.result.items.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.sources_domain: type: array items: type: string description: found top source domains relevant to the target array of objects containing data on top domains that are cited as sources in LLM responses tasks.result.items.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.items.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.items.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.search_results_domain: type: array items: type: string description: found top search results domains relevant to the target array of objects containing data on top domains that appear in search results related to LLM queries tasks.result.items.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.items.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.items.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.items.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.items.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.items.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.items.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.items.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.items.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: object properties: aggregation_key: type: string description: aggregation key for grouping the results required field groups results for comparison and serves as a label for the group; you can specify up to 250 characters in the aggregation_key field target: type: array items: type: object properties: domain: type: string description: target domain required field if you don't specify a keyword you can specify up to 63 characters in the domain field; a domain should be specified without https:// and www. keyword: type: string description: target keyword required field if you don't specify a domain you can specify up to 250 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article search_filter: type: string description: 'Entity search filter: include or exclude; defaults to include.' search_scope: type: array items: type: string description: 'Search scope. Domain entities: any, sources, search_results. Keyword entities: any, question, answer, brand_entities, fan_out_queries. Default: any.' include_subdomains: type: boolean description: 'indicates if the subdomains of the target domain will be included in the search optional field if set to true, the subdomains will be included in the search default value: false' match_type: type: string description: 'target keyword match type defines how the specified keyword is matched optional field possible values: word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for "light" will return results with "light bulb", "light switch"); partial_match - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for "light" will return results with "lighting", "highlight"); default value: word_match' oneOf: - required: - domain - required: - keyword description: array of objects containing target entities required field a single target can contain up to 10 domain and/or keyword entities required: - aggregation_key - target description: 'array of objects containing target entities with aggregation keys required field you can specify up to 10, but not less than 2 target sets of parameters, each with its aggregation_key;example of a targets array with multiple entities: [{"aggregation_key":"bmw","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"m5","match_type":"partial_match","search_scope":["answer"]}]},{"aggregation_key":"mercedes","target":[{"domain":"www.mercedes-benz.com","search_filter":"exclude"},{"keyword":"GLC","match_type":"word_match"}]}]' location_name: type: string description: 'full name of search location optional field if you use this field, you don''t need to specify location_code if you don''t specify this field, the location_code with 2840 value will be used by default; you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for United States only' location_code: type: integer description: 'search location code optional field if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: 2840 Note: chat_gpt data is available for 2840 only' language_name: type: string description: 'full name of search language optional field if you use this field, you don''t need to specify language_code; if you don''t specify this field, the language_code with en value will be used by default; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for English only' language_code: type: string description: 'search language code optional field if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: en Note: chat_gpt data is available for en onlyn' platform: type: string description: 'target platform optional field possible values: chat_gpt, google default value: google Note: the data returned depends on the selected platform Note #2:chat_gpt data is available for the United States and English only' initial_dataset_filters: type: array items: {} description: 'array of filter expressions applied before aggregation optional field you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["ai_search_volume",">","1000"]the full list of possible filters is available here. learn more about the initial dataset filters in this help center article.' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: sources_domain search_results_domain minimum value: 1 maximum value: 10 default value: 5' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/cross_aggregated_metrics/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/available_filters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Filters for AI Optimization LLM Mentions API description: 'The filterable fields for each mentions endpoint, keyed by endpoint: `search`, `search_mentions`, `target_metrics`, `multi_target_metrics`, `top_mentioned_domains`, `top_mentioned_pages`, `top_mentioned_brands`, `top_mentioned_brand_categories` and the `_lite` variants. Measured at 4.9 KB. Free: upstream cost is 0. Read it before building a `filters` argument - the mentions endpoints cost $0.101 each, so a rejected call is an expensive way to learn a field name.' operationId: get_dataforseo_ai_llm_mentions_available_filters responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results contains the full list of available parameters that can be used for data filtration the parameters are grouped by the endpoint they can be used with '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/available_filters source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/locations_and_languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations and Languages for AI Optimization LLM Mentions API description: 'The locations and languages the mentions endpoints accept, as `location_code`, `location_name` and `available_languages` - languages are nested per location rather than listed separately. Measured at 58.6 KB. Free: upstream cost is 0. Reference data, so fetch once and reuse.' operationId: get_dataforseo_ai_llm_mentions_locales responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.available_languages: type: array items: type: string description: supported languages contains the languages which are supported for a specific location tasks.result.available_languages.available_platforms: type: array items: type: string description: supported LLM platforms contains the sources of data supported for a specific location and language combination only google and chat_gpt are currently available tasks.result.available_languages.language_name: type: string description: language name tasks.result.available_languages.language_code: type: string description: language code according to ISO 639-1 tasks.result.available_languages.responses_count: type: integer description: number of LLM responses the number of LLM responses available in the database for the certain location and language parameters '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/locations_and_languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/search/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.4 max: 1.478 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live LLM Mentions description: 'The individual answers in which an assistant mentioned your target. Returns `total_count`, `current_offset`, `search_after_token` and `items` - page with the token, not `offset`, past the first pages. Measured at 7.7 KB for one item. 🔴 **Measured at $0.101 upstream, roughly eight times the flat rate billed** - among the most expensive endpoints in this provider. ⚠️ `target` is an **array of objects**, each `{"domain": "..."}` or `{"keyword": "..."}`; a bare string is rejected as the wrong type and an array of strings as ''Each target item must be an object''. Filter fields come from `get_dataforseo_ai_llm_mentions_available_filters`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For counts rather than the mentions themselves use `post_dataforseo_ai_llm_mentions_aggregated_metrics_live`.' operationId: post_dataforseo_ai_llm_mentions_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total amount of results relevant the request tasks.result.current_offset: type: integer description: the number of mentions objects that are omitted in the items array tasks.result.search_after_token: type: string description: token for subsequent requests by specifying the unique search_after_token when setting a new task, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant mentions data tasks.result.items.platform: type: string description: platform received in a POST array tasks.result.items.model_name: type: string description: 'name of the AI model from which the data was retrieved Note: for the google platform type, the value is always google_ai_overview' tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.question: type: string description: relevant question tasks.result.items.answer: type: string description: relevant answer in markdown format content of the result formatted in the markdown markup language tasks.result.items.sources: type: array items: type: string description: array of sources the sources the model cited or relied on in its final answer tasks.result.items.sources.snippet: type: string description: source description tasks.result.items.sources.source_name: type: string description: source name tasks.result.items.sources.thumbnail: type: string description: source thumbnail tasks.result.items.sources.markdown: type: string description: content of the element in markdown format content of the result formatted in the markdown markup language tasks.result.items.sources.position: type: integer description: position in the results tasks.result.items.sources.title: type: string description: source title tasks.result.items.sources.domain: type: string description: source domain tasks.result.items.sources.url: type: string description: source URL tasks.result.items.sources.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_results: type: array items: type: string description: array of search results all web search outputs the model retrieved when looking up information, including duplicates and unused entries tasks.result.items.search_results.description: type: string description: result description tasks.result.items.search_results.breadcrumb: type: string description: breadcrumb tasks.result.items.search_results.position: type: integer description: position in the results tasks.result.items.search_results.title: type: string description: result title tasks.result.items.search_results.domain: type: string description: result domain tasks.result.items.search_results.url: type: string description: result URL tasks.result.items.search_results.publication_date: type: string description: 'date and time when the result was published in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.monthly_searches: type: array items: type: string description: monthly AI search volume rates array of objects with AI search volume rates in a certain month of a year tasks.result.items.monthly_searches.year: type: integer description: year tasks.result.items.monthly_searches.month: type: integer description: month tasks.result.items.monthly_searches.search_volume: type: integer description: AI search volume rate in a certain month of a year learn more about this metric here tasks.result.items.first_response_at: type: string description: 'date and time when the response data was first recorded in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2025-10-21 06:25:30 +00:00' tasks.result.items.last_response_at: type: string description: 'date and time when the response data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2025-10-21 06:25:30 +00:00' tasks.result.items.brand_entities: type: array items: type: string description: array of brand entities contains information on brands mentioned in the response tasks.result.items.brand_entities.position: type: integer description: position in the results tasks.result.items.brand_entities.title: type: string description: name of the brand tasks.result.items.brand_entities.category: type: string description: category of the brand tasks.result.items.fan_out_queries: type: array items: type: string description: array of fan-out queries contains related search queries derived from the main query to provide a more comprehensive response '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: array items: type: object properties: domain: type: string description: target domain required field if you don't specify keyword you can specify up to 63 characters in the domain field; a domain should be specified without https:// and www. keyword: type: string description: target keyword required field if you don't specify domain you can specify up to 250 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article search_filter: type: string description: 'Entity search filter: include or exclude; defaults to include.' search_scope: type: array items: type: string description: 'Search scope. Domain entities: any, sources, search_results. Keyword entities: any, question, answer, brand_entities, fan_out_queries. Default: any.' include_subdomains: type: boolean description: 'indicates if the subdomains of the target domain will be included in the search optional field if set to true, the subdomains will be included in the search default value: false' match_type: type: string description: 'target keyword match type defines how the specified keyword is matched optional field possible values: word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for "light" will return results with "light bulb", "light switch"); partial_match - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for "light" will return results with "lighting", "highlight"); default value: word_match' oneOf: - required: - domain - required: - keyword description: 'array of objects containing target entities required field you can specify up to 10 entities (objects) in the target field one target entity can contain either one domain or one keyword and related parametersexamples: target array with a domain entity [{"domain": "en.wikipedia.org", "search_filter": "exclude"}] target array with a keyword entity [{"keyword": "bmw", "search_scope": ["question"], "match_type ": "partial_match"}] target array with multiple entities [{"domain": "en.wikipedia.org", "search_filter": "exclude"}, {"keyword": "bmw", "match_type ": "partial_match", "search_scope": ["answer"]}]' location_name: type: string description: 'full name of search location optional field if you use this field, you don''t need to specify location_code if you don''t specify this field, the location_code with 2840 value will be used by default; you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for United States only' location_code: type: integer description: 'search location code optional field if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: 2840 Note: chat_gpt data is available for 2840 only' language_name: type: string description: 'full name of search language optional field if you use this field, you don''t need to specify language_code; if you don''t specify this field, the language_code with en value will be used by default; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for English only' language_code: type: string description: 'search language code optional field if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: en Note: chat_gpt data is available for en onlyn' platform: type: string description: 'target platform optional field possible values: chat_gpt, google default value: google Note: the data returned depends on the selected platform Note #2:chat_gpt data is available for the United States and English only' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["ai_search_volume",">","1000"]The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc - results will be sorted in the ascending order desc - results will be sorted in the descending order you should use a comma to set up a sorting type example: ["ai_search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules' offset: type: integer description: 'offset in the results array of the returned mentions data optional fielddefault value: 0 example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects; Note: the maximum value is 9,000, use the search_after_token if you would like to offset more results' search_after_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request; by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task ; Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request' limit: type: integer description: 'the maximum number of returned objects optional fielddefault value: 100 maximum value: 1000' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/search/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/top_domains/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.202 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live LLM Mentions Top Domains description: 'The domains assistants cite most when answering about your target: `total` and `items`. Measured at 20.3 KB, the largest response in the mentions family. 🔴 **Measured at $0.101 upstream, roughly eight times the flat rate billed** - among the most expensive endpoints in this provider. ⚠️ `target` is an **array of objects**, each `{"domain": "..."}` or `{"keyword": "..."}`; a bare string is rejected as the wrong type and an array of strings as ''Each target item must be an object''. Filter fields come from `get_dataforseo_ai_llm_mentions_available_filters`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the list to pitch: these are the pages shaping what assistants say. For individual pages rather than domains use `post_dataforseo_ai_llm_mentions_top_pages_live`.' operationId: post_dataforseo_ai_llm_mentions_top_domains_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total: type: object description: aggregated mentions metrics summary contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions tasks.result.total.location: type: array items: type: string description: location-based grouping array of objects containing mention metrics segmented by geographical location tasks.result.total.location.type: type: string description: type of the element = 'group_element' tasks.result.total.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.language: type: array items: type: string description: language-based grouping array of objects containing mention metrics segmented by content language tasks.result.total.language.type: type: string description: type of the element = 'group_element' tasks.result.total.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.platform: type: array items: type: string description: platform-based grouping array of group elements containing mention metrics segmented by AI platform tasks.result.total.platform.type: type: string description: type of the element = 'group_element' tasks.result.total.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.sources_domain: type: array items: type: string description: found top source domains relevant to the target array of objects containing data on top domains that are cited as sources in LLM responses tasks.result.total.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.search_results_domain: type: array items: type: string description: found top search results domains relevant to the target array of objects containing data on top domains that appear in search results related to LLM queries tasks.result.total.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.total.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.total.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.total.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.total.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items: type: array items: type: string description: individual domain results array containing detailed mention metrics for each of the found top domains tasks.result.items.key: type: string description: domain name the domain name of the website found in LLM mentions for the specified target tasks.result.items.location: type: array items: type: string description: location-based grouping array of objects containing domain mention metrics segmented by geographical location tasks.result.items.location.type: type: string description: type of the element = 'group_element' tasks.result.items.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.language: type: array items: type: string description: language-based grouping array of objects containing domain mention metrics segmented by content language tasks.result.items.language.type: type: string description: type of the element = 'group_element' tasks.result.items.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.platform: type: array items: type: string description: platform-based grouping array of group elements containing domain mention metrics segmented by AI platform tasks.result.items.platform.type: type: string description: type of the element = 'group_element' tasks.result.items.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.sources_domain: type: array items: type: string description: source domains relevant to the specific top domain array of objects containing data on domains that are cited as sources in LLM responses tasks.result.items.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.items.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.items.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.search_results_domain: type: array items: type: string description: search results domains relevant to the specific top domain array of objects containing data on domains that appear in search results related to LLM queries tasks.result.items.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.items.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.items.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.items.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.items.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.items.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.items.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.items.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.items.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: array items: type: object properties: domain: type: string description: target domain required field if you don't specify keyword you can specify up to 63 characters in the domain field; a domain should be specified without https:// and www. keyword: type: string description: target keyword required field if you don't specify domain you can specify up to 250 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article search_filter: type: string description: 'Entity search filter: include or exclude; defaults to include.' search_scope: type: array items: type: string description: 'Search scope. Domain entities: any, sources, search_results. Keyword entities: any, question, answer, brand_entities, fan_out_queries. Default: any.' include_subdomains: type: boolean description: 'indicates if the subdomains of the target domain will be included in the search optional field if set to true, the subdomains will be included in the search default value: false' match_type: type: string description: 'target keyword match type optional field possible values: word_match, partial_match word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the seed key phrase. partial_match - searches for any occurrence of the keyword or its parts within the content default value: word_match' oneOf: - required: - domain - required: - keyword description: 'array of objects containing target entities required field you can specify up to 10 entities (objects) in the target field one target entity can contain either one domain or one keyword and related parametersexamples: target array with a domain entity [{"domain": "en.wikipedia.org", "search_filter": "exclude"}] target array with a keyword entity [{"keyword": "bmw", "search_scope": ["question"], "match_type ": "partial_match"}] target array with multiple entities [{"domain": "en.wikipedia.org", "search_filter": "exclude"}, {"keyword": "bmw", "match_type ": "partial_match", "search_scope": ["answer"]}]' location_name: type: string description: 'full name of search location optional field if you use this field, you don''t need to specify location_code if you don''t specify this field, the location_code with 2840 value will be used by default; you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for United States only' location_code: type: integer description: 'search location code optional field if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: 2840 Note: chat_gpt data is available for 2840 only' language_name: type: string description: 'full name of search language optional field if you use this field, you don''t need to specify language_code; if you don''t specify this field, the language_code with en value will be used by default; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for English only' language_code: type: string description: 'search language code optional field if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: en Note: chat_gpt data is available for en onlyn' platform: type: string description: 'target platform optional field possible values: chat_gpt, google default value: google Note: the data returned depends on the selected platform Note #2:chat_gpt data is available for the United States and English only' links_scope: type: string description: 'links source scope optional field this parameter specifies which links will be used to extract domains and aggregation data possible values: sources, search_results default value: sources' initial_dataset_filters: type: array items: {} description: 'array of filter expressions applied before aggregation optional field you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["ai_search_volume",">","1000"]the full list of possible filters is available here. learn more about the initial dataset filters in this help center article.' items_list_limit: type: integer description: 'maximum number of results in the items array optional field you can use this parameter to limit the number of data objects you receive in the items array minimum value: 1 maximum value: 10 default value: 5' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: sources_domain search_results_domain minimum value: 1 maximum value: 10 default value: 5' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/top_domains/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/llm_mentions/top_pages/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.202 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live LLM Mentions Top Pages description: 'The individual pages assistants cite most when answering about your target: `total` and `items`. Measured at 13.1 KB. 🔴 **Measured at $0.101 upstream, roughly eight times the flat rate billed** - among the most expensive endpoints in this provider. ⚠️ `target` is an **array of objects**, each `{"domain": "..."}` or `{"keyword": "..."}`; a bare string is rejected as the wrong type and an array of strings as ''Each target item must be an object''. Filter fields come from `get_dataforseo_ai_llm_mentions_available_filters`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. More actionable than its domain-level twin `post_dataforseo_ai_llm_mentions_top_domains_live` when you want to know which article to update or pitch, rather than which publisher.' operationId: post_dataforseo_ai_llm_mentions_top_pages_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total: type: object description: aggregated mentions metrics summary contains overall aggregated LLM mention metrics across all found top pages, grouped by various dimensions tasks.result.total.location: type: array items: type: string description: location-based grouping array of objects containing mention metrics segmented by geographical location tasks.result.total.location.type: type: string description: type of the element = 'group_element' tasks.result.total.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.language: type: array items: type: string description: language-based grouping array of objects containing mention metrics segmented by content language tasks.result.total.language.type: type: string description: type of the element = 'group_element' tasks.result.total.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.platform: type: array items: type: string description: platform-based grouping array of group elements containing mention metrics segmented by AI platform tasks.result.total.platform.type: type: string description: type of the element = 'group_element' tasks.result.total.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.total.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.total.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.sources_domain: type: array items: type: string description: found source domains relevant to the target array of objects containing data on top domains that are cited as sources in LLM responses tasks.result.total.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.search_results_domain: type: array items: type: string description: found search results domains relevant to the target array of objects containing data on top domains that appear in search results related to LLM queries tasks.result.total.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.total.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.total.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.total.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.total.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.total.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.total.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.total.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.total.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.total.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.total.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items: type: array items: type: string description: individual pages results array containing detailed mention metrics for each of the found top pages tasks.result.items.key: type: string description: URL of a found page the URL of a page found in LLM mentions for the specified target tasks.result.items.location: type: array items: type: string description: location-based grouping array of objects containing page mention metrics segmented by geographical location tasks.result.items.location.type: type: string description: type of the element = 'group_element' tasks.result.items.location.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.location.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.location.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.location.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.language: type: array items: type: string description: language-based grouping array of objects containing page mention metrics segmented by content language tasks.result.items.language.type: type: string description: type of the element = 'group_element' tasks.result.items.language.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.language.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.language.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.language.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.platform: type: array items: type: string description: platform-based grouping array of group elements containing page mention metrics segmented by AI platform tasks.result.items.platform.type: type: string description: type of the element = 'group_element' tasks.result.items.platform.key: type: string description: grouping identifier the specific identifier for the grouping dimension tasks.result.items.platform.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to this specific grouping key tasks.result.items.platform.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.platform.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.sources_domain: type: array items: type: string description: source domains relevant to the specific page array of objects containing data on domains that are cited as sources in LLM responses tasks.result.items.sources_domain.type: type: string description: type of the element = 'group_element' tasks.result.items.sources_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.items.sources_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.sources_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.sources_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.search_results_domain: type: array items: type: string description: search results domains relevant to the specific page array of objects containing data on domains that appear in search results related to LLM queries tasks.result.items.search_results_domain.type: type: string description: type of the element = 'group_element' tasks.result.items.search_results_domain.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found domain name tasks.result.items.search_results_domain.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.search_results_domain.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.search_results_domain.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.brand_entities_title: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity titles that appear in search results related to LLM queries tasks.result.items.brand_entities_title.type: type: string description: type of the element = 'group_element' tasks.result.items.brand_entities_title.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity title tasks.result.items.brand_entities_title.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.brand_entities_title.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.brand_entities_title.impressions: type: integer description: current AI impressions rate of a keyword tasks.result.items.brand_entities_category: type: array items: type: string description: data on brand entities relevant to the target array of objects containing data on brand entity categories that appear in search results related to LLM queries tasks.result.items.brand_entities_category.type: type: string description: type of the element = 'group_element' tasks.result.items.brand_entities_category.key: type: string description: grouping identifier the specific identifier for the grouping dimension in this case the field displays a found brand entity category tasks.result.items.brand_entities_category.mentions: type: integer description: total LLM mentions count the number of times the target keyword or domain were mentioned in relation to the specific domain tasks.result.items.brand_entities_category.ai_search_volume: type: integer description: current AI search volume rate of a keyword learn more about this metric here tasks.result.items.brand_entities_category.impressions: type: integer description: current AI impressions rate of a keyword '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: array items: type: object properties: domain: type: string description: target domain required field if you don't specify keyword you can specify up to 63 characters in the domain field; a domain should be specified without https:// and www. keyword: type: string description: target keyword required field if you don't specify domain you can specify up to 250 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article search_filter: type: string description: 'Entity search filter: include or exclude; defaults to include.' search_scope: type: array items: type: string description: 'Search scope. Domain entities: any, sources, search_results. Keyword entities: any, question, answer, brand_entities, fan_out_queries. Default: any.' include_subdomains: type: boolean description: 'indicates if the subdomains of the target domain will be included in the search optional field if set to true, the subdomains will be included in the search default value: false' match_type: type: string description: 'target keyword match type optional field possible values: word_match, partial_match word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the seed key phrase. partial_match - searches for any occurrence of the keyword or its parts within the content default value: word_match' oneOf: - required: - domain - required: - keyword description: 'array of objects containing target entities required field you can specify up to 10 entities (objects) in the target field one target entity can contain either one domain or one keyword and related parametersexamples: target array with a domain entity [{"domain": "en.wikipedia.org", "search_filter": "exclude"}] target array with a keyword entity [{"keyword": "bmw", "search_scope": ["question"], "match_type ": "partial_match"}] target array with multiple entities [{"domain": "en.wikipedia.org", "search_filter": "exclude"}, {"keyword": "bmw", "match_type ": "partial_match", "search_scope": ["answer"]}]' location_name: type: string description: 'full name of search location optional field if you use this field, you don''t need to specify location_code if you don''t specify this field, the location_code with 2840 value will be used by default; you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for United States only' location_code: type: integer description: 'search location code optional field if you use this field, you don''t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: 2840 Note: chat_gpt data is available for 2840 only' language_name: type: string description: 'full name of search language optional field if you use this field, you don''t need to specify language_code; if you don''t specify this field, the language_code with en value will be used by default; you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages Note: chat_gpt data is available for English only' language_code: type: string description: 'search language code optional field if you use this field, you don''t need to specify language_name; you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages default value: en Note: chat_gpt data is available for en onlyn' platform: type: string description: 'target platform optional field possible values: chat_gpt, google default value: google Note: the data returned depends on the selected platform Note #2:chat_gpt data is available for the United States and English only' links_scope: type: string description: 'links source scope optional field this parameter specifies which links will be used to extract pages and aggregation data possible values: sources, search_results default value: sources' initial_dataset_filters: type: array items: {} description: 'array of filter expressions applied before aggregation optional field you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["ai_search_volume",">","1000"]the full list of possible filters is available here. learn more about the initial dataset filters in this help center article.' items_list_limit: type: integer description: 'maximum number of results in the items array optional field you can use this parameter to limit the number of data objects you receive in the items array minimum value: 1 maximum value: 10 default value: 5' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: sources_domain search_results_domain minimum value: 1 maximum value: 10 default value: 5' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/llm_mentions/top_pages/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/perplexity/llm_responses/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.011236 p50: 0.023202 p95: 0.031224 max: 0.035034 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Perplexity LLM Responses description: 'Sends a `user_prompt` to a Perplexity model and returns its reply, synchronously. `model_name` must come from `get_dataforseo_ai_perplexity_llm_responses_models` - `sonar`, `sonar-pro` and `sonar-reasoning-pro`. `web_search_country_iso_code` scopes the search, which the other three vendors do not offer. Returns `model_name`, `input_tokens`, `output_tokens`, `reasoning_tokens`, `web_search`, `money_spent`, `datetime`, `items` and `fan_out_queries`. 💰 **Priced by tokens upstream, not per call**: a sixteen-token reply measured $0.0006, but nothing caps a long one, and AIsa bills a flat $0.012 either way. Read `money_spent` on the response to see what a prompt actually cost. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Perplexity searches by default, so its cost varies more with the question than the other vendors'' do - `post_perplexity_sonar_deep_research` is the documented case of that going badly (CASEBOOK C5).' operationId: post_dataforseo_ai_perplexity_llm_responses_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD includes the base task price plus the money_spent value tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.model_name: type: string description: name of the AI model used tasks.result.input_tokens: type: integer description: number of tokens in the input total count of tokens processed tasks.result.output_tokens: type: integer description: number of tokens in the output total count of tokens generated in the AI response tasks.result.web_search: type: boolean description: 'indicates if web search was used Note: web search is enabled by default in Perplexity Sonar models' tasks.result.money_spent: type: number description: cost of AI tokens, USD the price charged by the third-party AI model provider for according to its Pricing tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items: type: array items: type: string description: array of response items contains structured AI response data tasks.result.items.type: type: string description: type of the element = 'message' tasks.result.items.sections: type: array items: type: string description: array of content sections contains different parts of the AI response tasks.result.items.sections.type: type: string description: type of element='text' tasks.result.items.sections.text: type: string description: AI-generated text content tasks.result.items.sections.annotations: type: array items: type: string description: 'array of references used to generate the response equals null if the web_search parameter is not set to true Note: annotations may return empty even when web_search is true, as the AI will attempt to retrieve web information but may not find relevant results' tasks.result.items.sections.annotations.title: type: string description: the domain name or title of the quoted source tasks.result.items.sections.annotations.url: type: string description: URL of the quoted source tasks.result.fan_out_queries: type: array items: type: string description: array of fan-out queries contains related search queries derived from the main query to provide a more comprehensive response '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: user_prompt: type: string description: prompt for the AI model required field the question or task you want to send to the AI model; you can specify up to 500 characters in the user_prompt field model_name: type: string description: 'name of the AI model required field model_nameconsists of the actual model name and version name; if the basic model name is specified, its latest version will be set by default; you can receive the list of available LLM models by making a separate request to the following endpoint: https://api.dataforseo.com/v3/ai_optimization/perplexity/llm_responses/models' max_output_tokens: type: integer description: 'maximum number of tokens in the AI response optional field minimum value: 1 maximum value: 4096; default value: 2048; Note: if the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit' temperature: type: number description: 'randomness of the AI response optional field higher values make output more diverse lower values make output more focused minimum value: 0 maximum value: 1.9 default value: 0.77' top_p: type: number description: 'diversity of the AI response optional field controls diversity of the response by limiting token selection minimum value: 0 maximum value: 1 default value: 0.9' web_search_country_iso_code: type: string description: 'country code for web search localization optional field specify the country ISO code to get localized web search results Note: available only for Perplexity Sonar models example: US' system_message: type: string description: instructions for the AI behavior optional field defines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field message_chain: type: array items: type: object properties: role: type: string enum: - user - ai message: type: string required: - role - message description: 'conversation history optional field array of message objects representing previous conversation turns; each object must contain: role string with either user or ai role; message string with message content (max 500 characters); you can specify maximum of 10 message objects in the array; Note: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai); example: "message_chain": [{"role":"user","message":"Hello, what’s up?"},{"role":"ai","message":"Hello! I’m doing well, thank you. How can I assist you today?"}]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - user_prompt - model_name tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/perplexity/llm_responses/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/ai_optimization/perplexity/llm_responses/models: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Perplexity models for LLM Responses description: 'The Perplexity models available - `sonar`, `sonar-pro`, `sonar-reasoning-pro` - each with `model_name`, `reasoning`, `web_search_supported` and `task_post_supported`. Measured at 745 bytes, the smallest model list here. Free: upstream cost is 0. Note there is no queued variant for Perplexity; the live endpoint is the only one.' operationId: get_dataforseo_ai_perplexity_llm_responses_models responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request result: type: array items: type: string description: array of results result.model_name: type: string description: name of the AI model result.reasoning: type: boolean description: indicates if the AI model supports reasoning result.web_search_supported: type: boolean description: web search support for the AI model if true, the web_search parameter can be set with the AI model result.task_post_supported: type: boolean description: indicates if Standard (POST-GET) data retrieval is supported if true, you can use the Standard (POST-GET) data retrieval method with the AI model '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/ai_optimization/perplexity/llm_responses/models source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/dataforseo_trends/merged_data/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘DataForSEO Trends Merged Data’ Tasks description: 'Explore, demography and subregion data for the same `keywords` in one response, rather than three calls. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Prefer it when you want the whole picture: the three siblings each cost a call, and this returns what all three would. Correspondingly larger - expect at least the 21.7 KB measured for explore alone.' operationId: post_dataforseo_keywords_trends_merged_data_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keywords: type: array items: type: string description: keywords in a POST array tasks.result.type: type: array items: type: string description: search engine type in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keyword popularity and related data tasks.result.items.position: type: integer description: 'the alignment of the element can take the following values: 1, 2, 3, 4, etc.' tasks.result.items.type: type: string description: type of element = ‘demography’ tasks.result.items.keywords: type: array items: type: string description: relevant keywords the data included in the demography and demography_comparison is based on the keywords listed in this array tasks.result.items.data: type: array items: type: string description: DataForSEO Trends data for the specified parameters tasks.result.items.data.date_from: type: string description: 'start date of the corresponding time range in the UTC format: “yyyy-mm-dd”' tasks.result.items.data.date_to: type: string description: 'end date of the corresponding time range in the UTC format: “yyyy-mm-dd”' tasks.result.items.data.timestamp: type: integer description: a point in time in the Unix time format tasks.result.items.data.values: type: array items: type: string description: relative keyword popularity rate at a specific timestamp if you specify more than one keyword, the values will be averaged to the highest value across all specified keywords a value of 100 is the peak popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term tasks.result.items.averages: type: array items: type: string description: keyword popularity values averaged over the whole time range tasks.result.items.interests: type: array items: type: string description: subregional keyword popuarity data for each specified term tasks.result.items.interests.keyword: type: string description: relevant keyword the data included in the values element is based on this keyword tasks.result.items.interests.values: type: array items: type: string description: contains data on relative keyword popularity by country or region tasks.result.items.interests.values.geo_id: type: string description: 'location identifier you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: US-NY' tasks.result.items.interests.values.geo_name: type: string description: 'location name you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: Andorra' tasks.result.items.interests.values.value: type: integer description: 'relative keyword popularity rate in a given location represents location-specific keyword popularity rate over the specified time range; using this value you can understand how popular a keyword is in one location compared to another location; calculation: we determine the highest popularity value for the relevant keyword across all locations, and then express all other values as a percentage of that highest value (100); a value of 100 is the highest popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term' tasks.result.items.interests_comparison: type: object description: comparison of data on subregional keyword popularity for the specified parameters if you specified a single keyword, the value will be null tasks.result.items.interests_comparison.items: type: array items: type: string description: keyword popularity values per location values in this array represent percentages relative to the maximum value within each region tasks.result.items.interests_comparison.items.geo_id: type: string description: 'location identifier you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: US-NY' tasks.result.items.interests_comparison.items.geo_name: type: string description: 'location name you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: Andorra' tasks.result.items.interests_comparison.items.values: type: array items: type: string description: 'keyword popularity rates within a given location represents location-specific keyword popularity rate over the specified time range; using these values, you can understand which of the specified keywords is more popular in the related location; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the highest popularity value across all specified keywords within a given location, and then express the popularity values of each keyword as a percentage of the highest value (100); a value of 100 is the peak popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term' tasks.result.items.interests_comparison.absolute_items: type: array items: type: string description: keyword popularity rates across all locations values in this array represent percentages relative to the maximum value across all locations tasks.result.items.interests_comparison.absolute_items.geo_id: type: string description: 'location identifier you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: US-NY' tasks.result.items.interests_comparison.absolute_items.geo_name: type: string description: 'location name you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: Andorra' tasks.result.items.interests_comparison.absolute_items.values: type: array items: type: string description: 'keyword popularity rates relative to all locations represents location-specific keyword popularity rate over the specified time range; using these values, you can understand how popular each keyword is compared to all other keywords across all locations; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the highest popularity value across all keywords across all locations, and then express all other values as a percentage of that highest value (100); a value of 100 is the peak popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term' tasks.result.items.demography: type: object description: demographic breakdown of keyword popularity data per each specified term conains keyword popularity data by age and gender tasks.result.items.demography.age: type: array items: type: string description: distribution of keyword popularity by age tasks.result.items.demography.age.keyword: type: string description: relevant keyword for which demographic data is provided tasks.result.items.demography.age.values: type: array items: type: string description: contains age range and corresponding keyword popularity values tasks.result.items.demography.age.values.type: type: string description: 'age range can take the following values: 18-24, 25-34, 35-44, 45-54, 55-64' tasks.result.items.demography.age.values.value: type: integer description: 'keyword popularity rate within the specified age range using this value you can understand how popular a keyword is within each age range; calculation: we determine the highest popularity value for the relevant keyword across all age groups, and then express all other values as a percentage of that highest value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' tasks.result.items.demography.gender: type: array items: type: string description: distribution of keyword popularity by gender tasks.result.items.demography.gender.keyword: type: string description: relevant keyword for which demographic data is provided tasks.result.items.demography.gender.values: type: array items: type: string description: contains gender and corresponding keyword popularity values tasks.result.items.demography.gender.values.type: type: string description: 'gender category can take the following values: female, male' tasks.result.items.demography.gender.values.value: type: integer description: 'keyword popularity rate within the specified gender category using this value you can understand how popular a keyword is within each gender category; calculation: we determine the highest popularity value for the relevant keyword across all gender categories, and then express all other values as a percentage of that highest value (100); a value of 100 is the highest popularity for the term; a value of 0 means there was not enough data for this term' tasks.result.items.demography_comparison: type: object description: comparison of demographic data on keyword popularity for the specified parameters conains keyword popularity data by age and gender if you specified a single keyword, the value will be null tasks.result.items.demography_comparison.age: type: object description: comparison of keyword popularity data by age tasks.result.items.demography_comparison.age.$18-24: type: array items: type: string description: 'indicates age range and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified age range variable can take the following values: 18-24, 18-24, 25-34, 35-44, 45-54, 55-64; using the values from this array, you can understand which of the specified keywords is more popular within the related age range; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each age range, and then express all other values as a percentage of the total value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' tasks.result.items.demography_comparison.gender: type: object description: comparison of keyword popularity data by gender tasks.result.items.demography_comparison.gender.female: type: array items: type: string description: 'indicates gender category and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified gender category; using the values from this array, you can understand which of the specified keywords is more popular within the related gender category; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each gender category, and then express all other values as a percentage of the total value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' tasks.result.items.demography_comparison.gender.male: type: array items: type: string description: 'indicates gender category and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified gender category; using the values from this array, you can understand which of the specified keywords is more popular within the related gender category; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each gender category, and then express all other values as a percentage of the total value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field the maximum number of keywords you can specify: 5 avoid symbols and special characters (e.g., UTF symbols, emojis); specifying non-Latin characters, you’ll get data for the countries where they are used learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_name belongs to; example: United Kingdom' location_code: type: integer description: 'search engine location code optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_code belongs to; example: 2840' type: type: string description: 'dataforseo trends type optional field if you don’t specify this field, the web type will be used by default possible values: web, news, ecommerce' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, the current day and month of the preceding year will be used by default minimal value for the web type: 2004-01-01 minimal value for other types: 2008-01-01 date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' time_range: type: string description: 'preset time ranges optional field if you specify date_from or date_to parameters, this field will be ignored when setting a task possible values for all type parameters: past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/dataforseo_trends/merged_data/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/audience_estimation/industries: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Industries for Bing Ads Audience Estimation description: 'The industry values `post_dataforseo_keywords_bing_audience_live` accepts. Free: upstream cost is 0. Read it before composing an audience request - an unrecognised industry is rejected, not ignored. The job-function list is `get_dataforseo_keywords_bing_audience_job_functions`.' operationId: get_dataforseo_keywords_bing_audience_industries responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.industry_id: type: integer description: ID of the industry tasks.result.industry_name: type: string description: name of the industry '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/audience_estimation/industries source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/audience_estimation/job_functions: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Job Functions for Bing Ads Audience Estimation description: 'The job-function values `post_dataforseo_keywords_bing_audience_live` accepts. Free: upstream cost is 0. The industry list is `get_dataforseo_keywords_bing_audience_industries`. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_keywords_bing_audience_job_functions responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.job_function_id: type: integer description: ID of the job function tasks.result.job_function_name: type: string description: name of the job function '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/audience_estimation/job_functions source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/audience_estimation/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Bing Ads Audience Estimation’ Tasks description: 'Estimates the Bing Ads audience reachable at a given `bid` and `daily_budget`, narrowed by `location_code`, `age`, industry and job function. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Industry and job-function values come from `get_dataforseo_keywords_bing_audience_industries` and `get_dataforseo_keywords_bing_audience_job_functions` - both free, and both worth reading before composing a request. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_bing_audience_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.est_impressions: type: object description: monthly estimated impressions range tasks.result.est_impressions.high: type: integer description: indicates the upper bound of the range result tasks.result.est_impressions.low: type: integer description: indicates the lower bound of the range result tasks.result.est_audience_size: type: object description: monthly estimated reach user count range tasks.result.est_audience_size.high: type: integer description: indicates the upper bound of the range result tasks.result.est_audience_size.low: type: integer description: indicates the lower bound of the range result tasks.result.est_clicks: type: object description: monthly estimated click count range tasks.result.est_clicks.high: type: integer description: indicates the upper bound of the range result tasks.result.est_clicks.low: type: integer description: indicates the lower bound of the range result tasks.result.est_spend: type: object description: monthly estimated spending range tasks.result.est_spend.high: type: integer description: indicates the upper bound of the range result tasks.result.est_spend.low: type: integer description: indicates the lower bound of the range result tasks.result.est_cost_per_event: type: object description: indicates the estimated cost per event with range result tasks.result.est_cost_per_event.high: type: number description: indicates the upper bound of the range result tasks.result.est_cost_per_event.low: type: number description: indicates the lower bound of the range result tasks.result.est_ctr: type: object description: estimated click-through rate range tasks.result.est_ctr.high: type: number description: indicates the upper bound of the range result tasks.result.est_ctr.low: type: number description: indicates the lower bound of the range result tasks.result.suggested_bid: type: number description: suggested bid value under the current targeting tasks.result.suggested_budget: type: integer description: suggested daily budget value under the current targeting and bid tasks.result.events_lost_to_bid: type: integer description: indicates event lost count due to insufficient input bid tasks.result.events_lost_to_budget: type: integer description: indicates the event lost count due to insufficient input budget tasks.result.est_reach_audience_size: type: integer description: monthly estimated user count tasks.result.est_reach_impressions: type: integer description: monthly estimated impressions tasks.result.currency: type: integer description: 'currency name example: USDollar' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius (in km)” format the data will be provided for the country the specified coordinates belong to example: 29.6821525,-82.4098881,100' age: type: array items: type: string description: 'selection of age ranges for targeting possible values: eighteen_to_twenty_four, fifty_to_sixty_four, sixty_five_and_above, thirteen_to_seventeen, thirty_five_to_forty_nine, twenty_five_to_thirty_four, unknown, zero_to_twelve' bid: type: number description: 'desired bid setting value in USD maximum value: 1000' daily_budget: type: number description: 'daily campaign budget value in USD maximum value: 10000' gender: type: array items: type: string description: 'gender to target possible values: male, female, unknown' industry: type: array items: type: integer description: 'industry of LinkedIn profile targeting if you use this field, you can receive the list of available industry names with industry_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/industries example: 806301758' job_function: type: array items: type: integer description: 'job function of LinkedIn profile targeting if you use this field, you can receive the list of available job function names with job_function_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/job_functions example: 806300451' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/audience_estimation/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/audience_estimation/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Bing Ads Audience Estimation Results by id description: 'Retrieves a queued Bing audience-estimation task by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_keywords_bing_audience_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/audience_estimation/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/audience_estimation/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Bing Ads Audience Estimation’ Tasks description: 'Queues a Bing audience estimation, returning a task `id`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_keywords_bing_audience_fetch`.' operationId: post_dataforseo_keywords_bing_audience_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system unique task identifier in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius (in km)” format the data will be provided for the country the specified coordinates belong to example: 29.6821525,-82.4098881,100' age: type: array items: type: string description: 'selection of age ranges for targeting possible values: eighteen_to_twenty_four, fifty_to_sixty_four, sixty_five_and_above, thirteen_to_seventeen, thirty_five_to_forty_nine, twenty_five_to_thirty_four, unknown, zero_to_twelve' bid: type: number description: 'desired bid setting value in USD maximum value: 1000' daily_budget: type: number description: 'daily campaign budget value in USD maximum value: 10000' gender: type: array items: type: string description: 'gender to target possible values: male, female, unknown' industry: type: array items: type: integer description: 'industry of LinkedIn profile targeting if you use this field, you can receive the list of available industry names with industry_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/industries example: 806301758' job_function: type: array items: type: integer description: 'job function of LinkedIn profile targeting if you use this field, you can receive the list of available job function names with job_function_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/job_functions example: 806300451' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/audience_estimation/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/audience_estimation/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Bing Ads Audience Estimation’ Completed Tasks description: 'Lists finished Bing audience-estimation tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_keywords_bing_audience_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.function: type: string description: type of the task tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.endpoint: type: string description: URL for collecting the results of the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/audience_estimation/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_performance/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Bing Keyword Performance’ Tasks description: 'How a list of `keywords` performs in Bing Ads for a given `device` and `match` type. ⚠️ **`language_name` is required and its absence is reported as `Invalid Field: ''language_name''` inside an HTTP 200** - the message means missing as well as wrong. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Valid pairs come from `get_dataforseo_keywords_bing_kw_performance_locales`. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_bing_kw_performance_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.year: type: integer description: 'indicates the year for which the data is provided for example: 2020' tasks.result.month: type: integer description: 'indicates the month for which the data is provided for example: 10' tasks.result.keyword_kpi: type: object description: object containing keyword metrics if there is no data, then the value is null tasks.result.keyword_kpi.desktop: type: array items: type: string description: keyword data aggregated for desktop devices if there is no data, then the value is null tasks.result.keyword_kpi.desktop.ad_position: type: string description: 'represents the position of the relevant ad in SERP can take the following values: FirstPage1: The first ad to appear on the right side of the first search results page FirstPage2: The second ad to appear on the right side of the first search results page FirstPage3: The third ad to appear on the right side of the first search results page FirstPage4: The fourth ad to appear on the right side of the first search results page FirstPage5: The fifth ad to appear on the right side of the first search results page FirstPage6: The sixth ad to appear on the right side of the first search results page FirstPage7: The seventh ad to appear on the right side of the first search results page FirstPage8: The eighth ad to appear on the right side of the first search results page FirstPage9: The ninth ad to appear on the right side of the first search results page FirstPage10: The tenth ad to appear on the right side of the first search results page MainLine1: The first ad to appear at the top of the search results page MainLine2: The second ad to appear at the top of the search results page MainLine3: The third ad to appear at the top of the search results page MainLine4: The fourth ad to appear at the top of the search results page' tasks.result.keyword_kpi.desktop.clicks: type: integer description: ad clicks the number of clicks that the keyword and match type generated during the last month tasks.result.keyword_kpi.desktop.impressions: type: integer description: ad impressions the number of impressions that the keyword and match type generated during the last month tasks.result.keyword_kpi.desktop.average_cpc: type: integer description: average cost per click, USD calculated by dividing the cost of all clicks by the number of clicks tasks.result.keyword_kpi.desktop.ctr: type: integer description: click-through rate as a percentage calculated by dividing the number of clicks by the number of impressions and multiplying the result by 100 tasks.result.keyword_kpi.desktop.total_cost: type: integer description: total cost of an ad, USD the cost of using the specified keyword and match type during the last month tasks.result.keyword_kpi.desktop.average_bid: type: integer description: average bid of the keyword tasks.result.keyword_kpi.mobile: type: array items: type: string description: keyword data aggregated for mobile devices if there is no data, then the value is null tasks.result.keyword_kpi.mobile.ad_position: type: string description: 'represents the position of the relevant ad in SERP can take the following values: FirstPage1: The first ad to appear on the right side of the first search results page FirstPage2: The second ad to appear on the right side of the first search results page FirstPage3: The third ad to appear on the right side of the first search results page FirstPage4: The fourth ad to appear on the right side of the first search results page FirstPage5: The fifth ad to appear on the right side of the first search results page FirstPage6: The sixth ad to appear on the right side of the first search results page FirstPage7: The seventh ad to appear on the right side of the first search results page FirstPage8: The eighth ad to appear on the right side of the first search results page FirstPage9: The ninth ad to appear on the right side of the first search results page FirstPage10: The tenth ad to appear on the right side of the first search results page MainLine1: The first ad to appear at the top of the search results page MainLine2: The second ad to appear at the top of the search results page MainLine3: The third ad to appear at the top of the search results page MainLine4: The fourth ad to appear at the top of the search results page' tasks.result.keyword_kpi.mobile.clicks: type: integer description: ad clicks the number of clicks that the keyword and match type generated during the last month tasks.result.keyword_kpi.mobile.impressions: type: integer description: ad impressions the number of impressions that the keyword and match type generated during the last month tasks.result.keyword_kpi.mobile.average_cpc: type: integer description: average cost per click, USD calculated by dividing the cost of all clicks by the number of clicks tasks.result.keyword_kpi.mobile.ctr: type: integer description: click-through rate as a percentage calculated by dividing the number of clicks by the number of impressions and multiplying the result by 100 tasks.result.keyword_kpi.mobile.total_cost: type: integer description: total cost of an ad, USD the cost of using the specified keyword and match type during the last month tasks.result.keyword_kpi.mobile.average_bid: type: integer description: average bid of the keyword tasks.result.keyword_kpi.tablet: type: array items: type: string description: keyword data aggregated for tablet devices if there is no data, then the value is null tasks.result.keyword_kpi.tablet.ad_position: type: string description: 'represents the position of the relevant ad in SERP can take the following values: FirstPage1: The first ad to appear on the right side of the first search results page FirstPage2: The second ad to appear on the right side of the first search results page FirstPage3: The third ad to appear on the right side of the first search results page FirstPage4: The fourth ad to appear on the right side of the first search results page FirstPage5: The fifth ad to appear on the right side of the first search results page FirstPage6: The sixth ad to appear on the right side of the first search results page FirstPage7: The seventh ad to appear on the right side of the first search results page FirstPage8: The eighth ad to appear on the right side of the first search results page FirstPage9: The ninth ad to appear on the right side of the first search results page FirstPage10: The tenth ad to appear on the right side of the first search results page MainLine1: The first ad to appear at the top of the search results page MainLine2: The second ad to appear at the top of the search results page MainLine3: The third ad to appear at the top of the search results page MainLine4: The fourth ad to appear at the top of the search results page' tasks.result.keyword_kpi.tablet.clicks: type: integer description: ad clicks the number of clicks that the keyword and match type generated during the last month tasks.result.keyword_kpi.tablet.impressions: type: integer description: ad impressions the number of impressions that the keyword and match type generated during the last month tasks.result.keyword_kpi.tablet.average_cpc: type: integer description: average cost per click, USD calculated by dividing the cost of all clicks by the number of clicks tasks.result.keyword_kpi.tablet.ctr: type: integer description: click-through rate as a percentage calculated by dividing the number of clicks by the number of impressions and multiplying the result by 100 tasks.result.keyword_kpi.tablet.total_cost: type: integer description: total cost of an ad, USD the cost of using the specified keyword and match type during the last month tasks.result.keyword_kpi.tablet.average_bid: type: integer description: average bid of the keyword '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 1000 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the specified keywords will be converted to lowercase, data will be provided in a separate array learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device typepossible values: desktop, mobile, tablet, all default value: all' match: type: string description: 'keywords match type optional field can take the following values: aggregate returns data across all match types; broad returns data for all user queries containing the specified keyword with varying word order; phrase returns data for all user queries containing the specified keyword with identical word order; exact returns data for user query that matches the specified keyword;Note: the aggregate match type is applied by default' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: "United States"' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: English' language_code: type: string description: 'search engine language code required field if you don’t specify language_name you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: "en"' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_performance/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_performance/locations_and_languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations and Languages for Keyword Performance endpoints description: 'The location and language pairs `post_dataforseo_keywords_bing_kw_performance_live` accepts. Free: upstream cost is 0. Read it first - that endpoint rejects a missing `language_name` with the same message it uses for a wrong one. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_keywords_bing_kw_performance_locales responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: integer description: language name tasks.result.language_code: type: string description: language code tasks.result.available_locations: type: array items: type: string description: supported locations contains locations supported in combination with a specific language tasks.result.available_locations.location_code: type: string description: location code tasks.result.available_locations.location_name: type: string description: location name tasks.result.available_locations.country_iso_code: type: string description: ISO country code of the location tasks.result.available_locations.location_type: type: string description: 'location type possible values: Country, Region' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_performance/locations_and_languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_performance/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Bing Keyword Performance’ Results by id description: 'Retrieves a queued Bing keyword-performance task by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_keywords_bing_kw_performance_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_performance/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_performance/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Bing Keyword Performance’ Tasks description: 'Queues a Bing keyword-performance task, returning a task `id`. ⚠️ Same requirement as the live twin: `language_name` must be present. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_keywords_bing_kw_performance_fetch`.' operationId: post_dataforseo_keywords_bing_kw_performance_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 1000 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the specified keywords will be converted to lowercase, data will be provided in a separate array learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device typepossible values: desktop, mobile, tablet, all default value: all' match: type: string description: 'keywords match type optional field can take the following values: aggregate returns data across all match types; broad returns data for all user queries containing the specified keyword with varying word order; phrase returns data for all user queries containing the specified keyword with identical word order; exact returns data for user query that matches the specified keyword;Note: the aggregate match type is applied by default' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: "United States"' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: English' language_code: type: string description: 'search engine language code required field if you don’t specify language_name you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages example: "en"' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_performance/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_suggestions_for_url/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Bing Languages for Keyword Suggestions for URL description: 'The languages `post_dataforseo_keywords_bing_kw_for_url_live` accepts. Free: upstream cost is 0. Note this is a narrower list than `get_dataforseo_keywords_bing_languages`, which serves the rest of the Bing family. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_keywords_bing_kw_for_url_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_suggestions_for_url/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_suggestions_for_url/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Bing Ads Keyword Suggestions for URL’ Tasks description: 'Suggests Bing keywords for one page `target`, reading the page itself rather than a seed list. `exclude_brands` drops brand terms, `language_code` scopes it. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it when you have a URL and no keyword list yet; once you have seeds, `post_dataforseo_keywords_bing_kw_for_keywords_live` expands them. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_bing_kw_for_url_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array that were returned an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results results are sorted in order from keywords with the highest confidence score to those with the lowest confidence score tasks.result.keyword: type: string description: suggested keyword tasks.result.confidence_score: type: number description: a score from 0.0 to 1.0 that indicates the probability that the keyword would match a user’s search query '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'target URL of the webpage to scan for possible keywords required field maximum length: 2000 characters' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_suggestions_for_url/languages example: en' exclude_brands: type: boolean description: determines whether the results exclude brand keywords optional field language_name: type: string description: Full name of the search engine language. Required if language_code is not supplied; either language_name or language_code is sufficient. required: - target allOf: - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_suggestions_for_url/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_suggestions_for_url/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Bing Ads Keyword Suggestions For URL Results by id description: 'Retrieves a queued Bing keywords-for-URL task by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_keywords_bing_kw_for_url_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_suggestions_for_url/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_suggestions_for_url/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Keyword Suggestions For URL’ Tasks description: 'Queues a Bing keywords-for-URL task, returning a task `id`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_keywords_bing_kw_for_url_fetch`.' operationId: post_dataforseo_keywords_bing_kw_for_url_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'target URL of the webpage to scan for possible keywords required field maximum length: 2000 characters' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_suggestions_for_url/languages example: en' exclude_brands: type: boolean description: determines whether the results exclude brand keywords optional field language_name: type: string description: Full name of the search engine language. Required if language_code is not supplied; either language_name or language_code is sufficient. required: - target allOf: - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_suggestions_for_url/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keyword_suggestions_for_url/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Bing Ads Keyword Suggestions For URL’ Completed Tasks description: 'Lists finished Bing keywords-for-URL tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_keywords_bing_kw_for_url_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.function: type: string description: type of the task tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.endpoint: type: string description: URL for collecting the results of the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keyword_suggestions_for_url/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keywords_for_keywords/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Keywords For Keywords’ Tasks description: 'Expands a seed list of `keywords` into related Bing keywords with volume and competition. Measured at $0.09 upstream against $0.012 billed. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Expansion responses in this family run to megabytes on the Google side; assume the same order here and keep the seed list narrow. The Google twin is `post_dataforseo_keywords_gads_kw_for_keywords_live`. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_bing_kw_for_keywords_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.search_partners: type: boolean description: indicates whether data from partner networks is included in the response tasks.result.device: type: string description: 'device type indicates for what device type the data is provided; possible values: all, mobile, desktop, tablet' tasks.result.competition: type: number description: 'competition represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data. Possible values: 0.1, 0.5,0.90.1 – low competition, 0.5 – medium competition, 0.9 – high competition; if there is no data the value is null' tasks.result.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword. if there is no data, then the value is null tasks.result.search_volume: type: integer description: monthly average search volume rate represents the (approximate) number of searches for the keyword on the Bing search engine, depending on the user’s targetingsearch volume is rounded to the closest decimal values if there is no data, then the value is null tasks.result.categories: type: array items: type: string description: product and service categories legacy field, the value will always be null tasks.result.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword (as available for the past twelve months), targeted to the specified geographic locations. if there is no data, then the value is null tasks.result.monthly_searches.year: type: integer description: year tasks.result.monthly_searches.month: type: integer description: month tasks.result.monthly_searches.search_volume: type: integer description: monthly average search volume rate search volume is rounded to the closest decimal values '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: keywords required field you can specify the maximum of 200 keywords with each keyword containing no more than 100 characters; the specified keywords will be converted to lowercase, data will be provided in a separate array learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code supported languages: English, French, German' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name supported languages: en, fr, de' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order default value: relevance' keywords_negative: type: array items: type: string description: keywords negative array optional field These keywords will be ignored in the results array; You can specify a maximum of 200 terms that you want to exclude from the results; the specified keywords will be converted to lowercase format device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device type; possible values: all, mobile, desktop, tablet default value: all' date_from: type: string description: 'starting date of the time range optional field minimal value: 24 months from today’s date; if you don’t specify this field, data will be provided for the last 12 months date format: "yyyy-mm-dd" example: "2020-01-01" Note: we do not recommend using a custom time range for the past year’s dates' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months; minimum value: two years back from today’s date; maximum value: one month from today’s date; date format: "yyyy-mm-dd" example: "2020-03-15" Note: we do not recommend using a custom time range for the past year’s dates' search_partners: type: boolean description: 'Bing search partners type optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search. default value: false – results are returned for Bing, AOL, and Yahoo search networks' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keywords_for_keywords/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keywords_for_keywords/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Keywords For Keywords’ Results by id description: 'Retrieves a queued Bing keyword-expansion task by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_keywords_bing_kw_for_keywords_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keywords_for_keywords/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keywords_for_keywords/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Keywords For Keywords’ Tasks description: 'Queues a Bing keyword expansion, returning a task `id`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_keywords_bing_kw_for_keywords_fetch`.' operationId: post_dataforseo_keywords_bing_kw_for_keywords_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: keywords required field you can specify the maximum of 200 keywords with each keyword containing no more than 100 characters; the specified keywords will be converted to lowercase, data will be provided in a separate array learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code supported languages: English, French, German' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name supported languages: en, fr, de' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order default value: relevance' keywords_negative: type: array items: type: string description: keywords negative array optional field These keywords will be ignored in the results array; You can specify a maximum of 200 terms that you want to exclude from the results; the specified keywords will be converted to lowercase format device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device type; possible values: all, mobile, desktop, tablet default value: all' date_from: type: string description: 'starting date of the time range optional field minimal value: 24 months from today’s date; if you don’t specify this field, data will be provided for the last 12 months date format: "yyyy-mm-dd" example: "2020-01-01" Note: we do not recommend using a custom time range for the past year’s dates' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months; minimum value: two years back from today’s date; maximum value: one month from today’s date; date format: "yyyy-mm-dd" example: "2020-03-15" Note: we do not recommend using a custom time range for the past year’s dates' search_partners: type: boolean description: 'Bing search partners type optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search. default value: false – results are returned for Bing, AOL, and Yahoo search networks' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keywords_for_keywords/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keywords_for_site/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Keywords For Site’ Tasks description: 'The Bing keywords a whole site ranks or bids for, from a `target` domain. Measured at $0.09 upstream against $0.012 billed. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The Google equivalent measured 7.2 MB for one site with no way to cap it; assume the same shape here. The Google twin is `post_dataforseo_keywords_gads_kw_for_site_live`. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_bing_kw_for_site_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array that were returned an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.search_partners: type: boolean description: indicates whether data from partner networks included in the response tasks.result.device: type: string description: device type in a POST array if there is no data, then the value is null tasks.result.competition: type: number description: 'competition represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data. Possible values: 0.1, 0.5,0.90.1 – low competition, 0.5 – medium competition, 0.9 – high competition; if there is no data the value is null' tasks.result.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword. if there is no data, then the value is null tasks.result.search_volume: type: integer description: monthly average search volume rate represents the (approximate) number of searches for the keyword on the Bing search engine, depending on the user’s targetingsearch volume is rounded to the closest decimal valuesif there is no data, then the value is null tasks.result.categories: type: array items: type: string description: product and service categories legacy field, the value will always be null tasks.result.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword (as available for the past twelve months), targeted to the specified geographic locations. if there is no data, then the value is null tasks.result.monthly_searches.year: type: integer description: year tasks.result.monthly_searches.month: type: integer description: month tasks.result.monthly_searches.search_volume: type: integer description: monthly average search volume rate search volume is rounded to the closest decimal values '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain or URL required field the domain name or URL of the target website location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code supported languages: English, French, German' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name supported languages: en, fr, de' keywords_negative: type: array items: type: string description: keywords negative array optional field These keywords will be ignored in the results array; You can specify a maximum of 200 terms that you want to exclude from the results; the specified keywords will be converted to lowercase format device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device typepossible values: all, mobile, desktop, tablet default value: all' date_from: type: string description: 'starting date of the time range optional field minimal value: 24 months from today’s date; if you don’t specify this field, data will be provided for the last 12 months date format: "yyyy-mm-dd" example: "2020-01-01" Note: we do not recommend using a custom time range for the past year’s dates' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months; minimum value: two years back from today’s date; maximum value: one month from today’s date; note: we do not recommend using a custom time range for the past year’s dates; date format: "yyyy-mm-dd" example: "2020-03-15" Note: we do not recommend using a custom time range for the past year’s dates' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order default value: relevance' search_partners: type: boolean description: 'Bing search partners type optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search. default value: false – results are returned for Bing, AOL, and Yahoo search networks' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keywords_for_site/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keywords_for_site/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Keywords For Site’ Results by id description: 'Retrieves a queued Bing keywords-for-site task by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_keywords_bing_kw_for_site_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keywords_for_site/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/keywords_for_site/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Keywords For Site’ Tasks description: 'Queues a Bing keywords-for-site task, returning a task `id`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_keywords_bing_kw_for_site_fetch`.' operationId: post_dataforseo_keywords_bing_kw_for_site_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain or URL required field the URL of the webpage or the domain to scan for possible keywords location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code supported languages: English, French, German' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name supported languages: en, fr, de' keywords_negative: type: array items: type: string description: keywords negative array optional field These keywords will be ignored in the results array; You can specify a maximum of 200 terms that you want to exclude from the results; the specified keywords will be converted to lowercase format device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device type possible values: all, mobile, desktop, tablet default value: all' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order default value: relevance' date_from: type: string description: 'starting date of the time range optional field minimal value: 24 months from today’s date; if you don’t specify this field, data will be provided for the last 12 months date format: "yyyy-mm-dd" example: "2020-01-01" Note: we do not recommend using a custom time range for the past year’s dates' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months; minimum value: two years back from today’s date; maximum value: one month from today’s date; date format: "yyyy-mm-dd" example: "2020-03-15" Note: we do not recommend using a custom time range for the past year’s dates' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' search_partners: type: boolean description: 'Bing search partners type optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search. default value: false – results are returned for Bing, AOL, and Yahoo search networks' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/keywords_for_site/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Bing Languages for Keywords Data description: 'The languages the Bing keyword endpoints accept, as `language_name` and `language_code`. Measured at 548 bytes, the smallest reference response in this provider. Free: upstream cost is 0. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_keywords_bing_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Bing Locations for Keywords Data description: The locations the Bing keyword endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 6.1 MB.** Smaller than the Google-side catalogues in this provider, which run past 40 MB, but still far too large for a tool result. `location_code` 2840 is the United States; look other codes up in DataForSEO's documentation rather than fetching this. operationId: get_dataforseo_keywords_bing_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.location_code_parent: type: integer description: 'the code of the superordinate location example: "location_code": 9041134, "location_name": "Vienna International Airport,Lower Austria,Austria", "location_code_parent": 20044where location_code_parent corresponds to: "location_code": 20044, "location_name": "Lower Austria,Austria"' tasks.result.country_iso_code: type: string description: ISO country code of the location tasks.result.location_type: type: string description: location type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Search Volume’ Tasks description: 'Bing search volume for a list of `keywords`. Returns `keyword`, `location_code`, `language_code`, `search_partners`, `device`, `competition`, `cpc`, `search_volume`, `categories` and `monthly_searches` - note `categories`, which the Google equivalent does not return, and no `competition_index`. Measured at 1.3 KB for one keyword, a fraction of the Google response. Measured at $0.09 upstream against $0.012 billed. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The Google twin is `post_dataforseo_keywords_gads_search_volume_live`; run both when the audience is not Google-only. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_bing_search_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.search_partners: type: boolean description: indicates whether data from partner networks included in the response tasks.result.device: type: string description: device type in a POST array if there is no data, then the value is null tasks.result.competition: type: number description: 'competition represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data. Possible values: 0.1, 0.5,0.90.1 – low competition, 0.5 – medium competition, 0.9 – high competition; if there is no data the value is null' tasks.result.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword. if there is no data then the value is null tasks.result.search_volume: type: integer description: monthly average search volume rate represents either the (approximate) number of searches for the given keyword idea on bing search engine depending on the user’s targeting; search volume is rounded to the nearest tens; if there is no data, the value is null tasks.result.categories: type: array items: type: string description: 'product and service categories our API doesn’t return categories for this endpoint: the parameter will always equal null' tasks.result.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations if there is no data then the value is null tasks.result.monthly_searches.year: type: integer description: year tasks.result.monthly_searches.month: type: integer description: month tasks.result.monthly_searches.search_volume: type: integer description: monthly average search volume rate search volume is rounded to the nearest tens '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 1000 The maximum number of characters for each keyword: 100 the specified keywords will be converted to lowercase, data will be provided in a separate array learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code supported languages: English, French, German' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name supported languages: en, fr, de' device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device type; possible values: all, mobile, desktop, tablet default value: all' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order default value: relevance' date_from: type: string description: 'starting date of the time range optional field minimal value: 24 months from today’s date if you don’t specify this field, data will be provided for the last 12 months minimum value: two years back from today’s date date format: "yyyy-mm-dd" example: "2020-01-01" Note: we do not recommend using a custom time range for the past year’s dates' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months; minimum value: two years back from today’s date; maximum value: one month from today’s date; note: we do not recommend using a custom time range for the past year’s dates; date format: "yyyy-mm-dd" example: "2020-03-15" Note: we do not recommend using a custom time range for the past year’s dates' search_partners: type: boolean description: 'Bing search partners type optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search. default value: false – results are returned for Bing, AOL, and Yahoo search networks' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/search_volume/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Search Volume Results by id description: 'Retrieves a queued Bing search-volume task by `id`. Same shape as the live twin. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_keywords_bing_search_volume_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/search_volume/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/search_volume/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Search Volume’ Tasks description: 'Queues a Bing search-volume task, returning a task `id`. Measured at $0.09 upstream. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_keywords_bing_search_volume_fetch`.' operationId: post_dataforseo_keywords_bing_search_volume_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system unique task identifier in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 1000 The maximum number of characters for each keyword: 100 the specified keywords will be converted to lowercase, data will be provided in a separate array learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude” format the data will be provided for the country the specified coordinates belong to example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code supported languages: English, French, German' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name supported languages: en, fr, de' device: type: string description: 'device type optional field specify this field if you want to get the data for a particular device typepossible values: all, mobile, desktop, tablet default value: all' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order default value: relevance' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months minimal value: 24 months from today’s date date format: "yyyy-mm-dd" example: "2020-01-01" Note: we do not recommend using a custom time range for the past year’s dates' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, data will be provided for the last 12 months; minimum value: two years back from today’s date; maximum value: one month from today’s date; note: we do not recommend using a custom time range for the past year’s dates; date format: "yyyy-mm-dd" example: "2020-03-15" Note: we do not recommend using a custom time range for the past year’s dates' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' search_partners: type: boolean description: 'Bing search partners type optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search. default value: false – results are returned for Bing, AOL, and Yahoo search networks' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/search_volume/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/bing/search_volume_history/locations_and_languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations and Languages for Bing ‘Search Volume History’ Endpoint description: 'The location and language pairs the Bing search-volume-history endpoint accepts. Free: upstream cost is 0. Reference data - fetch once and reuse. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_keywords_bing_volume_history_locales responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 tasks.result.available_locations: type: array items: type: string description: array of available locations for a certain language tasks.result.available_locations.location_code: type: integer description: location code tasks.result.available_locations.location_name: type: string description: full name of the location tasks.result.available_locations.country_iso_code: type: string description: ISO country code of the location tasks.result.available_locations.location_type: type: string description: location type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/bing/search_volume_history/locations_and_languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/clickstream_data/bulk_search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.15 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Bulk Clickstream Search Volume’ Tasks description: 'Clickstream search volume for many `keywords` in one call, without the language dimension. Measured at 1.3 KB. 🔴 **Measured at $0.18 upstream against $0.012 billed - fifteen times, the widest gap found anywhere in this provider.** One call for many keywords, never one per keyword. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The per-keyword-with-language variant is `post_dataforseo_keywords_clickstream_search_volume_live`. Since the price is per call and not per keyword, this is the one to use for a list.' operationId: post_dataforseo_keywords_clickstream_bulk_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code in a POST array tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.keyword: type: string description: keyword keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character) tasks.result.items.search_volume: type: integer description: clickstream-based average monthly search volume rate represents the (approximate) number of searches for the given keyword idea based on clickstream you can learn more about clickstream search volume in this Help Center article tasks.result.items.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.monthly_searches.year: type: integer description: year tasks.result.items.monthly_searches.month: type: integer description: month tasks.result.items.monthly_searches.search_volume: type: integer description: monthly average search volume rate '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000; each keyword should be at least 3 characters long; the keywords will be converted to lowercase format; Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages example: 2840' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/clickstream_data/bulk_search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/clickstream_data/dataforseo_search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.36 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘DataForSEO Search Volume’ Tasks description: 'Search volume derived from clickstream panels rather than the ad platforms, for a list of `keywords`. `use_clickstream` toggles the blend. Returns `location_code`, `language_code`, `use_clickstream`, `items_count` and `items`. Measured at 1.3 KB. 🔴 **Measured at $0.18 upstream against $0.012 billed - fifteen times, the widest gap found anywhere in this provider.** One call for many keywords, never one per keyword. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Clickstream volume often disagrees with `post_dataforseo_keywords_gads_search_volume_live`, which is the point: one measures what advertisers are shown, the other what people did.' operationId: post_dataforseo_keywords_clickstream_search_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: array items: type: string description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.items_count: type: string description: ithe number of results returned in the items array tasks.result.items: type: array items: type: string description: array of keywords contains keywords and their search volume rates tasks.result.items.keyword: type: string description: keyword provided in the POST array tasks.result.items.use_clickstream: type: boolean description: 'indicates if the use_clickstream parameter is active possible values: true, false' tasks.result.items.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.monthly_searches: type: array items: type: string description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.monthly_searches.year: type: integer description: year tasks.result.items.monthly_searches.month: type: integer description: month tasks.result.items.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000 the keywords will be converted to lowercase format Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages example: United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages example: 2826' language_name: type: string description: 'full name of search engine language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages example: English' language_code: type: string description: 'search engine language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages example: en' use_clickstream: type: boolean description: 'use clickstream data to provide results optional field if set to true, you will get DataForSEO search volume values based on clickstream data; if set to false, Bing search volume data will be used to calculate DataForSEO search volume; default value: true; Note: Bing search volume is available for locations provided in Bing Search Volume History Locations and Bing Ads Locations endpoints; search volume values for any other location are calculated based on clickstream data even if you set this parameter to false' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/clickstream_data/dataforseo_search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/clickstream_data/global_search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.36 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Clickstream Global Search Volume’ Tasks description: 'Clickstream search volume for `keywords` worldwide, with no location argument at all - the global total and its per-country breakdown. Measured at 1.9 KB. 🔴 **Measured at $0.18 upstream against $0.012 billed - fifteen times, the widest gap found anywhere in this provider.** One call for many keywords, never one per keyword. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to decide which markets are worth a per-location call; the located variant is `post_dataforseo_keywords_clickstream_search_volume_live`.' operationId: post_dataforseo_keywords_clickstream_global_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.keyword: type: string description: keyword keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character) tasks.result.items.search_volume: type: integer description: clickstream-based average monthly search volume rate represents the (approximate) number of searches for the given keyword idea based on clickstream you can learn more about clickstream search volume in this Help Center article tasks.result.items.country_distribution: type: array items: type: string description: distribution of clickstream by countries represents clickstream-based search volume in available countries, as well as its respective percentage of global search volume tasks.result.items.country_distribution.country_iso_code: type: string description: country ISO code tasks.result.items.country_distribution.search_volume: type: integer description: search volume in a given country tasks.result.items.country_distribution.percentage: type: number description: percentage of global search volume '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000; each keyword should be at least 3 characters long; the keywords will be converted to lowercase format; Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/clickstream_data/global_search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/clickstream_data/locations_and_languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations and Languages for DataForSEO Clickstream Data API description: 'The locations and languages the clickstream endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code`, `location_type` and `available_languages` nested per location. Measured at 20.5 KB. Free: upstream cost is 0.' operationId: get_dataforseo_keywords_clickstream_locales responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.location_code_parent: type: integer description: the code of the superordinate location the value will be null as Country is the only supported location_type for this API tasks.result.country_iso_code: type: string description: ISO country code of the location tasks.result.location_type: type: string description: 'location type possible values: Country' tasks.result.available_languages: type: array items: type: string description: supported languages contains the languages which are supported for a specific location tasks.result.available_languages.language_name: type: string description: language name tasks.result.available_languages.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/clickstream_data/locations_and_languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/dataforseo_trends/demography/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0048 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘DataForSEO Trends Demography’ Tasks description: 'The Google Trends audience behind a keyword: age and gender splits over the same window `post_dataforseo_keywords_trends_explore_live` uses, with the same `type` and date arguments. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Cheap like its sibling. For where rather than who, use `post_dataforseo_keywords_trends_subregion_interests_live`.' operationId: post_dataforseo_keywords_trends_demography_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keywords: type: array items: type: string description: keywords in a POST array tasks.result.type: type: array items: type: string description: search engine type in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keyword popularity and related data tasks.result.items.position: type: integer description: 'the alignment of the element can take the following values: 1, 2, 3, 4, etc.' tasks.result.items.type: type: string description: type of element = ‘demography’ tasks.result.items.keywords: type: array items: type: string description: relevant keywords the data included in the demography and demography_comparison is based on the keywords listed in this array tasks.result.items.demography: type: object description: demographic breakdown of keyword popularity data per each specified term conains keyword popularity data by age and gender tasks.result.items.demography.age: type: array items: type: string description: distribution of keyword popularity by age tasks.result.items.demography.age.keyword: type: string description: relevant keyword for which demographic data is provided tasks.result.items.demography.age.values: type: array items: type: string description: contains age range and corresponding keyword popularity values tasks.result.items.demography.age.values.type: type: string description: 'age range can take the following values: 18-24, 25-34, 35-44, 45-54, 55-64' tasks.result.items.demography.age.values.value: type: integer description: 'keyword popularity rate within the specified age range using this value you can understand how popular a keyword is within each age range; calculation: we determine the highest popularity value for the relevant keyword across all age groups, and then express all other values as a percentage of that highest value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' tasks.result.items.demography.gender: type: array items: type: string description: distribution of keyword popularity by gender tasks.result.items.demography.gender.keyword: type: string description: relevant keyword for which demographic data is provided tasks.result.items.demography.gender.values: type: array items: type: string description: contains gender and corresponding keyword popularity values tasks.result.items.demography.gender.values.type: type: string description: 'gender category can take the following values: female, male' tasks.result.items.demography.gender.values.value: type: integer description: 'keyword popularity rate within the specified gender category using this value you can understand how popular a keyword is within each gender category; calculation: we determine the highest popularity value for the relevant keyword across all gender categories, and then express all other values as a percentage of that highest value (100); a value of 100 is the highest popularity for the term; a value of 0 means there was not enough data for this term' tasks.result.items.demography_comparison: type: object description: comparison of demographic data on keyword popularity for the specified parameters conains keyword popularity data by age and gender if you specified a single keyword, the value will be null tasks.result.items.demography_comparison.age: type: object description: comparison of keyword popularity data by age tasks.result.items.demography_comparison.age.$18-24: type: array items: type: string description: 'indicates age range and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified age range variable can take the following values: 18-24, 25-34, 35-44, 45-54, 55-64; using the values from this array, you can understand which of the specified keywords is more popular within the related age range; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each age range, and then express all other values as a percentage of the total value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' tasks.result.items.demography_comparison.gender: type: object description: comparison of keyword popularity data by gender tasks.result.items.demography_comparison.gender.female: type: array items: type: string description: 'indicates gender category and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified gender category; using the values from this array, you can understand which of the specified keywords is more popular within the related gender category; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each gender category, and then express all other values as a percentage of the total value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' tasks.result.items.demography_comparison.gender.male: type: array items: type: string description: 'indicates gender category and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified gender category; using the values from this array, you can understand which of the specified keywords is more popular within the related gender category; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each gender category, and then express all other values as a percentage of the total value (100); a value of 100 is the highest popularity for the term a value of 0 means there was not enough data for this term' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field the maximum number of keywords you can specify: 5 avoid symbols and special characters (e.g., UTF symbols, emojis); specifying non-Latin characters, you’ll get data for the countries where they are used learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_name belongs to; example: United Kingdom' location_code: type: integer description: 'search engine location code optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_code belongs to; example: 2840' type: type: string description: 'dataforseo trends type optional field if you don’t specify this field, the web type will be used by default possible values: web, news, ecommerce' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, the current day and month of the preceding year will be used by default minimal value for the web type: 2004-01-01 minimal value for other types: 2008-01-01 date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' time_range: type: string description: 'preset time ranges optional field if you specify date_from or date_to parameters, this field will be ignored when setting a task possible values for all type parameters: past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/dataforseo_trends/demography/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/dataforseo_trends/explore/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘DataForSEO Trends Explore’ Tasks description: 'Interest over time for up to five `keywords`, the Google Trends curve. Returns `keywords`, `type`, `location_code`, `language_code`, `datetime`, `items_count` and `items`. `type` selects web, news, images, youtube or shopping, and `date_from`/`date_to` set the window. Measured at 21.7 KB and **$0.0012 upstream - by far the best margin in this family**, two orders of magnitude cheaper than the Google Ads endpoints beside it. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Trends gives relative interest, not absolute volume; for counts use `post_dataforseo_keywords_gads_search_volume_live`.' operationId: post_dataforseo_keywords_trends_explore_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keywords: type: array items: type: string description: keywords in a POST array tasks.result.type: type: array items: type: string description: search engine type in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keyword popularity and related data tasks.result.items.position: type: integer description: 'the alignment of the element can take the following values: 1, 2, 3, 4, etc.' tasks.result.items.type: type: string description: type of element = ‘dataforseo_trends_graph’ tasks.result.items.keywords: type: array items: type: string description: relevant keywords the data included in the dataforseo_trends_graph element is based on the keywords listed in this array tasks.result.items.data: type: array items: type: string description: DataForSEO Trends data for the specified parameters tasks.result.items.data.date_from: type: string description: 'start date of the corresponding time range in the UTC format: “yyyy-mm-dd”' tasks.result.items.data.date_to: type: string description: 'end date of the corresponding time range in the UTC format: “yyyy-mm-dd”' tasks.result.items.data.timestamp: type: integer description: a point in time in the Unix time format tasks.result.items.data.values: type: array items: type: string description: relative keyword popularity rate at a specific timestamp represents the keyword popularity rate over the given time range if you specify more than one keyword, the values will be averaged to the highest value across all specified keywords a value of 100 is the peak popularity for the term. A value of 50 means that the term is half as popular. A score of 0 means there was not enough data for this term tasks.result.items.averages: type: array items: type: string description: keyword popularity values averaged over the whole time range '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field the maximum number of keywords you can specify: 5 learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_name belongs to; example: United Kingdom' location_code: type: integer description: 'search engine location code optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_code belongs to; example: 2840' type: type: string description: 'dataforseo trends type optional field if you don’t specify this field, the web type will be used by default possible values: web, news, ecommerce' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, the current day and month of the preceding year will be used by default minimal value for the web type: 2004-01-01 minimal value for other types: 2008-01-01 date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' time_range: type: string description: 'preset time ranges optional field if you specify date_from or date_to parameters, this field will be ignored when setting a task possible values for all type parameters: past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/dataforseo_trends/explore/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/dataforseo_trends/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of DataForSEO Trends Locations description: 'The locations the Trends endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code`, `location_type`, plus `geo_name` and `geo_id` - the last two are Google''s own geo identifiers and appear on no other location list in this provider. Measured at 36.8 KB. Free: upstream cost is 0.' operationId: get_dataforseo_keywords_trends_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: country: type: string description: 'country ISO code optional field specify the ISO code if you want to filter the list of locations by country example: us' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/dataforseo_trends/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/dataforseo_trends/subregion_interests/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0048 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘DataForSEO Trends Subregion Interests’ Tasks description: 'Where interest in a keyword is concentrated, broken down by subregion within `location_code`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to pick which markets deserve a located search-volume call, which costs $0.09 each on the Google Ads side. For who rather than where, `post_dataforseo_keywords_trends_demography_live`.' operationId: post_dataforseo_keywords_trends_subregion_interests_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keywords: type: array items: type: string description: keywords in a POST array tasks.result.type: type: array items: type: string description: search engine type in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.datetime: type: string description: 'date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keyword popularity and related data tasks.result.items.position: type: integer description: 'the alignment of the element can take the following values: 1, 2, 3, 4, etc.' tasks.result.items.type: type: string description: type of element = ‘subregion_interests’ tasks.result.items.keywords: type: array items: type: string description: relevant keywords the data included in the interests and interests_comparison is based on the keywords listed in this array tasks.result.items.interests: type: array items: type: string description: subregional keyword popuarity data for each specified term tasks.result.items.interests.keyword: type: string description: relevant keyword the data included in the values element is based on this keyword tasks.result.items.interests.values: type: array items: type: string description: contains data on relative keyword popularity by country or region tasks.result.items.interests.values.geo_id: type: string description: 'location identifier you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: US-NY' tasks.result.items.interests.values.geo_name: type: string description: 'location name you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: Andorra' tasks.result.items.interests.values.value: type: integer description: 'relative keyword popularity rate in a given location represents location-specific keyword popularity rate over the specified time range; using this value you can understand how popular a keyword is in one location compared to another location; calculation: we determine the highest popularity value for the relevant keyword across all locations, and then express all other values as a percentage of that highest value (100); a value of 100 is the highest popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term' tasks.result.items.interests_comparison: type: object description: comparison of data on subregional keyword popularity for the specified parameters if you specified a single keyword, the value will be null tasks.result.items.interests_comparison.items: type: array items: type: string description: keyword popularity values per location values in this array represent percentages relative to the maximum value within each region tasks.result.items.interests_comparison.items.geo_id: type: string description: 'location identifier you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: US-NY' tasks.result.items.interests_comparison.items.geo_name: type: string description: 'location name you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: Andorra' tasks.result.items.interests_comparison.items.values: type: array items: type: string description: 'keyword popularity rates within a given location represents location-specific keyword popularity rate over the specified time range; using these values, you can understand which of the specified keywords is more popular in the related location; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the highest popularity value across all specified keywords within a given location, and then express the popularity values of each keyword as a percentage of the highest value (100); a value of 100 is the peak popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term' tasks.result.items.interests_comparison.absolute_items: type: array items: type: string description: keyword popularity rates across all locations values in this array represent percentages relative to the maximum value across all locations tasks.result.items.interests_comparison.absolute_items.geo_id: type: string description: 'location identifier you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: US-NY' tasks.result.items.interests_comparison.absolute_items.geo_name: type: string description: 'location name you can use this field for matching obtained results with location parameters specified in the request see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations example: Andorra' tasks.result.items.interests_comparison.absolute_items.values: type: array items: type: string description: 'keyword popularity rates relative to all locations represents location-specific keyword popularity rate over the specified time range; using these values, you can understand how popular each keyword is compared to all other keywords across all locations; the first value in the array is provided for the first term from the keywords array, the second value is provided for the second keyword, and so on; calculation: we determine the highest popularity value across all keywords across all locations, and then express all other values as a percentage of that highest value (100); a value of 100 is the peak popularity for the term a value of 50 means that the term is half as popular a value of 0 means there was not enough data for this term' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field the maximum number of keywords you can specify: 5 avoid symbols and special characters (e.g., UTF symbols, emojis); specifying non-Latin characters, you’ll get data for the countries where they are used learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_name belongs to; example: United Kingdom' location_code: type: integer description: 'search engine location code optional field if you don’t use this field, you will recieve global results if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations note that the data will be provided for the country the specified location_code belongs to; example: 2840' type: type: string description: 'dataforseo trends type optional field if you don’t specify this field, the web type will be used by default possible values: web, news, ecommerce' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, the current day and month of the preceding year will be used by default minimal value for the web type: 2004-01-01 minimal value for other types: 2008-01-01 date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' time_range: type: string description: 'preset time ranges optional field if you specify date_from or date_to parameters, this field will be ignored when setting a task possible values for all type parameters: past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/dataforseo_trends/subregion_interests/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Ads Traffic By Keywords’ Results by id description: 'Retrieves a queued Google Ads traffic forecast by `id`: projected impressions, clicks, cost and average position for the bid you specified. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Unlike the volume endpoints this is a projection, not a measurement - the numbers move with `bid` and `match`.' operationId: get_dataforseo_keywords_gads_ad_traffic_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Ad Traffic By Keywords’ Tasks description: 'Queues a forecast of clicks, impressions and spend for `keywords` at a given `bid` and `match` type, returning a task `id`. `search_partners` includes Google''s partner network. 🔴 **Measured at $0.09 upstream against the $0.012 billed - a sevenfold loss on every call.** The price does not fall with fewer keywords, so send the whole batch in one call. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the only Google Ads endpoint here with no live variant - forecasting always queues. Retrieve with `get_dataforseo_keywords_gads_ad_traffic_fetch`.' operationId: post_dataforseo_keywords_gads_ad_traffic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 1000 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the keywords you specify will be converted to a lowercase format Note #1: Google Ads may return no data for certain groups of keywords; Note #2: Google Ads provides combined search volume values for groups of similar keywords to obtain search volume for similar keywords, we recommend submitting such keywords in separate requests; Note #3: Google Ads doesn’t allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can’t use them when setting a task; to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' bid: type: number description: the maximum custom bid required field the collected data will be based on this value it stands for the price you are willing to pay for an ad; the higher value you specify here, the higher values you will get in the returned metrics learn more in this help center article match: type: string description: 'keywords match-type required field can take the following values: exact, broad, phrase' search_partners: type: boolean description: 'include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites' location_name: type: string description: 'full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English' language_code: type: string description: 'search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en' date_from: type: string description: 'starting date of the forecasting time range required field if you specify date_to if you indicate date_from and date_to, you don’t need to specify date_interval minimum value is tomorrow’s date the value you specify in date_from shouldn’t be further than date_to date format: "yyyy-mm-dd" example: "2021-10-30"if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior' date_to: type: string description: 'ending date of the forecasting time range required field if you specify date_from if you indicate date_from and date_to, you don’t need to specify date_interval minimum value is date_from +1 day maximum value is current day and month of the next year date format: "yyyy-mm-dd" example: "2022-10-30"' date_interval: type: string description: 'forecasting date interval optional field if you specify date_interval, you don’t need to indicate date_from and date_to possible values: next_week, next_month, next_quarter default value: next_month' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by relevance, impressions, ctr, average_cpc, cost, or clicks in the descending order default value: relevance' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords - bid - match allOf: - anyOf: - required: - date_from - date_to - not: anyOf: - required: - date_from - required: - date_to tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/keywords_for_keywords/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.18 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Keywords For Keywords’ Tasks description: 'Expands a seed list of `keywords` into related Google Ads keywords, each with `keyword`, `location_code`, `language_code`, `search_partners`, `competition`, `competition_index`, `search_volume`, `low_top_of_page_bid`, `high_top_of_page_bid`, `cpc` and `monthly_searches`. 🔴 **Measured at 2.8 MB for a single seed keyword, and this endpoint takes no limit parameter** - the expansion is as large as Google''s own, and it lands whole in the agent''s context. Pair it with a narrow seed, or use `post_dataforseo_labs_google_keyword_ideas_live`, which does accept a limit. 🔴 **Measured at $0.09 upstream against the $0.012 billed - a sevenfold loss on every call.** The price does not fall with fewer keywords, so send the whole batch in one call. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_gads_kw_for_keywords_live responses: '200': description: Successful response content: application/json: schema: type: object '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 20 The maximum number of characters for each keyword: 80 the keywords you specify will be converted to a lowercase format Note: Google Ads may return no data for certain groups of keywords visit our Help Center to learn more Also note that Google Ads doesn’t allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can’t use them when setting a task; to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English' language_code: type: string description: 'search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en' search_partners: type: boolean description: 'include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites' date_from: type: string description: 'starting date of the time range optional field date format: "yyyy-mm-dd" minimal value: 4 years from the current date by default, data is returned for the past 12 months; Note: the indicated date cannot be greater than that specified in date_to and/or yesterday’s date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior' date_to: type: string description: 'ending date of the time range optional field Note: the indicated date cannot be greater than yesterday’s date; if you don’t specify this field, yesterday’s date will be used by default date format: "yyyy-mm-dd" example: "2022-11-30"' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order default value: relevance' include_adult_keywords: type: boolean description: 'include keywords associated with adult content optional field if set to true, adult keywords will be included in the response default value: false note that the API may return no data for such keywords due to Google Ads restrictions' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/keywords_for_keywords/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/keywords_for_keywords/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Keywords For Keywords’ Results by id description: 'Retrieves a queued Google Ads keyword-expansion task by `id`. 🔴 Same 2.8 MB order of magnitude as the live twin. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_keywords_gads_kw_for_keywords_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/keywords_for_keywords/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/keywords_for_keywords/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Keywords For Keywords’ Tasks description: 'Queues a Google Ads keyword expansion, returning a task `id`. Accepts a `target` alongside `keywords`, which the live endpoint does not. 🔴 **Measured at $0.09 upstream against the $0.012 billed - a sevenfold loss on every call.** The price does not fall with fewer keywords, so send the whole batch in one call. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 The result is the same 2.8 MB order as the live twin - queuing defers the context cost, it does not reduce it. Retrieve with `get_dataforseo_keywords_gads_kw_for_keywords_fetch`.' operationId: post_dataforseo_keywords_gads_kw_for_keywords_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 20 The maximum number of characters for each keyword: 80 the keywords you specify will be converted to a lowercase format Note: Google Ads may return no data for certain groups of keywords visit our Help Center to learn more Also note that Google Ads doesn’t allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can’t use them when setting a task; to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' target: type: string description: 'target website optional field specify a website or URL to get a list of keywords relevant to it; Note: if a website url is specified, you will still get keywords relevant for the entire website' location_name: type: string description: 'full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English' language_code: type: string description: 'search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en' search_partners: type: boolean description: 'include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites' date_from: type: string description: 'starting date of the time range optional field date format: "yyyy-mm-dd" minimal value: 4 years from the current date by default, data is returned for the past 12 months; Note: the indicated date cannot be greater than that specified in date_to and/or yesterday’s date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior' date_to: type: string description: 'ending date of the time range optional field Note: the indicated date cannot be greater than yesterday’s date; if you don’t specify this field, yesterday’s date will be used by default date format: "yyyy-mm-dd" example: "2022-11-30"' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order default value: relevance' include_adult_keywords: type: boolean description: 'include keywords associated with adult content optional field if set to true, adult keywords will be included in the response default value: false note that the API may return no data for such keywords due to Google Ads restrictions' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/keywords_for_keywords/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/keywords_for_site/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Keywords For Site’ Tasks description: 'The Google Ads keywords a whole site ranks or bids for, from a `target` domain, each with `keyword`, `location_code`, `language_code`, `search_partners`, `competition`, `competition_index`, `search_volume`, `low_top_of_page_bid`, `high_top_of_page_bid`, `cpc` and `monthly_searches`. `target_type` selects the page or the domain. 🔴 **Measured at 7.2 MB for one site - the largest live response in this provider - and there is no limit parameter to cap it.** Treat this as a bulk export, not something to call inside an agent loop; `post_dataforseo_labs_google_kw_for_site_live` answers a similar question with paging. 🔴 **Measured at $0.09 upstream against the $0.012 billed - a sevenfold loss on every call.** The price does not fall with fewer keywords, so send the whole batch in one call. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_gads_kw_for_site_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, the value is null tasks.result.search_partners: type: boolean description: include Google search partners the value you specified when setting the task if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search; if false, the results are returned for Google search sites only tasks.result.competition: type: string description: 'competition represents the relative level of competition associated with the given keyword in paid SERP only possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.competition_index: type: integer description: competition index the competition index for the query indicating how competitive ad placement is for the keyword can take values from 0 to 100 the level of competition from 0 to 100 is determined by the number of ad slots filled divided by the total number of ad slots available if not enough data is available, the value is null; learn more about the metric in this help center article tasks.result.search_volume: type: integer description: monthly average search volume rate represents the (approximate) number of searches for the given keyword idea either on google.com or google.com and partners, depending on the user’s targeting if there is no data, the value is null tasks.result.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.cpc: type: number description: cost per click indicates the amount paid (USD) for each click on the ad displayed for a given keyword tasks.result.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations if there is no data, the value is null tasks.result.monthly_searches.year: type: integer description: year tasks.result.monthly_searches.month: type: integer description: month tasks.result.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.keyword_annotations: type: object description: the annotations for the keyword tasks.result.concepts: type: array items: type: string description: the list of concepts for the keyword tasks.result.concepts.name: type: string description: the concept name for the keyword in the concept_group tasks.result.concepts.concept_group: type: object description: the concept group of the concept details tasks.result.concepts.concept_group.name: type: string description: the concept group name tasks.result.concepts.concept_group.type: type: string description: the concept group type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'domain or page required field the domain name of the target website or the url of the target page; note: to obtain keywords for the target website, use the target_type parameter' target_type: type: string description: 'search keywords for site or for url optional field possible values: site, page; default value: page; if set to site, keywords will be provided for the entire site; if set to page, keywords will be provided for the specified webpage' location_name: type: string description: 'full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English' language_code: type: string description: 'search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en' search_partners: type: boolean description: 'include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites' date_from: type: string description: 'starting date of the time range optional field date format: "yyyy-mm-dd" minimal value: 4 years from the current date by default, data is returned for the past 12 months; Note: the indicated date cannot be greater than that specified in date_to and/or yesterday’s date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior' date_to: type: string description: 'ending date of the time range optional field Note: the indicated date cannot be greater than yesterday’s date; if you don’t specify this field, yesterday’s date will be used by default date format: "yyyy-mm-dd" example: "2022-11-30"' include_adult_keywords: type: boolean description: 'include keywords associated with adult content optional field if set to true, adult keywords will be included in the response default value: false note that the API may return no data for such keywords due to Google Ads restrictions' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order default value: relevance' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/keywords_for_site/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/keywords_for_site/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get ‘Keywords For Site’ Results by id description: 'Retrieves a queued Google Ads keywords-for-site task by `id`. 🔴 Same 7.2 MB order as the live twin. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_keywords_gads_kw_for_site_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/keywords_for_site/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/keywords_for_site/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting ‘Keywords For Site’ Tasks description: 'Queues a Google Ads keywords-for-site task, returning a task `id`. 🔴 **Measured at $0.09 upstream against the $0.012 billed - a sevenfold loss on every call.** The price does not fall with fewer keywords, so send the whole batch in one call. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 The result is the same 7.2 MB order as the live twin. Retrieve with `get_dataforseo_keywords_gads_kw_for_site_fetch`.' operationId: post_dataforseo_keywords_gads_kw_for_site_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'domain or page required field the domain name of the target website or the url of the target page; note: to obtain keywords for the target website, use the target_type parameter' target_type: type: string description: 'search keywords for site or url optional field possible values: site, page; default value: page if set to site, keywords will be provided for the entire site; if set to page, keywords will be provided for the specified webpage' location_name: type: string description: 'full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English' language_code: type: string description: 'search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en' search_partners: type: boolean description: 'include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites' date_from: type: string description: 'starting date of the time range optional field date format: "yyyy-mm-dd" minimal value: 4 years from the current date by default, data is returned for the past 12 months; Note: the indicated date cannot be greater than that specified in date_to and/or yesterday’s date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior' date_to: type: string description: 'ending date of the time range optional field Note: the indicated date cannot be greater than yesterday’s date; if you don’t specify this field, yesterday’s date will be used by default date format: "yyyy-mm-dd" example: "2022-11-30"' include_adult_keywords: type: boolean description: 'include keywords associated with adult content optional field if set to true, adult keywords will be included in the response default value: false note that the API may return no data for such keywords due to Google Ads restrictions' sort_by: type: string description: 'results sorting parameters optional field Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order default value: relevance' postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/keywords_for_site/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.18 max: 0.18 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live ‘Google Ads Search Volume’ Tasks description: 'Google Ads search volume for a list of `keywords`. Returns `keyword`, `location_code`, `language_code`, `search_partners`, `competition`, `competition_index`, `search_volume`, `low_top_of_page_bid`, `high_top_of_page_bid`, `cpc` and `monthly_searches`, plus `spell` when Google corrected the term. Measured at 3.8 KB for one keyword. 🔴 **Measured at $0.09 upstream against the $0.012 billed - a sevenfold loss on every call.** The price does not fall with fewer keywords, so send the whole batch in one call. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the classical search-volume number; for how often people ask an assistant instead, use `post_dataforseo_ai_keyword_volume_live`. The submit and fetch twins of this endpoint do the same work asynchronously, at the same price, for batches too large to wait on.' operationId: post_dataforseo_keywords_gads_search_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: array items: type: string description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.keyword: type: string description: keyword keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character) tasks.result.spell: type: string description: correct spelling of the keyword Note:if the keyword in the POST array appears to be misspelled, data will be returned for the correctly spelled keyword; we use the functionality of Google Ads API to check and validate the spelling of keywords, learn more by this link tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.search_partners: type: boolean description: indicates whether data from partner networks included in the response tasks.result.competition: type: string description: 'competition represents the relative amount of competition associated with the given keyword in paid SERP only; this value is based on Google Ads data and can take the following values: HIGH, MEDIUM, LOW; if there is no data the value is null; learn more about the metric in this help center article' tasks.result.competition_index: type: integer description: competition represents the relative amount of competition associated with the given keyword in paid SERP only; this value is based on Google Ads data and can be between 0 and 100 (inclusive); if there is no data the value is null; learn more about the metric in this help center article tasks.result.search_volume: type: integer description: monthly average search volume rate; represents either the (approximate) number of searches for the given keyword idea on google.com or google.com and partners, depending on the user’s targeting; if there is no data then the value is null tasks.result.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers); the value may differ depending on the location specified in a POST request tasks.result.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers); the value may differ depending on the location specified in a POST request tasks.result.cpc: type: number description: cost per click indicates the amount paid (USD) for each click on the ad displayed for a given keyword tasks.result.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months by default), targeted to the specified geographic locations; if there is no data then the value is null tasks.result.monthly_searches.year: type: integer description: year tasks.result.monthly_searches.month: type: integer description: month tasks.result.monthly_searches.search_volume: type: integer description: monthly average search volume rate '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 1000 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the keywords you specify will be converted to a lowercase format Note #1: Google Ads may return no data for certain groups of keywords; Note #2: Google Ads provides combined search volume values for groups of similar keywords to obtain search volume for similar keywords, we recommend submitting such keywords in separate requests; Note #3: Google Ads doesn’t allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can’t use them when setting a task; to learn more about which symbols and characters can be used, please refer to this article learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom' location_code: type: integer description: 'search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142' language_name: type: string description: 'full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English' language_code: type: string description: 'search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en' search_partners: type: boolean description: 'include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites' date_from: type: string description: 'starting date of the time range optional field date format: "yyyy-mm-dd" minimal value: 4 years from the current date by default, data is returned for the past 12 months; Note: the indicated date cannot be greater than that specified in date_to and/or yesterday’s date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior' date_to: type: string description: 'ending date of the time range optional field Note: the indicated date cannot be greater than the past month, Google Ads does not return data on the current month; if you don’t specify this field, yesterday’s date will be used by default date format: "yyyy-mm-dd" example: "2022-11-30"' include_adult_keywords: type: boolean description: 'include keywords associated with adult content optional field if set to true, adult keywords will be included in the response default value: false note that the API may return no data for such keywords due to Google Ads restrictions' sort_by: type: string description: 'results sorting parameters optional field use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in the descending order default value: relevance' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data array of the response required: - keywords example: - keywords: - accounting software location_code: 2840 language_code: en tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/search_volume/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Search Volume Results by id description: 'Retrieves a queued Google Ads search-volume task by `id`. Same shape as `post_dataforseo_keywords_gads_search_volume_live`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_keywords_gads_search_volume_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/search_volume/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_ads/status: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Google Ads Status description: 'Whether DataForSEO''s Google Ads data is current: `actual_data`, `date_update`, `last_year_in_monthly_searches` and `last_month_in_monthly_searches`. Measured at 1 KB. Free: upstream cost is 0. **Worth checking before a spend decision** - it tells you how stale the `monthly_searches` arrays on every Google Ads response actually are.' operationId: get_dataforseo_keywords_gads_status responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: the data specified in the API call tasks.result: type: array items: type: string description: array of results tasks.result.actual_data: type: boolean description: indicates whether Google updated keyword data for the previous month generally, Google updates keyword data in the middle of the month if the value is true, Google currently provides up-to-date data for the previous month if the value is false, we are not able to provide data for the previous month tasks.result.date_update: type: string description: 'date of the latest update of Google Ads data indicates the latest date when Google updated search volume, CPC, and other keyword metrics example: 2020-05-15' tasks.result.last_year_in_monthly_searches: type: integer description: the latest year for which search volume data is available tasks.result.last_month_in_monthly_searches: type: integer description: the latest month for which search volume data is available '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_ads/status source: https://github.com/AIsa-team/aisa-proxy /dataforseo/keywords_data/google_trends/categories: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Trends Categories description: 'The Google Trends category tree, as `category_code`, `category_name` and `category_code_parent`. 🔴 **Measured at 122 KB with no limit or filter parameter** - the same shape as the content and technology taxonomies elsewhere in this provider. Fetch it once and keep the branch you need. Free: upstream cost is 0.' operationId: get_dataforseo_keywords_google_trends_categories responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.category_code: type: integer description: unique google trends category identifier tasks.result.category_name: type: string description: name of the google trends category tasks.result.category_code_parent: type: integer description: 'the code of the superordinate category example: "category_code": 1100, "category_name": "Superhero Films", "category_code_parent": 1097 where category_code_parent corresponds to: "category_code": 1097, "category_name": "Action & Adventure Films"' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/keywords_data/google_trends/categories source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/aggregation_technologies/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0264 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Aggregation Technologies description: 'Counts rather than domains: how many sites match a technology query, broken down by group, category and technology. Returns `total_count`, `items_count`, `offset` and `items`, with `internal_groups_list_limit`, `internal_categories_list_limit`, `internal_technologies_list_limit` and `internal_list_limit` each capping a different nesting level - set all four or the response grows quickly. Measured at 680 bytes with every limit at 1, the smallest response in this family. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status. For the domains themselves rather than their counts, use `post_dataforseo_domains_tech_domains_by_technology_live`.' operationId: post_dataforseo_domains_tech_aggregation_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.: type: string description: type of element = ‘aggregation_technologies_item’ tasks.result.group: type: string description: technology group id tasks.result.category: type: string description: technology category id tasks.result.technology: type: string description: technology name tasks.result.groups_count: type: integer description: technology groups count number of domains that match the parameters you specified and are using technologies from the indicated group tasks.result.categories_count: type: integer description: technology categories count number of domains that match the parameters you specified and are using technologies from the indicated category tasks.result.technologies_count: type: integer description: technologies count number of domains that match the parameters you specified and are using the indicated technology '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: group: type: string description: 'id of the target technology group required field if you don’t specify technology, category or keyword at least one field (group, category, keyword, technology) must be set you can find the full list of technology group ids on this page example: "marketing"' category: type: string description: 'id of the target technology category required field if you don’t specify group, keyword or technology at least one field (group, category, keyword, technology) must be set you can find the full list of technology category ids on this page example: "crm"' technology: type: string description: 'target technology required field if you don’t specify group, keyword or category at least one field (group, category, keyword, technology) must be set you can find the full list of technologies on this page example: "Salesforce"' keyword: type: string description: 'target keyword in the domain’s meta keywords required field if you don’t specify group, category or technology at least one field (group, category, keyword, technology) must be set UTF-8 encoding example: "seo"learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' mode: type: string description: 'search mode optional field possible search mode types: as_is – search for results exactly matching the specified group ids, category ids, or technology names entry – search for results matching a part of the specified group ids, category ids, or technology names default value: as_is' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in, like,not_like you can use the % operator with like and not_like to match any string of zero or more characters you can use the following parameters to filter the results: domain_rank, last_visited, country_iso_code, language_code, content_language_code Note: all filtering parameters are taken from the domain_technology_item of the domain_technologies endpoint; example: [["country_iso_code","=","US"], "and", ["domain_rank",">",800]]for more information about filters, please refer to Domain Analytics Technologies API – Filters' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the following values to sort the results: groups_count, categories_count, technologies_count possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["groups_count,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["groups_count,desc","technologies_count,desc"] default value: ["groups_count,desc","categories_count,desc","technologies_count,desc"]' internal_groups_list_limit: type: integer description: 'maximum number of returned technology groups optional field you can use this field to limit the number of items with identical "group" in the results default value: 5 minimum value: 1 maximum value: 10000' internal_categories_list_limit: type: integer description: 'maximum number of returned technology categories within the same group optional field you can use this field to limit the number of items with identical "category" in the results default value: 5 minimum value: 1 maximum value: 10000' internal_technologies_list_limit: type: integer description: 'maximum number of returned technologies within the same category optional field you can use this field to limit the number of items with identical "technology" in the results default value: 10 minimum value: 1 maximum value: 10000' internal_list_limit: type: integer description: 'maximum number of items with identical "category", "group", and "technology" optional field if you use this field, the values specified in internal_groups_list_limit, internal_categories_list_limit and internal_technologies_list_limit will be ignored; you can use this field to limit the number of items with identical "category", "group", or "technology" default value: 10 minimum value: 1 maximum value: 10000' limit: type: integer description: 'the maximum number of returned technologies optional field default value: 100 maximum value: 10000' offset: type: integer description: 'offset in the results array of returned domains optional field default value: 0 maximum value: 9999 if you specify the 10 value, the first ten technologies in the results array will be omitted and the data will be provided for the successive technologies' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response allOf: - anyOf: - required: - group - required: - category - required: - technology - required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/aggregation_technologies/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/domain_technologies/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.024 max: 0.024 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Technologies description: 'Everything detected about one domain from a single `target`. Returns `domain`, `title`, `description`, `meta_keywords`, `domain_rank`, `last_visited`, `country_iso_code`, `language_code`, `content_language_code`, `phone_numbers`, `emails`, `social_graph_urls` and `technologies`. Measured at 3.5 KB for stripe.com. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status. This is the per-domain direction; to go the other way and find the domains using a given technology use `post_dataforseo_domains_tech_domains_by_technology_live`. The `emails` and `phone_numbers` it surfaces are scraped from the site itself, not a contact database.' operationId: post_dataforseo_domains_tech_for_domain_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.type: type: string description: type of the returned data item = ‘domain_technology_item’ tasks.result.domain: type: string description: specified domain name tasks.result.title: type: string description: domain meta title tasks.result.description: type: string description: domain meta description tasks.result.meta_keywords: type: array items: type: string description: domain meta keywords tasks.result.domain_rank: type: string description: backlink rank of the target domain learn more about the metric and how it is calculated in this help center article tasks.result.last_visited: type: string description: 'most recent date when our crawler visited the domain in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2022-10-10 12:57:46 +00:00' tasks.result.country_iso_code: type: string description: domain ISO code ISO code of the country that the target domain is determined to belong to tasks.result.language_code: type: string description: domain language code of the language that the target domain is determined to be associated with tasks.result.content_language_code: type: string description: content language code of the language that content on the target domain is written in tasks.result.phone_numbers: type: array items: type: string description: phone numbers of the target contact phone numbers indicated on the target website tasks.result.emails: type: array items: type: string description: emails of the target emails indicated on the target website tasks.result.social_graph_urls: type: array items: type: string description: social media links and handles social media URLs detected in the social graphs of the target website tasks.result.technologies: type: object description: technologies used by target domain contains objects with the names of technologies used on the website see the full list of available technologies structured by groups and categories '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'target domain required field domain name of the website to analyze Note: results will be returned for the specified domain only' required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/domain_technologies/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/domains_by_html_terms/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0312 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domains by HTML Terms description: 'Finds domains whose HTML contains given `search_terms` - a raw string match where `post_dataforseo_domains_tech_domains_by_technology_live` matches a detected technology. Use it for a tracking snippet, an affiliate tag or a template signature that no detector names. Returns `total_count`, `items_count`, `offset`, `offset_token` and `items` carrying the same profile as the technology search. Measured at 1.8 KB for one item; cap with `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status.' operationId: post_dataforseo_domains_tech_domains_by_html_terms_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.offset: type: integer description: specified offset value tasks.result.offset_token: type: string description: token for subsequent requests by specifying the unique offset_token when setting a new task, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task tasks.result.items: type: array items: type: string description: items array tasks.result.type: type: string description: type of the item = ‘domain_technology_item’ tasks.result.domain: type: string description: specified domain name tasks.result.title: type: string description: domain meta title tasks.result.description: type: string description: domain meta description tasks.result.meta_keywords: type: array items: type: string description: domain meta keywords tasks.result.domain_rank: type: string description: backlink rank of the target domain learn more about the metric and how it is calculated in this help center article tasks.result.last_visited: type: string description: 'most recent date when our crawler visited the domain in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2022-10-10 12:57:46 +00:00' tasks.result.country_iso_code: type: string description: domain ISO code ISO code of the country that target domain is determined to belong to tasks.result.language_code: type: string description: domain language code of the language that target domain is determined to be associated with tasks.result.content_language_code: type: string description: content language code of the language that content on the target domain is written with tasks.result.phone_numbers: type: array items: type: string description: phone numbers of the target contact phone numbers indicated on the target website tasks.result.emails: type: array items: type: string description: emails of the target emails indicated on the target website tasks.result.social_graph_urls: type: array items: type: string description: social media links and handles social media URLs detected in the social graphs of the target website tasks.result.technologies: type: object description: technologies used by target domain contains objects with the names of technologies used on the website; to get a full list of technologies and their structure, refer to the technologies endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: search_terms: type: array items: type: string description: 'target search terms required field specify target HTML elements, tags, attributes, their content or all of the above if you specify more than one search term, you will receive only the domains containing all of the specified terms in the HTML code of their homepage maximum number of search terms you can specify: 10 example: ["data-attrid"]' keywords: type: array items: type: string description: 'target keywords in the domain’s title, description or meta keywords optional field UTF-8 encoding maximum number of keywords you can specify: 10 example: ["seo","software"] learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' mode: type: string description: 'search mode optional field possible search mode types: strict_entry – search for results exactly matching the order, intervals and separators in the specified search terms entry – search for results ignoring the order, intervals and separators in the specified search terms default value: entry' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["domain","like","%seo%"] [["country_iso_code","=","US"], "and", ["domain_rank",">",100]] [["domain_rank",">",100], "and", [["country_iso_code","=","US"],"or",["country_iso_code","=","CA"]]] for more information about filters, please refer to Domain Analytics Technologies API – Filters' order_by: type: array items: type: string description: 'results sorting rules optional field available fields: domain_rank, domain, last_visited, country_iso_code, language_code, content_language_code possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["last_visited,desc"] default rule: ["domain_rank,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["last_visited,desc","domain_rank,desc"]' limit: type: integer description: 'the maximum number of returned domains optional field default value: 100 maximum value: 10000' offset: type: integer description: 'offset in the results array of returned domains optional field default value: 0 if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains; Note: the maximum value is 9999, the sum of limit and offset must not exceed 10000; use the offset_token if you would like to offset more results' offset_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request learn more about this parameter on our Help Center' required: - search_terms tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/domains_by_html_terms/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/domains_by_technology/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0312 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domains by Technology description: 'Finds domains running a given technology - the reverse of `post_dataforseo_domains_tech_for_domain_live`. Accepts `technologies`, `technology_paths`, `groups`, `categories` and `keywords`, with `filters` and `order_by` over the fields named by `get_dataforseo_domains_tech_available_filters`. Returns `total_count`, `items_count`, `offset`, `offset_token` and `items`, each item the same profile as the per-domain call: `domain`, `title`, `description`, `meta_keywords`, `domain_rank`, `last_visited`, `country_iso_code`, `language_code`, `content_language_code`, `phone_numbers`, `emails`, `social_graph_urls` and `technologies`. Measured at 1.5 KB for one item, so cap it with `limit` - the item shape is heavy and `total_count` runs to millions for a popular platform. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status.' operationId: post_dataforseo_domains_tech_domains_by_technology_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.offset: type: integer description: specified offset value tasks.result.offset_token: type: string description: token for subsequent requests by specifying the unique offset_token when setting a new task, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task tasks.result.items: type: array items: type: string description: items array tasks.result.type: type: string description: type of the item = ‘domain_technology_item’ tasks.result.domain: type: string description: specified domain name tasks.result.title: type: string description: domain meta title tasks.result.description: type: string description: domain meta description tasks.result.meta_keywords: type: array items: type: string description: domain meta keywords tasks.result.domain_rank: type: string description: backlink rank of the target domain learn more about the metric and how it is calculated in this help center article tasks.result.last_visited: type: string description: 'most recent date when our crawler visited the domain in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2022-10-10 12:57:46 +00:00' tasks.result.country_iso_code: type: string description: domain ISO code ISO code of the country that target domain is determined to belong to tasks.result.language_code: type: string description: domain language code of the language that target domain is determined to be associated with tasks.result.content_language_code: type: string description: content language code of the language that content on the target domain is written with tasks.result.phone_numbers: type: array items: type: string description: phone numbers of the target contact phone numbers indicated on the target website tasks.result.emails: type: array items: type: string description: emails of the target emails indicated on the target website tasks.result.social_graph_urls: type: array items: type: string description: social media links and handles social media URLs detected in the social graphs of the target website tasks.result.technologies: type: object description: technologies used by target domain contains objects with the names of technologies used on the website; to get a full list of technologies and their structure, refer to the technologies endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: technology_paths: type: array items: type: object properties: path: type: string name: type: string required: - path - name description: 'target technology paths required field if you don’t specify groups, technologies, keywords or categories at least one field (technology_paths, groups, technologies, keywords or categories) must be set; each technology path should be specified as a separate object containing “path” and “name”, where “path” is specified as “$group_id.$category_id” and “name” – as the name of the target technology; each object with a technology path should be separated with a comma you can find the full list of technology group ids, category ids and technology names on this page note: you can specify up to 10 technology paths in this array example: [{"path": "content.cms","name": "wordpress"}, {"path": "marketing.crm","name": "salesforce"}]' groups: type: array items: type: string description: 'ids of the target technology groups required field if you don’t specify technologies, technology_paths, keywords or categories you can find the full list of technology group ids on this page note: you can specify up to 10 technology groups in this array example: ["sales", "marketing"]' categories: type: array items: type: string description: 'ids of the target technology categories required field if you don’t specify groups, technology_paths, keywords or technologies you can find the full list of technology category ids on this page note: you can specify up to 10 technology categories in this array example: ["payment_processors","crm"]' technologies: type: array items: type: string description: 'target technologies required field if you don’t specify groups, technology_paths, keywords or categories you can find the full list of technologies you can specify here on this page note: you can specify up to 10 technologies in this array example: ["Google Pay","Salesforce"]' keywords: type: array items: type: string description: 'target keywords in the domain’s title, description or meta keywords required field if you don’t specify groups, technology_paths, technologies or categories optional field you can specify the maximum of 10 keywords; UTF-8 encoding; example: ["seo","software"] learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' mode: type: string description: 'search mode optional field possible search mode types: as_is – search for results exactly matching the specified group ids, category ids, or technology names entry – search for results matching a part of the specified group ids, category ids, or technology names default value: as_is' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["country_iso_code","=","US"] [["country_iso_code","=","US"], "and", ["domain_rank",">",100]] [["domain_rank",">",100], "and", [["country_iso_code","=","US"],"or",["country_iso_code","=","CA"]]] for more information about filters, please refer to Domain Analytics Technologies API – Filters' order_by: type: array items: type: string description: 'results sorting rules optional field available fields: domain_rank, domain, last_visited, country_iso_code, language_code, content_language_code possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["last_visited,desc"] default rule: ["domain_rank,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["last_visited,desc","domain_rank,desc"]' limit: type: integer description: 'the maximum number of returned domains optional field default value: 100 maximum value: 10000' offset: type: integer description: 'offset in the results array of returned domains optional field default value: 0 if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains; Note: the maximum value is 9999, the sum of limit and offset must not exceed 10000; use the offset_token if you would like to offset more results' offset_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request learn more about this parameter on our Help Center' allOf: - anyOf: - required: - technology_paths - required: - groups - required: - categories - required: - technologies - required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/domains_by_technology/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/available_filters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Filters for Domain Analytics Technologies API description: 'The filterable fields for each technology endpoint, keyed by endpoint: `domains_by_technology`, `aggregation_technologies`, `technologies_summary` and `domains_by_html_terms`. The first three share `domain_rank`, `last_visited`, `country_iso_code`, `language_code` and `content_language_code`; `domains_by_html_terms` adds `domain`. Measured at 2.1 KB. Free: upstream cost is 0. Read it before building a `filters` argument - an unknown field is rejected, not ignored. The whois equivalent is `get_dataforseo_domains_whois_available_filters`.' operationId: get_dataforseo_domains_tech_available_filters responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results contains the full list of available parameters that can be used for data filtration the parameters are grouped by the endpoint they can be used with '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/available_filters source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Languages for Domain Analytics Technologies API description: 'The languages the technology endpoints accept, as `language_name` and `language_code`. 127 rows, measured at 6.8 KB. Free: upstream cost is 0. Reference data - fetch once and reuse. Note this is not the same catalogue as the content family''s 71 languages, so a code valid there is not guaranteed here. The location equivalent is `get_dataforseo_domains_tech_locations`.' operationId: get_dataforseo_domains_tech_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations for Domain Analytics Technologies API description: 'The locations the technology endpoints accept, as `location_name` and `country_iso_code`. 217 rows, measured at 29.6 KB - larger than it looks for reference data, so fetch once and reuse rather than calling it per request. Free: upstream cost is 0. Note this list is not the same length as the content family''s 235 locations; the two are separate catalogues and a name valid in one is not guaranteed in the other. The language equivalent is `get_dataforseo_domains_tech_languages`.' operationId: get_dataforseo_domains_tech_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_name: type: string description: full name of the location tasks.result.country_iso_code: type: string description: ISO country code of the location '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/technologies: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Technologies for Domain Analytics Technologies API description: 'The full technology taxonomy as a tree: `groups`, each with `id`, `title` and `categories`, and each category with its technologies. These are the values `groups`, `categories` and `technologies` accept on the search endpoints. 🔴 **Measured at 130 KB, and it takes no limit or filter parameter** - by far the largest response here and a serious bite out of an agent''s context. Fetch it once and keep the branch you need. Free: upstream cost is 0.' operationId: get_dataforseo_domains_tech_list responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.groups: type: array items: type: string description: array of technology groups tasks.result.groups.id: type: string description: 'id of the technology group example: marketing, sales' tasks.result.groups.title: type: string description: title of the technology group tasks.result.groups.categories: type: array items: type: string description: technology categories in this group tasks.result.groups.categories.id: type: string description: 'id of the technology category example: crm, cart_abandonment' tasks.result.groups.categories.path: type: string description: 'path to the technology category example: user_generated_content.content_curation' tasks.result.groups.categories.title: type: string description: title of the technology category tasks.result.groups.categories.technologies: type: array items: type: string description: 'list of technologies in this category example: "Salesforce", "CareCart"' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/technologies source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/technologies_summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0264 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Technologies Summary description: 'Where a technology is used, rather than by whom: returns `countries`, `languages`, `content_languages` and `keywords` for the technology set you name. Measured at 1.4 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status. Use it to size a market before pulling domain lists. For counts broken down by group and category use `post_dataforseo_domains_tech_aggregation_live`; for adoption over time, `post_dataforseo_domains_tech_technology_stats_live`.' operationId: post_dataforseo_domains_tech_summary_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.countries: type: object description: distribution of websites by country contains country codes and number of websites per country tasks.result.languages: type: object description: distribution of websites by language contains language codes and number of websites per language tasks.result.content_languages: type: object description: distribution of websites by content language contains content language codes and number of websites per language tasks.result.keywords: type: object description: distribution of websites by keywords contains keywords found in the websites’ titles, descriptions or meta keywords, and number of websites using each keyword '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: technology_paths: type: array items: type: object properties: path: type: string name: type: string required: - path - name description: 'target technology paths required field if you don’t specify groups, technologies and categories each technology path should be specified as a separate object containing “path” and “name”, where “path” is specified as “$group_id.$category_id” and “name” – as the name of the target technology; each object with a technology path should be separated with a comma you can find the full list of technology group ids, category ids and technology names on this page note: you can specify up to 10 technology paths in this array example: [{"path": "content.cms","name": "wordpress"}, {"path": "marketing.crm","name": "salesforce"}]' groups: type: array items: type: string description: 'ids of the target technology groups required field if you don’t specify technologies, technology_paths, categories, or keywords you can find the full list of technology group ids on this page note: you can specify up to 10 technology groups in this array example: ["sales", "marketing"]' categories: type: array items: type: string description: 'ids of the target technology categories required field if you don’t specify groups, technology_paths, technologies, or keywords you can find the full list of technology category ids on this page note: you can specify up to 10 technology categories in this array example: ["payment_processors","crm"]' technologies: type: array items: type: string description: 'target technologies required field if you don’t specify groups, technology_paths, categories, or keywords you can find the full list of technologies you can specify here on this page note: you can specify up to 10 technologies in this array example: ["Google Pay","Salesforce"]' keywords: type: array items: type: string description: 'target keywords in the domain’s title, description or meta keywords required field if you don’t specify groups, technology_paths, categories, or technologies you can specify the maximum of 10 keywords; UTF-8 encoding; example: ["seo","software"] learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' mode: type: string description: 'search mode optional field possible search mode types: as_is – search for results exactly matching the specified group ids, category ids, or technology names entry – search for results matching a part of the specified group ids, category ids, or technology names default value: as_is' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in, like,not_like you can use the % operator with like and not_like to match any string of zero or more characters you can use the following parameters to filter the results: domain_rank, last_visited, country_iso_code, language_code, content_language_code example: [["country_iso_code","=","US"], "and", ["domain_rank",">",800]] for more information about filters, please refer to Domain Analytics Technologies API – Filters' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: countries, languages, content_languages, keywords default value: 10 minimum value: 1 maximum value: 10000' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response allOf: - anyOf: - required: - technology_paths - required: - groups - required: - categories - required: - technologies - required: - keywords tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/technologies_summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/technologies/technology_stats/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0264 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Technology Stats description: 'Adoption of one `technology` over time. Returns `technology`, `date_from`, `date_to`, `items_count` and `items`. ⚠️ **`date_from` and `date_to` must both be present or both absent** - sending only `date_from` is rejected with `status_code` 40501, `Invalid Field: ''date_from''`, inside an HTTP 200. Omit both to get the default window. Measured at 516 bytes. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status. For a single point in time use `post_dataforseo_domains_tech_summary_live`.' operationId: post_dataforseo_domains_tech_technology_stats_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.technology: type: string description: target technology tasks.result.date_from: type: string description: starting date of the time range tasks.result.date_to: type: string description: ending date of the time range tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of the item = ‘technology_stats_item’ tasks.result.items.date: type: string description: date for which the data is provided tasks.result.items.domains_count: type: integer description: number of domains that use the specified technology tasks.result.items.countries: type: object description: distribution of websites by country contains country codes and number of websites per country tasks.result.items.languages: type: object description: distribution of websites by language contains language codes and number of websites per language tasks.result.items.domains_rank: type: object description: distribution of websites by backlink rank contains domain rank ranges and number of websites per range learn more about rank and how it is calculated in this help center article '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: technology: type: string description: 'target technology required field you can find the full list of technologies you can specify here on this page example: "Salesforce"' date_from: type: string description: 'starting date of the time range optional field minimum value: 2022-10-31 if you don’t specify this field, the minimum value will be used by default date format: "yyyy-mm-dd" example: "2023-06-01"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2023-01-15"' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - technology tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/technologies/technology_stats/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/whois/available_filters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Filters for Domain Analytics Whois API description: 'The filterable fields for `post_dataforseo_domains_whois_overview_live`, under an `overview` key: `domain`, `created_datetime`, `changed_datetime`, `expiration_datetime`, `updated_datetime`, `first_seen`, `epp_status_codes`, `tld`, `registered` and `registrar`, alongside the nested metrics fields. Measured at 1.9 KB. Free: upstream cost is 0. Worth reading first here more than anywhere else in this family, because the endpoint it filters is the expensive one. The technology equivalent is `get_dataforseo_domains_tech_available_filters`.' operationId: get_dataforseo_domains_whois_available_filters responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results contains the full list of available parameters that can be used for data filtration the parameters are grouped by the endpoint they can be used with '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/whois/available_filters source: https://github.com/AIsa-team/aisa-proxy /dataforseo/domain_analytics/whois/overview/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.2952 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Whois Overview description: 'Whois records enriched with SEO metrics. Each item carries `domain`, `created_datetime`, `changed_datetime`, `expiration_datetime`, `updated_datetime`, `first_seen`, `epp_status_codes`, `tld`, `registered`, `registrar`, plus `metrics` and `backlinks_info`. Paged with `limit`, `offset` and `offset_token`, filtered over the fields in `get_dataforseo_domains_whois_available_filters`. Measured at 2.5 KB for one item. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, and the real outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200, so check that field rather than the transport status. 🔴 **The most expensive endpoint in this family by an order of magnitude: measured at $0.1212 upstream for a single record.** Filter hard and keep `limit` low; do not call it in a loop over a domain list.' operationId: post_dataforseo_domains_whois_overview_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.offset: type: integer description: results offset value specified in POST request tasks.result.offset_token: type: object description: token for subsequent requests by specifying the unique offset_token when setting a new task, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task tasks.result.items: type: array items: type: string description: contains ranking and traffic data tasks.result.items.domain: type: string description: domain name tasks.result.items.created_datetime: type: string description: 'date and time of registration date and time (in the ISO 8601 format) when the domain was first registered example: "1997-03-29 03:00:00 +00:00"' tasks.result.items.changed_datetime: type: string description: 'date and time when the domain entry was changed date and time (in the ISO 8601 format) when the domain entry was last modified example: "2021-01-14 08:36:28 +00:00"' tasks.result.items.expiration_datetime: type: string description: 'date and time when the domain will expire date and time (in the ISO 8601 format) when the domain is due to expire example: "2022-11-26 17:21:23 +00:00"' tasks.result.items.updated_datetime: type: string description: 'date and time when the domain was updated date and time (in the ISO 8601 format) when the domain was last updated example: "2021-01-29 13:59:38 +00:00"' tasks.result.items.first_seen: type: string description: 'date and time when our crawler found the domain for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: "2019-11-15 12:57:46 +00:00"' tasks.result.items.epp_status_codes: type: array items: type: string description: extensive provisioning protocol status codes the status of a domain name registration as defined by ICANN tasks.result.items.tld: type: string description: top-level domain top-level domain in the DNS root zone tasks.result.items.registered: type: boolean description: 'domain registration status if false, the domain name registration has expired Note: expired domains will remain in the database for only a short period of time' tasks.result.items.registrar: type: string description: 'domain registrar if null, the domain registrar is unknown example: NameCheap, Inc.' tasks.result.items.metrics: type: object description: ranking data relevant to the specified domain tasks.result.items.metrics.organic: type: object description: ranking and traffic data from organic search tasks.result.items.metrics.organic.pos_1: type: integer description: 'number of organic SERPs where the domain ranks #1' tasks.result.items.metrics.organic.pos_2_3: type: integer description: 'number of organic SERPs where the domain ranks #2-3' tasks.result.items.metrics.organic.pos_4_10: type: integer description: 'number of organic SERPs where the domain ranks #4-10' tasks.result.items.metrics.organic.pos_11_20: type: integer description: 'number of organic SERPs where the domain ranks #11-20' tasks.result.items.metrics.organic.pos_21_30: type: integer description: 'number of organic SERPs where the domain ranks #21-30' tasks.result.items.metrics.organic.pos_31_40: type: integer description: 'number of organic SERPs where the domain ranks #31-40' tasks.result.items.metrics.organic.pos_41_50: type: integer description: 'number of organic SERPs where the domain ranks #41-50' tasks.result.items.metrics.organic.pos_51_60: type: integer description: 'number of organic SERPs where the domain ranks #51-60' tasks.result.items.metrics.organic.pos_61_70: type: integer description: 'number of organic SERPs where the domain ranks #61-70' tasks.result.items.metrics.organic.pos_71_80: type: integer description: 'number of organic SERPs where the domain ranks #71-80' tasks.result.items.metrics.organic.pos_81_90: type: integer description: 'number of organic SERPs where the domain ranks #81-90' tasks.result.items.metrics.organic.pos_91_100: type: integer description: 'number of organic SERPs where the domain ranks #91-100' tasks.result.items.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.count: type: integer description: total count of organic SERPs that contain the domain tasks.result.items.metrics.organic.estimated_paid_traffic_cost: type: number description: estimated cost of converting organic search traffic into paid represents the estimated monthly cost of running ads (USD) for all keywords a domain ranks for the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid: type: object description: ranking and traffic data from paid search tasks.result.items.metrics.paid.pos_1: type: integer description: 'number of paid SERPs where the domain ranks #1' tasks.result.items.metrics.paid.pos_2_3: type: integer description: 'number of paid SERPs where the domain ranks #2-3' tasks.result.items.metrics.paid.pos_4_10: type: integer description: 'number of paid SERPs where the domain ranks #4-10' tasks.result.items.metrics.paid.pos_11_20: type: integer description: 'number of paid SERPs where the domain ranks #11-20' tasks.result.items.metrics.paid.pos_21_30: type: integer description: 'number of paid SERPs where the domain ranks #21-30' tasks.result.items.metrics.paid.pos_31_40: type: integer description: 'number of paid SERPs where the domain ranks #31-40' tasks.result.items.metrics.paid.pos_41_50: type: integer description: 'number of paid SERPs where the domain ranks #41-50' tasks.result.items.metrics.paid.pos_51_60: type: integer description: 'number of paid SERPs where the domain ranks #51-60' tasks.result.items.metrics.paid.pos_61_70: type: integer description: 'number of paid SERPs where the domain ranks #61-70' tasks.result.items.metrics.paid.pos_71_80: type: integer description: 'number of paid SERPs where the domain ranks #71-80' tasks.result.items.metrics.paid.pos_81_90: type: integer description: 'number of paid SERPs where the domain ranks #81-90' tasks.result.items.metrics.paid.pos_91_100: type: integer description: 'number of paid SERPs where the domain ranks #91-100' tasks.result.items.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.count: type: integer description: total count of paid SERPs that contain the domain tasks.result.items.metrics.paid.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values learn more about how the metric is calculated in this help center article tasks.result.items.backlinks_info: type: object description: backlink data for the returned domain tasks.result.items.backlinks_info.referring_domains: type: integer description: number of referring domains tasks.result.items.backlinks_info.referring_main_domains: type: integer description: number of referring main domains tasks.result.items.backlinks_info.referring_pages: type: integer description: number of referring pages tasks.result.items.backlinks_info.dofollow: type: integer description: number of dofollow links tasks.result.items.backlinks_info.backlinks: type: integer description: total number of backlinks the total number of backlinks, including dofollow and nofollow links tasks.result.items.backlinks_info.time_update: type: string description: 'date and time when backlink data was updated in the UTC format: "yyyy-mm-dd hh-mm-ss +00:00" example: 2019-11-15 12:57:46 +00:00' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: limit: type: integer description: 'the maximum number of returned domains optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned items optional field default value: 0 if you specify the 10 value, the first ten items in the results array will be omitted and the data will be provided for the successive items; Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead' offset_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request learn more about this parameter on our Help Center' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc - results will be sorted in the ascending order desc - results will be sorted in the descending order the comma is used as a separator example: ["metrics.organic.pos_1,desc"] default rule: ["metrics.organic.count,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["expiration_datetime,asc","metrics.organic.etv,desc","metrics.organic.pos_1,desc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/domain_analytics/whois/overview/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/amazon/bulk_search_volume/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02424 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Amazon Bulk Search Volume description: 'Amazon search volume for many keywords in one call. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Price is per call, so send the whole list. The Google-side volume endpoint is `post_dataforseo_labs_google_keyword_overview_live`, and the two measure different marketplaces entirely.' operationId: post_dataforseo_labs_amazon_bulk_volume_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keyword search volume data data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: keyword in a POST array tasks.result.items.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the returned keyword on Amazon '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000; the keywords will be converted to lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if don’t specify location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the following locations and languages only: Australia – 2036, en Austria – 2040, de Canada – 2124, en Egypt – 2818, ar France – 2250, fr Germany – 2276, de India – 2356, en Italy – 2380, it Mexico – 2484, es Netherlands – 2528, nl Saudi Arabia – 2682, ar Singapore – 2702, en Spain – 2724, es United Arab Emirates – 2784, ar United Kingdom – 2826, en United States – 2840, en example: United States' location_code: type: integer description: 'location code required field if don’t specify location_name you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports these locations and languages only; example: 2840' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages Note: this endpoint currently supports these locations and languages only; example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages Note: this endpoint currently supports these locations and languages only; example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/amazon/bulk_search_volume/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/amazon/product_competitors/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Product Competitors description: 'Amazon products competing with a given product on shared search terms. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For the shared terms themselves use `post_dataforseo_labs_amazon_product_kw_overlap_live`.' operationId: post_dataforseo_labs_amazon_product_competitors_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.asin: type: string description: ASIN in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains detected Amazon product competitors and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.asin: type: string description: ASIN of the product unique product identifier on Amazon; for more information, refer to this help center guide tasks.result.items.avg_position: type: number description: 'average position of the product in Amazon SERP Note: average position is calculated for intersected keywords only; the value for a given product may differ when combined with different target products' tasks.result.items.sum_position: type: integer description: 'sum of all product positions in Amazon SERP Note: average position is calculated for intersected keywords only; the value for a given product may differ when combined with different target products' tasks.result.items.intersections: type: integer description: number of intersecting keywords tasks.result.items.competitor_metrics: type: object description: 'metrics for intersecting keywords ranking data relevant to the keywords that the provided asin shares with the target asin; Note: in this object ranking data is provided for the returned competitor’s asin' tasks.result.items.competitor_metrics.amazon_serp: type: object description: ranking data from Amazon organic SERP tasks.result.items.competitor_metrics.amazon_serp.pos_1: type: integer description: 'number of organic SERPs where the product ranks #1' tasks.result.items.competitor_metrics.amazon_serp.pos_2_3: type: integer description: 'number of organic SERPs where the product ranks #2-3' tasks.result.items.competitor_metrics.amazon_serp.pos_4_10: type: integer description: 'number of organic SERPs where the product ranks #4-10' tasks.result.items.competitor_metrics.amazon_serp.pos_11_100: type: integer description: 'number of organic SERPs where the product ranks #11-100' tasks.result.items.competitor_metrics.amazon_serp.count: type: integer description: total count of Amazon organic SERPs that contain the product tasks.result.items.competitor_metrics.amazon_serp.search_volume: type: integer description: total search volume of the product’s ranking keywords in organic SERP tasks.result.items.competitor_metrics.amazon_paid: type: object description: ranking data from Amazon paid SERP tasks.result.items.competitor_metrics.amazon_paid.pos_1: type: integer description: 'number of paid SERPs where the product ranks #1' tasks.result.items.competitor_metrics.amazon_paid.pos_2_3: type: integer description: 'number of paid SERPs where the product ranks #2-3' tasks.result.items.competitor_metrics.amazon_paid.pos_4_10: type: integer description: 'number of paid SERPs where the product ranks #4-10' tasks.result.items.competitor_metrics.amazon_paid.pos_11_100: type: integer description: 'number of paid SERPs where the product ranks #11-100' tasks.result.items.competitor_metrics.amazon_paid.count: type: integer description: total count of Amazon paid SERPs that contain the product tasks.result.items.competitor_metrics.amazon_paid.search_volume: type: integer description: total search volume of the product’s ranking keywords in paid SERP tasks.result.items.full_metrics: type: object description: metrics for all keywords of the product full overview of ranking data relevant to all keywords that the provided asin is ranking for tasks.result.items.full_metrics.amazon_serp: type: object description: ranking data from Amazon organic SERP tasks.result.items.full_metrics.amazon_serp.pos_1: type: integer description: 'number of organic SERPs where the product ranks #1' tasks.result.items.full_metrics.amazon_serp.pos_2_3: type: integer description: 'number of organic SERPs where the product ranks #2-3' tasks.result.items.full_metrics.amazon_serp.pos_4_10: type: integer description: 'number of organic SERPs where the product ranks #4-10' tasks.result.items.full_metrics.amazon_serp.pos_11_100: type: integer description: 'number of organic SERPs where the product ranks #11-100' tasks.result.items.full_metrics.amazon_serp.count: type: integer description: total count of Amazon organic SERPs that contain the product tasks.result.items.full_metrics.amazon_serp.search_volume: type: integer description: total search volume of the product’s ranking keywords in organic SERP tasks.result.items.full_metrics.amazon_paid: type: object description: ranking data from Amazon paid SERP tasks.result.items.full_metrics.amazon_paid.pos_1: type: integer description: 'number of paid SERPs where the product ranks #1' tasks.result.items.full_metrics.amazon_paid.pos_2_3: type: integer description: 'number of paid SERPs where the product ranks #2-3' tasks.result.items.full_metrics.amazon_paid.pos_4_10: type: integer description: 'number of paid SERPs where the product ranks #4-10' tasks.result.items.full_metrics.amazon_paid.pos_11_100: type: integer description: 'number of paid SERPs where the product ranks #11-100' tasks.result.items.full_metrics.amazon_paid.count: type: integer description: total count of Amazon paid SERPs that contain the product tasks.result.items.full_metrics.amazon_paid.search_volume: type: integer description: total search volume of the product’s ranking keywords in paid SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: asin: type: string description: product ID required field unique product identifier (ASIN) on Amazon; you can receive the asin parameter by making a separate request to the Amazon Products endpoint location_name: type: string description: 'full name of the location required field if don’t specify location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: United States' location_code: type: integer description: 'location code required field if don’t specify location_name you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: 2840' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' limit: type: integer description: 'the maximum number of products in the results array optional field default value: 100; maximum value: 1000' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, ilike, not_ilike, like, not_like, match, not_match you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters example: ["full_metrics.amazon_serp.pos_1",">", 20] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["full_metrics.amazon_serp.pos_1,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["full_metrics.amazon_serp.pos_1,desc","avg_position,desc"] default rule: ["ranked_serp_element.serp_item.rank_group,asc"]' offset: type: integer description: 'offset in the results array of returned product competitors optional field default value: 0 if you specify the 10 value, the first ten product competitors in the results array will be omitted and the data will be provided for the successive product competitors' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - asin allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/amazon/product_competitors/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/amazon/product_keyword_intersections/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keyword Intersections description: 'The Amazon search terms two or more products both rank for. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Where `post_dataforseo_labs_amazon_product_competitors_live` names the rivals, this names the terms they contest.' operationId: post_dataforseo_labs_amazon_product_kw_overlap_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.asins: type: object description: ASINs in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains detected Amazon product competitors and related data tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: returned keyword tasks.result.items.keyword_data.location_code: type: integer description: location in a POST array tasks.result.items.keyword_data.language_code: type: string description: language in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the returned keyword on Amazon tasks.result.items.intersection_result: type: object description: data on the intersection tasks.result.items.intersection_result.$asin_number: type: object description: intersection data for one of the ASINs in a POST request tasks.result.items.intersection_result.$asin_number.se_type: type: string description: search engine type tasks.result.items.intersection_result.$asin_number.type: type: string description: type of element = ‘amazon_serp’ tasks.result.items.intersection_result.$asin_number.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.intersection_result.$asin_number.rank_absolute: type: integer description: absolute rank in Amazon SERP absolute position among all the elements in SERP tasks.result.items.intersection_result.$asin_number.position: type: string description: 'the alignment of the element in Amazon SERP can take the following values: left, right' tasks.result.items.intersection_result.$asin_number.xpath: type: string description: the XPath of the element tasks.result.items.intersection_result.$asin_number.domain: type: string description: Amazon domain tasks.result.items.intersection_result.$asin_number.title: type: string description: product title tasks.result.items.intersection_result.$asin_number.url: type: string description: URL of the product page tasks.result.items.intersection_result.$asin_number.description: type: string description: description of the product tasks.result.items.intersection_result.$asin_number.asin: type: string description: ASIN of the product learn more about ASIN in this help center guide tasks.result.items.intersection_result.$asin_number.image_url: type: string description: URL of the product image featured in the results tasks.result.items.intersection_result.$asin_number.price_from: type: number description: 'the regular price of a product example: 49.98' tasks.result.items.intersection_result.$asin_number.price_to: type: number description: 'the upper limit of the product price range example: 384.99' tasks.result.items.intersection_result.$asin_number.currency: type: string description: 'currency in the ISO format example: USD' tasks.result.items.intersection_result.$asin_number.special_offers: type: array items: type: string description: special offer details contains special offer details, including coupon and Subscribe & Save discounts tasks.result.items.intersection_result.$asin_number.is_best_seller: type: boolean description: “Best Seller” label if the value is true, the product is marked with the “Best Seller” label tasks.result.items.intersection_result.$asin_number.is_amazon_choice: type: boolean description: “Amazon’s choice” label if the value is true, the product is marked with the “Amazon’s choice” label tasks.result.items.intersection_result.$asin_number.rating: type: object description: the item’s rating the popularity rate based on reviews and displayed in SERP tasks.result.items.intersection_result.$asin_number.rating.rating_type: type: string description: 'the type of rating here you can find the following elements: Max5, Percents, CustomMax' tasks.result.items.intersection_result.$asin_number.rating.value: type: integer description: the value of the rating tasks.result.items.intersection_result.$asin_number.rating.votes_count: type: integer description: the amount of feedback tasks.result.items.intersection_result.$asin_number.rating.rating_max: type: integer description: the maximum value for a rating_type tasks.result.items.intersection_result.$asin_number.delivery_info: type: object description: delivery information delivery information including free and fast delivery date ranges tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_message: type: string description: delivery information message accompanying the delivery information as posted by the seller tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price: type: object description: price for the delivery price of the delivery based on the location you specified in the POST request; if free delivery is available, the value is null tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price.current: type: number description: current delivery price tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price.regular: type: number description: regular undiscounted delivery price tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price.max_value: type: number description: maximum undiscounted delivery price tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price.currency: type: string description: currency in the ISO format tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price.is_price_range: type: boolean description: indicates whether the delivery price is a range tasks.result.items.intersection_result.$asin_number.delivery_info.delivery_price.displayed_price: type: string description: price line provided as displayed in Amazon listing '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: asins: type: object description: 'asins of target products required field product IDs of the products for which you need to find keyword intersections; specify the ASINs as in the following example: "asins": { "1": "019005476X", "2": "0190074442" } the maximum number of ASINs you can specify in this object is 20; learn more about the parameter on this help center page' additionalProperties: type: string location_name: type: string description: 'full name of the location required field if don’t specify location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: United Kingdom' location_code: type: integer description: 'location code required field if don’t specify location_name you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: 2840' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' limit: type: integer description: 'the maximum number of products in the results array optional field default value: 100; maximum value: 1000' intersection_mode: type: string description: 'mode for finding asin intersections optional field possible values: union, intersect; default value: intersect; learn more about the parameter in this help center guide' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, ilike, not_ilike, like, not_like, match, not_match you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters example: ["avg_position"," for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["sum_position,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["intersections,desc","avg_position,asc"] default rule: ["intersections,desc"]' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - asins allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/amazon/product_keyword_intersections/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/amazon/product_rank_overview/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02448 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Product Rank Overview description: 'Where a set of Amazon products rank overall - the product-level equivalent of a domain rank overview. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For the keywords behind those rankings use `post_dataforseo_labs_amazon_ranked_keywords_live`.' operationId: post_dataforseo_labs_amazon_product_rank_overview_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains detected Amazon product competitors and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.asin: type: string description: ASIN of the product unique product identifier on Amazon; for more information, refer to this help center guide tasks.result.items.metrics: type: object description: average keyword position of the product tasks.result.items.metrics.amazon_serp: type: object description: ranking data from Amazon organic SERP tasks.result.items.metrics.amazon_serp.pos_1: type: integer description: 'number of organic SERPs where the product ranks #1' tasks.result.items.metrics.amazon_serp.pos_2_3: type: integer description: 'number of organic SERPs where the product ranks #2-3' tasks.result.items.metrics.amazon_serp.pos_4_10: type: integer description: 'number of organic SERPs where the product ranks #4-10' tasks.result.items.metrics.amazon_serp.pos_11_100: type: integer description: 'number of organic SERPs where the product ranks #11-100' tasks.result.items.metrics.amazon_serp.count: type: integer description: total count of Amazon organic SERPs that contain the product tasks.result.items.metrics.amazon_serp.search_volume: type: integer description: total search volume of the product’s ranking keywords in organic SERP tasks.result.items.metrics.amazon_paid: type: object description: ranking data from Amazon paid SERP tasks.result.items.metrics.amazon_paid.pos_1: type: integer description: 'number of paid SERPs where the product ranks #1' tasks.result.items.metrics.amazon_paid.pos_2_3: type: integer description: 'number of paid SERPs where the product ranks #2-3' tasks.result.items.metrics.amazon_paid.pos_4_10: type: integer description: 'number of paid SERPs where the product ranks #4-10' tasks.result.items.metrics.amazon_paid.pos_11_100: type: integer description: 'number of paid SERPs where the product ranks #11-100' tasks.result.items.metrics.amazon_paid.count: type: integer description: total count of Amazon paid SERPs that contain the product tasks.result.items.metrics.amazon_paid.search_volume: type: integer description: total search volume of the product’s ranking keywords in paid SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: asins: type: array items: type: string description: 'product IDs to compare required field product IDs to receive ranking data for; the maximum number of ASINs you can specify in this array is 1000; you can receive the asin parameter by making a separate request to the Amazon Products endpoint Note: all letters in ASIN code must be specified in uppercase format; example: B01LW2SL7R' location_name: type: string description: 'full name of the location required field if don’t specify location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: United States' location_code: type: integer description: 'location code required field if don’t specify location_name you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: 2840' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - asins allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/amazon/product_rank_overview/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/amazon/ranked_keywords/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Ranked Keywords description: 'The Amazon search terms a product ranks for. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is Labs'' own Amazon index, so it pages and answers immediately - unlike `seo-merchant`, which queues a live scrape of the store.' operationId: post_dataforseo_labs_amazon_ranked_keywords_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.asin: type: string description: ASIN in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains detected Amazon product competitors and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: returned keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword info for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the returned keyword on Amazon tasks.result.items.ranked_serp_element: type: object description: contains data on the products’s SERP element found for the returned keyword tasks.result.items.ranked_serp_element.se_type: type: string description: search engine type tasks.result.items.ranked_serp_element.serp_item: type: object description: contains data on the SERP element the list of supported SERP elements can be found below tasks.result.items.ranked_serp_element.serp_item.se_type: type: string description: search engine type tasks.result.items.ranked_serp_element.serp_item.type: type: string description: type of element = ‘amazon_serp’ tasks.result.items.ranked_serp_element.serp_item.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.ranked_serp_element.serp_item.rank_absolute: type: integer description: absolute rank in Amazon SERP absolute position among all the elements in SERP tasks.result.items.ranked_serp_element.serp_item.position: type: string description: 'the alignment of the element in Amazon SERP can take the following values: left, right' tasks.result.items.ranked_serp_element.serp_item.xpath: type: string description: the XPath of the element tasks.result.items.ranked_serp_element.serp_item.domain: type: string description: Amazon domain tasks.result.items.ranked_serp_element.serp_item.title: type: string description: product title tasks.result.items.ranked_serp_element.serp_item.url: type: string description: URL of the product page tasks.result.items.ranked_serp_element.serp_item.description: type: string description: description of the product tasks.result.items.ranked_serp_element.serp_item.asin: type: string description: ASIN of the product learn more about ASIN in this help center guide tasks.result.items.ranked_serp_element.serp_item.image_url: type: string description: URL of the product image featured in the results tasks.result.items.ranked_serp_element.serp_item.price_from: type: number description: 'the regular price of a product example: 49.98' tasks.result.items.ranked_serp_element.serp_item.price_to: type: number description: 'the upper limit of the product price range example: 384.99' tasks.result.items.ranked_serp_element.serp_item.currency: type: string description: 'currency in the ISO format example: USD' tasks.result.items.ranked_serp_element.serp_item.special_offers: type: array items: type: string description: special offer details contains special offer details, including coupon and Subscribe & Save discounts tasks.result.items.ranked_serp_element.serp_item.is_best_seller: type: boolean description: “Best Seller” label if the value is true, the product is marked with the “Best Seller” label tasks.result.items.ranked_serp_element.serp_item.is_amazon_choice: type: boolean description: “Amazon’s choice” label if the value is true, the product is marked with the “Amazon’s choice” label tasks.result.items.ranked_serp_element.serp_item.rating: type: object description: the item’s rating the popularity rate based on reviews and displayed in SERP tasks.result.items.ranked_serp_element.serp_item.rating.rating_type: type: string description: 'the type of rating here you can find the following elements: Max5, Percents, CustomMax' tasks.result.items.ranked_serp_element.serp_item.rating.value: type: integer description: the value of the rating tasks.result.items.ranked_serp_element.serp_item.rating.votes_count: type: integer description: the amount of feedback tasks.result.items.ranked_serp_element.serp_item.rating.rating_max: type: integer description: the maximum value for a rating_type tasks.result.items.ranked_serp_element.serp_item.delivery_info: type: object description: delivery information delivery information including free and fast delivery date ranges tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_message: type: string description: delivery information message accompanying the delivery information as posted by the seller tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price: type: object description: price for the delivery price of the delivery based on the location you specified in the POST request; if free delivery is available, the value is null tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price.current: type: number description: current delivery price tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price.regular: type: number description: regular undiscounted delivery price tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price.max_value: type: number description: maximum undiscounted delivery price tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price.currency: type: string description: currency in the ISO format tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price.is_price_range: type: boolean description: indicates whether the delivery price is a range tasks.result.items.ranked_serp_element.serp_item.delivery_info.delivery_price.displayed_price: type: string description: price line provided as displayed in Amazon listing tasks.result.items.ranked_serp_element.check_url: type: string description: direct URL to Amazon results you can use it to make sure that we provided accurate results tasks.result.items.ranked_serp_element.serp_item_types: type: array items: type: string description: 'direct URL to Amazon results contains types of all search results (items) found in the returned SERP; possible item types: amazon_serp, amazon_paid, editorial_recommendations, top_rated_from_our_brands, related_searches' tasks.result.items.ranked_serp_element.se_results_count: type: integer description: total number of results in Amazon SERP tasks.result.items.ranked_serp_element.last_updated_time: type: string description: 'date and time when SERP data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.ranked_serp_element.previous_updated_time: type: string description: 'previous to the most recent update of SERP data in the ISO 8601 format: “YYYY-MM-DDThh:mm:ss.sssssssZ” example: 2020-09-12T00:07:43.0733218Z' tasks.result.items.ranked_serp_element.previous_updated_time.se_type: type: string description: search engine type tasks.result.items.ranked_serp_element.previous_updated_time.type: type: string description: type of element = ‘related_searches’ tasks.result.items.ranked_serp_element.previous_updated_time.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.ranked_serp_element.previous_updated_time.rank_absolute: type: integer description: absolute rank in Amazon SERP absolute position among all the elements in SERP tasks.result.items.ranked_serp_element.previous_updated_time.position: type: string description: 'the alignment of the element in Amazon SERP can take the following values: left, right' tasks.result.items.ranked_serp_element.previous_updated_time.xpath: type: string description: the XPath of the element tasks.result.items.ranked_serp_element.previous_updated_time.domain: type: string description: Amazon domain tasks.result.items.ranked_serp_element.previous_updated_time.title: type: string description: product title tasks.result.items.ranked_serp_element.previous_updated_time.url: type: string description: URL of the product page tasks.result.items.ranked_serp_element.previous_updated_time.description: type: string description: description of the product tasks.result.items.ranked_serp_element.previous_updated_time.asin: type: string description: ASIN of the product learn more about ASIN in this help center guide tasks.result.items.ranked_serp_element.previous_updated_time.image_url: type: string description: URL of the product image featured in the results tasks.result.items.ranked_serp_element.previous_updated_time.price_from: type: number description: 'the regular price of a product example: 49.98' tasks.result.items.ranked_serp_element.previous_updated_time.price_to: type: number description: 'the upper limit of the product price range example: 384.99' tasks.result.items.ranked_serp_element.previous_updated_time.currency: type: string description: 'currency in the ISO format example: USD' tasks.result.items.ranked_serp_element.previous_updated_time.special_offers: type: array items: type: string description: special offer details contains special offer details, including coupon and Subscribe & Save discounts tasks.result.items.ranked_serp_element.previous_updated_time.is_best_seller: type: boolean description: “Best Seller” label if the value is true, the product is marked with the “Best Seller” label tasks.result.items.ranked_serp_element.previous_updated_time.is_amazon_choice: type: boolean description: “Amazon’s choice” label if the value is true, the product is marked with the “Amazon’s choice” label tasks.result.items.ranked_serp_element.previous_updated_time.rating: type: object description: the item’s rating the popularity rate based on reviews and displayed in SERP tasks.result.items.ranked_serp_element.previous_updated_time.rating.rating_type: type: string description: 'the type of rating here you can find the following elements: Max5, Percents, CustomMax' tasks.result.items.ranked_serp_element.previous_updated_time.rating.value: type: integer description: the value of the rating tasks.result.items.ranked_serp_element.previous_updated_time.rating.votes_count: type: integer description: the amount of feedback tasks.result.items.ranked_serp_element.previous_updated_time.rating.rating_max: type: integer description: the maximum value for a rating_type tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info: type: object description: delivery information delivery information including free and fast delivery date ranges tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_message: type: string description: delivery information message accompanying the delivery information as posted by the seller tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price: type: object description: price for the delivery price of the delivery based on the location you specified in the POST request; if free delivery is available, the value is null tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price.current: type: number description: current delivery price tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price.regular: type: number description: regular undiscounted delivery price tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price.max_value: type: number description: maximum undiscounted delivery price tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price.currency: type: string description: currency in the ISO format tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price.is_price_range: type: boolean description: indicates whether the delivery price is a range tasks.result.items.ranked_serp_element.previous_updated_time.delivery_info.delivery_price.displayed_price: type: string description: price line provided as displayed in Amazon listing tasks.result.items.ranked_serp_element.previous_updated_time.items: type: array items: type: string description: contains tasks.result.items.ranked_serp_element.previous_updated_time.items.type: type: string description: type of element = ‘related_searches_element’ tasks.result.items.ranked_serp_element.previous_updated_time.items.title: type: string description: product title tasks.result.items.ranked_serp_element.previous_updated_time.items.url: type: string description: the URL of the product page tasks.result.items.ranked_serp_element.previous_updated_time.items.image_alt: type: string description: the alt tag of the product image featured in the results tasks.result.items.ranked_serp_element.previous_updated_time.items.image_url: type: string description: URL of the product image featured in the results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: asin: type: string description: product ID required field unique product identifier (ASIN) on Amazon; you can receive the asin parameter by making a separate request to the Amazon Products endpoint location_name: type: string description: 'full name of the location required field if don’t specify location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: United States' location_code: type: integer description: 'location code required field if don’t specify location_name you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: 2840' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' limit: type: integer description: 'the maximum number of products in the results array optional field default value: 100; maximum value: 1000' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["keyword_data.keyword_info.search_volume","in",[100,1000]]; for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["keyword_data.keyword_info.competition,desc"] default rule: ["ranked_serp_element.serp_item.rank_group,asc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_data.keyword_info.search_volume,desc","keyword_data.keyword_info.cpc,desc"]' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - asin allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/amazon/ranked_keywords/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/amazon/related_keywords/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Related Keywords description: 'Amazon search terms related to a seed keyword. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The Google-side equivalent is `post_dataforseo_labs_google_related_keywords_live`; shopping intent and web intent diverge sharply, so do not substitute one for the other.' operationId: post_dataforseo_labs_amazon_related_keywords_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.seed_keyword: type: string description: keyword in a POST array tasks.result.seed_keyword_data: type: object description: keyword data for the seed keyword fields in the object are identical to that of keyword_data tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains objects with keywords and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: related keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword info for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the provided keyword idea on Amazon tasks.result.items.depth: type: integer description: keyword search depth tasks.result.items.related_keywords: type: array items: type: string description: list of related keywords represents the list of search queries which are related to the keyword returned in the array above '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field UTF-8 encoding the keywords should be specified in the lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' depth: type: integer description: 'keyword search depth optional field default value: 1; number of the returned results depends on the value you set in this field; you can specify a level from 0 to 4; estimated number of keywords for each level (maximum): 0 – the keyword set in the keyword field 1 – 6 keywords 2 – 42 keywords 3 – 258 keywords 4 – 1554 keywords' include_seed_keyword: type: boolean description: 'include data for the seed keyword optional field if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response default value: false' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/amazon/related_keywords/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/apple/app_competitors/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: App Store App Competitors Live description: 'App Store apps competing with a given app on shared keywords. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Google Play twin: `post_dataforseo_labs_google_app_competitors_live`.' operationId: post_dataforseo_labs_apple_app_competitors_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_id: type: string description: id of the app in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the app_id and competitor applications tasks.result.items.se_type: type: string description: search engine type tasks.result.items.app_id: type: string description: id of the competitor app tasks.result.items.avg_position: type: number description: 'average position of the app in App Store SERP Note: average position is calculated for intersected keywords only; the value for a given application may differ when combined with different target applications' tasks.result.items.sum_position: type: integer description: 'sum of all app positions in App Store SERP Note: sum position is calculated for intersected keywords only; the value for a given application may differ when combined with different target applications' tasks.result.items.intersections: type: integer description: number of intersecting keywords tasks.result.items.competitor_metrics: type: object description: 'metrics for intersecting keywords ranking data relevant to the keywords that the provided competitor application shares with the app in a POST request; note: in this array ranking data is provided for the returned competitor’s app_id' tasks.result.items.competitor_metrics.app_store_search_organic: type: object description: ranking data from App Store organic search tasks.result.items.competitor_metrics.app_store_search_organic.pos_1: type: integer description: 'number of SERPs where the competitor app ranks #1 in organic results' tasks.result.items.competitor_metrics.app_store_search_organic.pos_2_3: type: integer description: 'number of SERPs where the competitor app ranks #2-3 in organic results' tasks.result.items.competitor_metrics.app_store_search_organic.pos_4_10: type: integer description: 'number of SERPs where the competitor app ranks #4-10 in organic results' tasks.result.items.competitor_metrics.app_store_search_organic.pos_11_100: type: integer description: 'number of SERPs where the competitor app ranks #11-100 in organic results' tasks.result.items.competitor_metrics.app_store_search_organic.count: type: integer description: total count of organic SERPs that contain the competitor app tasks.result.items.competitor_metrics.app_store_search_organic.search_volume: type: integer description: total search volume of the intersecting keywords in App Store organic SERP tasks.result.items.full_metrics: type: object description: metrics for all keywords of the application full overview of ranking data relevant to all keywords that the provided app_id is ranking for tasks.result.items.full_metrics.app_store_search_organic: type: object description: ranking data from App Store organic search tasks.result.items.full_metrics.app_store_search_organic.pos_1: type: integer description: 'number of SERPs where the competitor app ranks #1 in organic results' tasks.result.items.full_metrics.app_store_search_organic.pos_2_3: type: integer description: 'number of SERPs where the competitor app ranks #2-3 in organic results' tasks.result.items.full_metrics.app_store_search_organic.pos_4_10: type: integer description: 'number of SERPs where the competitor app ranks #4-10 in organic results' tasks.result.items.full_metrics.app_store_search_organic.pos_11_100: type: integer description: 'number of SERPs where the competitor app ranks #11-100 in organic results' tasks.result.items.full_metrics.app_store_search_organic.count: type: integer description: total count of organic SERPs that contain the competitor app tasks.result.items.full_metrics.app_store_search_organic.search_volume: type: integer description: total search volume of the app’s ranking keywords in App Store organic SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on App Store; you can find the ID in the URL of every app listed on App Store; example: in the URL https://apps.apple.com/us/app/id835599320 the id is 835599320' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in example: ["intersections",">",500] [["competitor_metrics.app_store_search_organic.pos_1","",10],"and",["avg_position",">=","10"]] [[["intersections",">=",50],"and",["competitor_metrics.app_store_search_organic.pos_1","in",[1,5]]], "or", ["sum_position",">=","10000"]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results; possible sorting types: asc – results will be sorted in the ascending order; desc – results will be sorted in the descending order; you should use a comma to specify a sorting type; example: ["intersections,asc"] Note: you can set no more than three sorting rules in a single request; you should use a comma to separate several sorting rules; example: ["intersections,desc","sum_position,asc"] default rule: ["intersections,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned apps optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned apps optional field default value: 0 if you specify the 10 value, the first ten apps in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/apple/app_competitors/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/apple/app_intersection/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: App Store App Intersection Live description: 'The keywords two or more App Store apps both rank for. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Google Play twin: `post_dataforseo_labs_google_app_intersection_live`.' operationId: post_dataforseo_labs_apple_app_intersection_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_ids: type: object description: ids of the apps in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the ranking keywords for the app specified in the app_id field tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: returned keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword info for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive); in this case, will equal null tasks.result.items.keyword_data.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article; in this case, will equal null' tasks.result.items.keyword_data.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword; in this case, will equal null tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword on App Store tasks.result.items.keyword_data.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories; in this case, will equal null tasks.result.items.keyword_data.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches for this keyword (as available for the past twelve months), targeted to the specified geographic locations; in this case, will equal null tasks.result.items.keyword_data.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.keyword_data.serp_info.se_type: type: string description: search engine type search engine type specified in a POST request; for this endpoint, the field equals bing tasks.result.items.keyword_data.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.keyword_data.serp_info.serp_item_types: type: array items: type: string description: types of search results in SERP contains types of search results (items) found in SERP; in this case, will equal null tasks.result.items.keyword_data.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.keyword_data.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.items.intersection_result: type: object description: contains SERP data for the returned keyword data will be provided in separate arrays for each app ID you specified in the app_ids object when setting a task; depending on the number of specified app IDs, it can contain from 1 to 20 arrays named respectively tasks.result.items.intersection_result.1: type: object description: 'contains SERP data for the respective app ID field name varies in the range from 1 to 20 according to the number of app IDs in the app_ids object; possible types of SERP elements: app_store_search_organic' tasks.result.items.intersection_result.1.type: type: string description: 'type of the SERP element possible values: app_store_search_organic' tasks.result.items.intersection_result.1.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.intersection_result.1.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.intersection_result.1.position: type: string description: 'the alignment of the element in SERP can take the following values: left, right' tasks.result.items.intersection_result.1.app_id: type: string description: id of the app tasks.result.items.intersection_result.1.title: type: string description: title of the app tasks.result.items.intersection_result.1.url: type: string description: URL to the app page on App Store tasks.result.items.intersection_result.1.icon: type: string description: URL to the app icon tasks.result.items.intersection_result.1.reviews_count: type: integer description: the total number of reviews of the app tasks.result.items.intersection_result.1.rating: type: object description: average rating of the app tasks.result.items.intersection_result.1.rating.rating_type: type: string description: 'the type of the rating can take the following values: Max5' tasks.result.items.intersection_result.1.rating.value: type: number description: the value of the rating tasks.result.items.intersection_result.1.rating.votes_count: type: integer description: the amount of feedback in this case, the value will be null tasks.result.items.intersection_result.1.rating.rating_max: type: integer description: the maximum value for a rating_type the maximum value for Max5 is 5 tasks.result.items.intersection_result.1.is_free: type: boolean description: indicates whether the app is free tasks.result.items.intersection_result.1.is_free.current: type: number description: current price refers to the current price indicated in the element tasks.result.items.intersection_result.1.is_free.regular: type: number description: regular price refers to the regular price indicated in the element tasks.result.items.intersection_result.1.is_free.max_value: type: number description: the maximum price refers to the maximum price indicated in the element tasks.result.items.intersection_result.1.is_free.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.intersection_result.1.is_free.is_price_range: type: boolean description: price is provided as a range indicates whether a price is provided in a range tasks.result.items.intersection_result.1.is_free.displayed_price: type: string description: price string in the result raw price string as provided in the result '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_ids: type: object description: 'ids of the target apps required field IDs of the target mobile applications on App Store; you can find the ID in the URL of every app listed on App Store; example: in the URL https://apps.apple.com/us/app/id835599320 the id is 835599320; the ids should be specified the following way: "app_ids": { "1": "686449807", "2": "382617920" } if you specify a single ID here, the API will return results only for one application; the maximum number of app IDs you can specify in this object is 20' additionalProperties: type: string location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in example: ["keyword_data.keyword_info.search_volume",">",500] [["keyword_data.keyword_info.search_volume","",500],"and",[intersection_result.382617920.rank_group",">=","10"]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results; possible sorting types: asc – results will be sorted in the ascending order; desc – results will be sorted in the descending order; you should use a comma to specify a sorting type; example: ["intersection_result.382617920.rank_absolute,asc"] Note: you can set no more than three sorting rules in a single request; you should use a comma to separate several sorting rules; example: ["intersection_result.382617920.rank_absolute,desc","keyword_data.keyword_info.search_volume,asc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_ids allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/apple/app_intersection/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/apple/bulk_app_metrics/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02448 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: App Store Bulk App Metrics Live description: 'Ratings, reviews and install estimates for many App Store apps in one call. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Google Play twin: `post_dataforseo_labs_google_bulk_app_metrics_live`.' operationId: post_dataforseo_labs_apple_bulk_app_metrics_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_id: type: string description: id of the app in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the ranking app metrics of the specified application tasks.result.items.se_type: type: string description: search engine type tasks.result.items.app_id: type: string description: id of the app in a POST array tasks.result.items.metrics: type: object description: metrics for the ranking keywords of the app ranking data relevant to the keywords that the provided application ranks for on App Store tasks.result.items.metrics.app_store_search_organic: type: object description: ranking data from App Store organic search tasks.result.items.metrics.app_store_search_organic.pos_1: type: integer description: 'number of SERPs where the app ranks #1 in organic results' tasks.result.items.metrics.app_store_search_organic.pos_2_3: type: integer description: 'number of SERPs where the app ranks #2-3 in organic results' tasks.result.items.metrics.app_store_search_organic.pos_4_10: type: integer description: 'number of SERPs where the app ranks #4-10 in organic results' tasks.result.items.metrics.app_store_search_organic.pos_11_100: type: integer description: 'number of SERPs where the app ranks #11-100 in organic results' tasks.result.items.metrics.app_store_search_organic.count: type: integer description: total count of organic SERPs that contain the app tasks.result.items.metrics.app_store_search_organic.search_volume: type: integer description: total search volume of the app’s ranking keywords in App Store organic SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_ids: type: array items: type: string description: 'ids of the apps required field IDs of mobile applications on App Store; you can find the ID in the URL of every app listed on App Store; example: in the URL https://apps.apple.com/us/app/id835599320 the id is 835599320; the maximum number of IDs you can specify in this field is 1000' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_ids allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/apple/bulk_app_metrics/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/apple/keywords_for_app/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: App Store Keywords For App Live description: 'The keywords an App Store app ranks for. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The Google Play twin is `post_dataforseo_labs_google_keywords_for_app_live`; the two stores'' keyword sets rarely match, which is the reason to run both.' operationId: post_dataforseo_labs_apple_keywords_for_app_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_id: type: string description: id of the app in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the ranking keywords for the app specified in the app_id field tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: returned keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword info for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive); in this case, will equal null tasks.result.items.keyword_data.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article; in this case, will equal null' tasks.result.items.keyword_data.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword; in this case, will equal null tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword on App Store tasks.result.items.keyword_data.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories; in this case, will equal null tasks.result.items.keyword_data.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches for this keyword (as available for the past twelve months), targeted to the specified geographic locations; in this case, will equal null tasks.result.items.ranked_serp_element: type: object description: contains data on the domain’s SERP element found for the returned keyword tasks.result.items.ranked_serp_element.se_type: type: string description: search engine type tasks.result.items.ranked_serp_element.serp_item: type: array items: type: string description: contains data on the SERP element the list of supported SERP elements can be found below tasks.result.items.ranked_serp_element.serp_item.type: type: string description: 'type of the SERP element possible values: app_store_search_organic' tasks.result.items.ranked_serp_element.serp_item.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.ranked_serp_element.serp_item.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.ranked_serp_element.serp_item.position: type: string description: 'the alignment of the element in SERP can take the following values: left, right' tasks.result.items.ranked_serp_element.serp_item.app_id: type: string description: id of the app tasks.result.items.ranked_serp_element.serp_item.title: type: string description: title of the app tasks.result.items.ranked_serp_element.serp_item.url: type: string description: URL to the app page on App Store tasks.result.items.ranked_serp_element.serp_item.icon: type: string description: URL to the app icon tasks.result.items.ranked_serp_element.serp_item.reviews_count: type: integer description: the total number of reviews of the app tasks.result.items.ranked_serp_element.serp_item.rating: type: object description: average rating of the app tasks.result.items.ranked_serp_element.serp_item.rating.rating_type: type: string description: 'the type of the rating can take the following values: Max5' tasks.result.items.ranked_serp_element.serp_item.rating.value: type: number description: the value of the rating tasks.result.items.ranked_serp_element.serp_item.rating.votes_count: type: integer description: the amount of feedback in this case, the value will be null tasks.result.items.ranked_serp_element.serp_item.rating.rating_max: type: integer description: the maximum value for a rating_type the maximum value for Max5 is 5 tasks.result.items.ranked_serp_element.serp_item.is_free: type: boolean description: indicates whether the app is free tasks.result.items.ranked_serp_element.serp_item.is_free.current: type: number description: current price refers to the current price indicated in the element tasks.result.items.ranked_serp_element.serp_item.is_free.regular: type: number description: regular price refers to the regular price indicated in the element tasks.result.items.ranked_serp_element.serp_item.is_free.max_value: type: number description: the maximum price refers to the maximum price indicated in the element tasks.result.items.ranked_serp_element.serp_item.is_free.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.ranked_serp_element.serp_item.is_free.is_price_range: type: boolean description: price is provided as a range indicates whether a price is provided in a range tasks.result.items.ranked_serp_element.serp_item.is_free.displayed_price: type: string description: price string in the result raw price string as provided in the result tasks.result.items.ranked_serp_element.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.ranked_serp_element.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.ranked_serp_element.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.ranked_serp_element.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00; in this case, will equal null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on App Store; you can find the ID in the URL of every app listed on App Store; example: in the URL https://apps.apple.com/us/app/id835599320 the id is 835599320' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in example: ["keyword_data.keyword_info.search_volume",">",500] [["keyword_data.keyword_info.search_volume","",500],"and",["ranked_serp_element.serp_item.rank_group",">=","10"]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results; possible sorting types: asc – results will be sorted in the ascending order; desc – results will be sorted in the descending order; you should use a comma to specify a sorting type; example: ["ranked_serp_element.serp_item.rank_group,asc"] Note: you can set no more than three sorting rules in a single request; you should use a comma to separate several sorting rules; example: ["ranked_serp_element.serp_item.rank_group,desc","keyword_data.keyword_info.search_volume,asc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/apple/keywords_for_app/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/available_filters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Filters for DataForSEO Labs API description: 'The filterable fields for every Labs endpoint, keyed by endpoint: `related_keywords`, `keyword_suggestions`, `ranked_keywords`, `keyword_ideas`, `serp_competitors`, `relevant_pages`, `subdomains`, `competitors_domain`, `categories_for_domain`, `keywords_for_categories` and the rest. 🔴 **Measured at 60.9 KB** - large for a reference response, though nothing beside the location catalogues elsewhere in this provider. Free: upstream cost is 0. Fetch once and keep the section you need; an unknown filter field is rejected, not ignored.' operationId: get_dataforseo_labs_available_filters responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results contains the full list of available parameters that can be used for data filtration the parameters are grouped by the endpoint they can be used with '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/available_filters source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/app_competitors/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Google Play App Competitors Live description: 'Google Play apps competing with a given app on shared keywords. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The Apple twin is `post_dataforseo_labs_apple_app_competitors_live`. For the keywords behind the overlap use `post_dataforseo_labs_google_app_intersection_live`.' operationId: post_dataforseo_labs_google_app_competitors_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_id: type: string description: id of the app in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the app_id and competitor applications tasks.result.items.se_type: type: string description: search engine type tasks.result.items.app_id: type: string description: id of the competitor app tasks.result.items.avg_position: type: number description: 'average position of the app in Google Play SERP Note: average position is calculated for intersected keywords only; the value for a given application may differ when combined with different target applications' tasks.result.items.sum_position: type: integer description: 'sum of all app positions in Google Play SERP Note: sum position is calculated for intersected keywords only; the value for a given application may differ when combined with different target applications' tasks.result.items.intersections: type: integer description: number of intersecting keywords tasks.result.items.competitor_metrics: type: object description: 'metrics for intersecting keywords ranking data relevant to the keywords that the provided competitor application shares with the app in a POST request; note: in this array ranking data is provided for the returned competitor’s app_id' tasks.result.items.competitor_metrics.google_play_search_organic: type: object description: ranking data from Google Play organic search tasks.result.items.competitor_metrics.google_play_search_organic.pos_1: type: integer description: 'number of SERPs where the competitor app ranks #1 in organic results' tasks.result.items.competitor_metrics.google_play_search_organic.pos_2_3: type: integer description: 'number of SERPs where the competitor app ranks #2-3 in organic results' tasks.result.items.competitor_metrics.google_play_search_organic.pos_4_10: type: integer description: 'number of SERPs where the competitor app ranks #4-10 in organic results' tasks.result.items.competitor_metrics.google_play_search_organic.pos_11_100: type: integer description: 'number of SERPs where the competitor app ranks #11-100 in organic results' tasks.result.items.competitor_metrics.google_play_search_organic.count: type: integer description: total count of organic SERPs that contain the competitor app tasks.result.items.competitor_metrics.google_play_search_organic.search_volume: type: integer description: total search volume of the intersecting keywords in Google Play organic SERP tasks.result.items.full_metrics: type: object description: metrics for all keywords of the application full overview of ranking data relevant to all keywords that the provided app_id is ranking for tasks.result.items.full_metrics.google_play_search_organic: type: object description: ranking data from Google Play organic search tasks.result.items.full_metrics.google_play_search_organic.pos_1: type: integer description: 'number of SERPs where the competitor app ranks #1 in organic results' tasks.result.items.full_metrics.google_play_search_organic.pos_2_3: type: integer description: 'number of SERPs where the competitor app ranks #2-3 in organic results' tasks.result.items.full_metrics.google_play_search_organic.pos_4_10: type: integer description: 'number of SERPs where the competitor app ranks #4-10 in organic results' tasks.result.items.full_metrics.google_play_search_organic.pos_11_100: type: integer description: 'number of SERPs where the competitor app ranks #11-100 in organic results' tasks.result.items.full_metrics.google_play_search_organic.count: type: integer description: total count of organic SERPs that contain the competitor app tasks.result.items.full_metrics.google_play_search_organic.search_volume: type: integer description: total search volume of the app’s ranking keywords in Google Play organic SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on Google Play; you can find the ID in the URL of every app listed on Google Play; example: in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger the id is org.telegram.messenger' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in example: ["intersections",">",500] [["competitor_metrics.google_play_search_organic.pos_1","",10],"and",["avg_position",">=","10"]] [[["intersections",">=",50],"and",["competitor_metrics.google_play_search_organic.pos_1","in",[1,5]]], "or", ["sum_position",">=","10000"]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results; possible sorting types: asc – results will be sorted in the ascending order; desc – results will be sorted in the descending order; you should use a comma to specify a sorting type; example: ["intersections,asc"] Note: you can set no more than three sorting rules in a single request; you should use a comma to separate several sorting rules; example: ["intersections,desc","sum_position,asc"] default rule: ["intersections,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned apps optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned apps optional field default value: 0 if you specify the 10 value, the first ten apps in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/app_competitors/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/app_intersection/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Google Play App Intersection Live description: 'The keywords two or more Google Play apps both rank for. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Where `post_dataforseo_labs_google_app_competitors_live` names the rivals, this names the ground they contest. Apple twin: `post_dataforseo_labs_apple_app_intersection_live`.' operationId: post_dataforseo_labs_google_app_intersection_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_ids: type: object description: ids of the apps in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the ranking keywords for the app specified in the app_id field tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: returned keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword info for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive); in this case, will equal null tasks.result.items.keyword_data.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article; in this case, will equal null' tasks.result.items.keyword_data.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword; in this case, will equal null tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword on Google Play tasks.result.items.keyword_data.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories; in this case, will equal null tasks.result.items.keyword_data.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches for this keyword (as available for the past twelve months), targeted to the specified geographic locations; in this case, will equal null tasks.result.items.keyword_data.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.keyword_data.serp_info.se_type: type: string description: search engine type search engine type specified in a POST request; for this endpoint, the field equals bing tasks.result.items.keyword_data.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.keyword_data.serp_info.serp_item_types: type: array items: type: string description: types of search results in SERP contains types of search results (items) found in SERP; in this case, will equal null tasks.result.items.keyword_data.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.keyword_data.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.items.intersection_result: type: object description: contains SERP data for the returned keyword data will be provided in separate arrays for each app ID you specified in the app_ids object when setting a task; depending on the number of specified app IDs, it can contain from 1 to 20 arrays named respectively tasks.result.items.intersection_result.1: type: object description: 'contains SERP data for the respective app ID field name varies in the range from 1 to 20 according to the number of app IDs in the app_ids object; possible types of SERP elements: google_play_search_organic' tasks.result.items.intersection_result.1.type: type: string description: 'type of the SERP element possible values: google_play_search_organic' tasks.result.items.intersection_result.1.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.intersection_result.1.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.intersection_result.1.position: type: string description: 'the alignment of the element in SERP can take the following values: left, right' tasks.result.items.intersection_result.1.app_id: type: string description: id of the app tasks.result.items.intersection_result.1.title: type: string description: title of the app tasks.result.items.intersection_result.1.url: type: string description: URL to the app page on Google Play tasks.result.items.intersection_result.1.icon: type: string description: URL to the app icon tasks.result.items.intersection_result.1.reviews_count: type: integer description: the total number of reviews of the app tasks.result.items.intersection_result.1.rating: type: object description: average rating of the app tasks.result.items.intersection_result.1.rating.rating_type: type: string description: 'the type of the rating can take the following values: Max5' tasks.result.items.intersection_result.1.rating.value: type: number description: the value of the rating tasks.result.items.intersection_result.1.rating.votes_count: type: integer description: the amount of feedback in this case, the value will be null tasks.result.items.intersection_result.1.rating.rating_max: type: integer description: the maximum value for a rating_type the maximum value for Max5 is 5 tasks.result.items.intersection_result.1.is_free: type: boolean description: indicates whether the app is free tasks.result.items.intersection_result.1.is_free.current: type: number description: current price refers to the current price indicated in the element tasks.result.items.intersection_result.1.is_free.regular: type: number description: regular price refers to the regular price indicated in the element tasks.result.items.intersection_result.1.is_free.max_value: type: number description: the maximum price refers to the maximum price indicated in the element tasks.result.items.intersection_result.1.is_free.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.intersection_result.1.is_free.is_price_range: type: boolean description: price is provided as a range indicates whether a price is provided in a range tasks.result.items.intersection_result.1.is_free.displayed_price: type: string description: price string in the result raw price string as provided in the result tasks.result.items.intersection_result.1.developer: type: string description: name of the app developer tasks.result.items.intersection_result.1.developer_url: type: object description: URL to the developer page on Google Play '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_ids: type: object description: 'ids of the target apps required field IDs of the target mobile applications on Google Play; you can find the ID in the URL of every app listed on Google Play; example: in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger the id is org.telegram.messenger;; the ids should be specified the following way: "app_ids": { "1": "org.telegram.messenger", "2": "com.zhiliaoapp.musically" } if you specify a single ID here, the API will return results only for one application; the maximum number of app IDs you can specify in this object is 20' additionalProperties: type: string location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in example: ["keyword_data.keyword_info.search_volume",">",500] [["keyword_data.keyword_info.search_volume","",500],"and",[intersection_result.382617920.rank_group",">=","10"]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results; possible sorting types: asc – results will be sorted in the ascending order; desc – results will be sorted in the descending order; you should use a comma to specify a sorting type; example: ["intersection_result.382617920.rank_absolute,asc"] Note: you can set no more than three sorting rules in a single request; you should use a comma to separate several sorting rules; example: ["intersection_result.382617920.rank_absolute,desc","keyword_data.keyword_info.search_volume,asc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_ids allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/app_intersection/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/available_history: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: DataForSEO Labs Google Available History description: 'The dates for which historical Labs data exists, as a `date` list. Measured at 2.0 KB. Free: upstream cost is 0. **Read it before calling any historical endpoint** - `post_dataforseo_labs_google_historical_rank_live` and its siblings return nothing rather than an error for a date outside this range.' operationId: get_dataforseo_labs_google_available_history responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: the data specified in the API call tasks.result: type: array items: type: string description: array of objects containing results tasks.result.date: type: string description: 'available date indicates the date of the range available for setting in the Domain Metrics by Categories endpoint example: 2022-05-16' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/available_history source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/bulk_app_metrics/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02448 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Google Play Bulk App Metrics Live description: 'Ratings, reviews and install estimates for many Google Play apps in one call. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Price is per call, so this is how to screen an app list before spending per-app calls. Apple twin: `post_dataforseo_labs_apple_bulk_app_metrics_live`.' operationId: post_dataforseo_labs_google_bulk_app_metrics_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_id: type: string description: id of the app in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the ranking app metrics of the specified application tasks.result.items.se_type: type: string description: search engine type tasks.result.items.app_id: type: string description: id of the app in a POST array tasks.result.items.metrics: type: object description: metrics for the ranking keywords of the app ranking data relevant to the keywords that the provided application ranks for on Google Play tasks.result.items.metrics.google_play_search_organic: type: object description: ranking data from Google Play organic search tasks.result.items.metrics.google_play_search_organic.pos_1: type: integer description: 'number of SERPs where the app ranks #1 in organic results' tasks.result.items.metrics.google_play_search_organic.pos_2_3: type: integer description: 'number of SERPs where the app ranks #2-3 in organic results' tasks.result.items.metrics.google_play_search_organic.pos_4_10: type: integer description: 'number of SERPs where the app ranks #4-10 in organic results' tasks.result.items.metrics.google_play_search_organic.pos_11_100: type: integer description: 'number of SERPs where the app ranks #11-100 in organic results' tasks.result.items.metrics.google_play_search_organic.count: type: integer description: total count of organic SERPs that contain the app tasks.result.items.metrics.google_play_search_organic.search_volume: type: integer description: total search volume of the app’s ranking keywords in Google Play organic SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_ids: type: array items: type: string description: 'ids of the app required field IDs of the mobile applications on Google Play; you can find the ID in the URL of every app listed on Google Play; example: in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger the id is org.telegram.messenger; the maximum number of IDs you can specify in this field is 1000' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_ids allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/bulk_app_metrics/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/bulk_keyword_difficulty/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.02856 max: 0.05832 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Keyword Difficulty description: 'Difficulty scores for many `keywords` in one call. Returns `se_type`, `total_count`, `items_count` and `items`. Measured at 713 bytes. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Price is per call, not per keyword, so send the whole list. For the full picture on fewer keywords use `post_dataforseo_labs_google_keyword_overview_live`.' operationId: post_dataforseo_labs_google_bulk_keyword_difficulty_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related keyword difficulty scores tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: keyword in a POST array tasks.result.items.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000 the keywords will be converted to lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if don’t specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if don’t specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/bulk_keyword_difficulty/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/bulk_traffic_estimation/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.02712 max: 0.03144 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Traffic Estimation description: 'Estimated organic traffic for many domains in one call. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Price is per call, so this is how to rank a competitor list cheaply before spending per-domain calls on the interesting ones. The historical version is `post_dataforseo_labs_google_historical_bulk_traffic_live`.' operationId: post_dataforseo_labs_google_bulk_traffic_estimation_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: array of items with relevant traffic estimation data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.target: type: string description: target domain in a POST array tasks.result.items.metrics: type: object description: traffic data relevant to the specified domain tasks.result.items.metrics.organic: type: object description: traffic data from organic search tasks.result.items.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.count: type: integer description: total count of organic SERPs that contain the domain tasks.result.items.metrics.paid: type: object description: traffic data from paid search tasks.result.items.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.count: type: integer description: total count of paid SERPs that contain the domain tasks.result.items.metrics.featured_snippet: type: object description: traffic data from the featured snippet results in Google SERP tasks.result.items.metrics.featured_snippet.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.count: type: integer description: total count of featured snippet items that contain the domain tasks.result.items.metrics.local_pack: type: object description: traffic data from the local pack results in SERP tasks.result.items.metrics.local_pack.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.count: type: integer description: total count of local pack items that contain the domain '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: target domains, subdomains, and webpages required field you can specify domains, subdomains, and webpages in this field; domains and subdomains should be specified without https:// and www.; pages should be specified with absolute URL, including https:// and www.; you can set up to 1000 domains, subdomains or webpages location_name: type: string description: 'full name of the location if you use this field, you don’t have to specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: United Kingdom' location_code: type: integer description: 'location code if you use this field, you don’t have to specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: 2840' language_name: type: string description: 'full name of the language if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: English' language_code: type: string description: 'language code if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: en' item_types: type: array items: type: string description: 'display results by item type optional field indicates the type of search results included in the response Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array possible values: ["organic", "paid", "featured_snippet", "local_pack"] default value: ["organic", "paid"]' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true, only core keywords will be returned, all highly similar keywords will be excluded; default value: false' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/bulk_traffic_estimation/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/categories_for_domain/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Categories For Domain description: 'The topics a `target` site ranks in, as Google''s own category codes with the site''s footprint in each. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The reverse direction - keywords for a category you name - is `post_dataforseo_labs_google_keywords_for_categories_live`.' operationId: post_dataforseo_labs_google_categories_for_domain_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.target: type: string description: target domain or subdomain in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant categories and related ranking data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.metrics: type: object description: ranking data relevant to the specified domain or subdomain tasks.result.items.organic: type: object description: ranking and traffic data from organic search tasks.result.items.organic.pos_1: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #1' tasks.result.items.organic.pos_2_3: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #2-3' tasks.result.items.organic.pos_4_10: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #4-10' tasks.result.items.organic.pos_11_20: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #11-20' tasks.result.items.organic.pos_21_30: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #21-30' tasks.result.items.organic.pos_31_40: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #31-40' tasks.result.items.organic.pos_41_50: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #41-50' tasks.result.items.organic.pos_51_60: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #51-60' tasks.result.items.organic.pos_61_70: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #61-70' tasks.result.items.organic.pos_71_80: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #71-80' tasks.result.items.organic.pos_81_90: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #81-90' tasks.result.items.organic.pos_91_100: type: integer description: 'number of organic SERPs where the domain or subdomain ranks #91-100' tasks.result.items.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain or subdomain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.organic.count: type: integer description: total count of organic SERPs that contain the domain or subdomain tasks.result.items.organic.estimated_paid_traffic_cost: type: number description: estimated cost of converting organic search traffic into paid represents the estimated monthly cost (USD) of running ads for all keywords in the category that the domain or subdomain ranks for the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search learn more about how the metric is calculated in this help center article tasks.result.items.organic.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.organic.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.organic.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.organic.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.organic.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.organic.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.organic.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.organic.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.organic.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.organic.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.organic.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.organic.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.organic.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.organic.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.paid: type: object description: ranking and traffic data from paid search tasks.result.items.paid.pos_1: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #1' tasks.result.items.paid.pos_2_3: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #2-3' tasks.result.items.paid.pos_4_10: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #4-10' tasks.result.items.paid.pos_11_20: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #11-20' tasks.result.items.paid.pos_21_30: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #21-30' tasks.result.items.paid.pos_31_40: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #31-40' tasks.result.items.paid.pos_41_50: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #41-50' tasks.result.items.paid.pos_51_60: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #51-60' tasks.result.items.paid.pos_61_70: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #61-70' tasks.result.items.paid.pos_71_80: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #71-80' tasks.result.items.paid.pos_81_90: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #81-90' tasks.result.items.paid.pos_91_100: type: integer description: 'number of paid SERPs where the domain or subdomain ranks #91-100' tasks.result.items.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain or subdomain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.paid.count: type: integer description: total count of paid SERPs that contain the domain or subdomain tasks.result.items.paid.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.paid.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.paid.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.paid.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.paid.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.paid.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.paid.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.paid.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.paid.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.paid.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.paid.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.paid.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.paid.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.paid.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.paid.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.featured_snippet: type: object description: ranking and traffic data from the featured snippet results in Google SERP tasks.result.items.featured_snippet.pos_1: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #1' tasks.result.items.featured_snippet.pos_2_3: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #2-3' tasks.result.items.featured_snippet.pos_4_10: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #4-10' tasks.result.items.featured_snippet.pos_11_20: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #11-20' tasks.result.items.featured_snippet.pos_21_30: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #21-30' tasks.result.items.featured_snippet.pos_31_40: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #31-40' tasks.result.items.featured_snippet.pos_41_50: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #41-50' tasks.result.items.featured_snippet.pos_51_60: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #51-60' tasks.result.items.featured_snippet.pos_61_70: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #61-70' tasks.result.items.featured_snippet.pos_71_80: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #71-80' tasks.result.items.featured_snippet.pos_81_90: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #81-90' tasks.result.items.featured_snippet.pos_91_100: type: integer description: 'number of featured snippet items where the domain or subdomain ranks #91-100' tasks.result.items.featured_snippet.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain or subdomain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.featured_snippet.count: type: integer description: total count of featured snippet items that contain the domain or subdomain tasks.result.items.featured_snippet.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.featured_snippet.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.featured_snippet.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.featured_snippet.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.featured_snippet.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.featured_snippet.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.featured_snippet.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.featured_snippet.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.featured_snippet.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.featured_snippet.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.featured_snippet.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.featured_snippet.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.featured_snippet.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.featured_snippet.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.featured_snippet.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.local_pack: type: object description: ranking and traffic data from the local pack results in SERP tasks.result.items.local_pack.pos_1: type: integer description: 'number of local pack items where the domain or subdomain ranks #1' tasks.result.items.local_pack.pos_2_3: type: integer description: 'number of local pack items where the domain or subdomain ranks #2-3' tasks.result.items.local_pack.pos_4_10: type: integer description: 'number of local pack items where the domain or subdomain ranks #4-10' tasks.result.items.local_pack.pos_11_20: type: integer description: 'number of local pack items where the domain or subdomain ranks #11-20' tasks.result.items.local_pack.pos_21_30: type: integer description: 'number of local pack items where the domain or subdomain ranks #21-30' tasks.result.items.local_pack.pos_31_40: type: integer description: 'number of local pack items where the domain or subdomain ranks #31-40' tasks.result.items.local_pack.pos_41_50: type: integer description: 'number of local pack items where the domain or subdomain ranks #41-50' tasks.result.items.local_pack.pos_51_60: type: integer description: 'number of local pack items where the domain or subdomain ranks #51-60' tasks.result.items.local_pack.pos_61_70: type: integer description: 'number of local pack items where the domain or subdomain ranks #61-70' tasks.result.items.local_pack.pos_71_80: type: integer description: 'number of local pack items where the domain or subdomain ranks #71-80' tasks.result.items.local_pack.pos_81_90: type: integer description: 'number of local pack items where the domain or subdomain ranks #81-90' tasks.result.items.local_pack.pos_91_100: type: integer description: 'number of local pack items where the domain or subdomain ranks #91-100' tasks.result.items.local_pack.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain or subdomain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.local_pack.count: type: integer description: total count of local pack items that contain the domain or subdomain tasks.result.items.local_pack.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the domain or subdomain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.local_pack.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.local_pack.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.local_pack.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.local_pack.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.local_pack.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.local_pack.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.local_pack.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.local_pack.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.local_pack.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.local_pack.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.local_pack.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.local_pack.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.local_pack.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.local_pack.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain or subdomain required field the domain or subdomain name of the target website the domain or subdomain should be specified without https:// and www. location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' include_subcategories: type: boolean description: 'indicates if the subcategories will be included in the search optional field if set to false, the subcategories will be ignored default value: false learn more about the parameter in this help center article' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' historical_serp_mode: type: string description: 'data collection mode optional field you can use this field to filter the results; possible types of filtering: live — return metrics for SERPs in which the specified target currently has ranking results; lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn’t have them during the last check; all — return metrics for both types of SERPs. default value: live' item_types: type: array items: type: string description: 'display results by item type optional field indicates the type of search results included in the response Note: if the item_types array contains item types that are different from the organic object, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response; possible values: ["organic", "paid", "featured_snippet", "local_pack"] default value: ["organic", "paid"]' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in example: ["metrics.organic.pos_1,">",0] [[["metrics.organic.count",">=",100],"and",["metrics.organic.pos_1",">",0]], "or", ["metrics.organic.etv","in",[10,100]]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to specify a sorting type example: ["metrics.paid.etv,asc"] Note: you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["metrics.organic.etv,desc","metrics.paid.count,asc"] default rule: ["metrics.organic.count,desc"] Note: if the item_types array contains item types that are different from the organic object, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned categories optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned categories optional field default value: 0 if you specify the 10 value, the first ten categories in the results array will be omitted and the data will be provided for the successive categories' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/categories_for_domain/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/categories_for_keywords/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Languages for Google Categories for Keywords API description: 'The languages `post_dataforseo_labs_google_categories_for_kw_live` accepts, as `language_name` and `language_code`. Measured at 2.8 KB. Free: upstream cost is 0. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_labs_google_categories_for_kw_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/categories_for_keywords/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/categories_for_keywords/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02424 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Categories for Keywords description: 'The categories a set of `keywords` belongs to. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Language codes come from `get_dataforseo_labs_google_categories_for_kw_languages`. Use it to check whether a keyword list is coherent before building a page around it.' operationId: post_dataforseo_labs_google_categories_for_kw_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related keyword difficulty scores tasks.result.items.keyword: type: string description: keyword in a POST array tasks.result.items.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000 the keywords will be converted to lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/languages example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/languages example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/categories_for_keywords/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/domain_rank_overview/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.02424 max: 0.02424 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Rank Overview description: 'A domain''s search footprint: organic and paid keyword counts, estimated traffic and traffic value, by `location_code`. Returns `se_type`, `target`, `total_count`, `items_count` and `items`. Measured at 1.6 KB. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For the same numbers over time use `post_dataforseo_labs_google_historical_rank_live`; for many domains at once, `post_dataforseo_labs_google_bulk_traffic_estimation_live`.' operationId: post_dataforseo_labs_google_domain_rank_overview_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.target: type: string description: target domain in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains ranking and traffic data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.metrics: type: object description: ranking data relevant to the specified domain tasks.result.items.metrics.organic: type: object description: ranking and traffic data from organic search tasks.result.items.metrics.organic.pos_1: type: integer description: 'number of organic SERPs where the domain ranks #1' tasks.result.items.metrics.organic.pos_2_3: type: integer description: 'number of organic SERPs where the domain ranks #2-3' tasks.result.items.metrics.organic.pos_4_10: type: integer description: 'number of organic SERPs where the domain ranks #4-10' tasks.result.items.metrics.organic.pos_11_20: type: integer description: 'number of organic SERPs where the domain ranks #11-20' tasks.result.items.metrics.organic.pos_21_30: type: integer description: 'number of organic SERPs where the domain ranks #21-30' tasks.result.items.metrics.organic.pos_31_40: type: integer description: 'number of organic SERPs where the domain ranks #31-40' tasks.result.items.metrics.organic.pos_41_50: type: integer description: 'number of organic SERPs where the domain ranks #41-50' tasks.result.items.metrics.organic.pos_51_60: type: integer description: 'number of organic SERPs where the domain ranks #51-60' tasks.result.items.metrics.organic.pos_61_70: type: integer description: 'number of organic SERPs where the domain ranks #61-70' tasks.result.items.metrics.organic.pos_71_80: type: integer description: 'number of organic SERPs where the domain ranks #71-80' tasks.result.items.metrics.organic.pos_81_90: type: integer description: 'number of organic SERPs where the domain ranks #81-90' tasks.result.items.metrics.organic.pos_91_100: type: integer description: 'number of organic SERPs where the domain ranks #91-100' tasks.result.items.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.count: type: integer description: total count of organic SERPs that contain the domain tasks.result.items.metrics.organic.estimated_paid_traffic_cost: type: number description: estimated cost of converting organic search traffic into paid represents the estimated monthly cost of running ads (USD) for all keywords that a domain ranks for the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for this domain tasks.result.items.metrics.organic.is_up: type: integer description: rank went up indicates how many ranked elements of this domain went up in Google Search tasks.result.items.metrics.organic.is_down: type: integer description: rank went down indicates how many ranked elements of this domain went down in Google Search tasks.result.items.metrics.organic.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of this domain were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.paid: type: object description: ranking and traffic data from paid search tasks.result.items.metrics.paid.pos_1: type: integer description: 'number of paid SERPs where the domain ranks #1' tasks.result.items.metrics.paid.pos_2_3: type: integer description: 'number of paid SERPs where the domain ranks #2-3' tasks.result.items.metrics.paid.pos_4_10: type: integer description: 'number of paid SERPs where the domain ranks #4-10' tasks.result.items.metrics.paid.pos_11_20: type: integer description: 'number of paid SERPs where the domain ranks #11-20' tasks.result.items.metrics.paid.pos_21_30: type: integer description: 'number of paid SERPs where the domain ranks #21-30' tasks.result.items.metrics.paid.pos_31_40: type: integer description: 'number of paid SERPs where the domain ranks #31-40' tasks.result.items.metrics.paid.pos_41_50: type: integer description: 'number of paid SERPs where the domain ranks #41-50' tasks.result.items.metrics.paid.pos_51_60: type: integer description: 'number of paid SERPs where the domain ranks #51-60' tasks.result.items.metrics.paid.pos_61_70: type: integer description: 'number of paid SERPs where the domain ranks #61-70' tasks.result.items.metrics.paid.pos_71_80: type: integer description: 'number of paid SERPs where the domain ranks #71-80' tasks.result.items.metrics.paid.pos_81_90: type: integer description: 'number of paid SERPs where the domain ranks #81-90' tasks.result.items.metrics.paid.pos_91_100: type: integer description: 'number of paid SERPs where the domain ranks #91-100' tasks.result.items.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.count: type: integer description: total count of paid SERPs that contain the domain tasks.result.items.metrics.paid.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for this domain tasks.result.items.metrics.paid.is_up: type: integer description: rank went up indicates how many ranked elements of this domain went up in Google Search tasks.result.items.metrics.paid.is_down: type: integer description: rank went down indicates how many ranked elements of this domain went down in Google Search tasks.result.items.metrics.paid.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of this domain were previously presented in SERPs, but weren’t found during the last check '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain required field the domain name of the target website the domain should be specified without https:// and www. location_name: type: string description: 'full name of the location optional field if you use this field, you don’t need to specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: United Kingdom' location_code: type: integer description: 'location code optional field if you use this field, you don’t need to specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: 2840' language_name: type: string description: 'full name of the language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: English' language_code: type: string description: 'language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: en' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true, all highly similar keywords will be excluded from the ranking and traffic calculations, the results will be based on data for main keywords from groups of synonyms default value: false' limit: type: integer description: 'the maximum number of returned results for domain optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned items optional field default value: 0 if you specify the 10 value, the first ten items in the results array will be omitted and the data will be provided for the successive items' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/domain_rank_overview/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/historical_bulk_traffic_estimation/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.2496 max: 0.2496 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Historical Bulk Traffic Estimation description: 'Estimated organic traffic for many domains at each point in the available history - the time series behind `post_dataforseo_labs_google_bulk_traffic_estimation_live`. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Response size multiplies domains by dates; keep both lists short. Available dates come from `get_dataforseo_labs_google_available_history`.' operationId: post_dataforseo_labs_google_historical_bulk_traffic_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: array of items with relevant traffic estimation data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.target: type: string description: target domain in a POST array tasks.result.items.metrics: type: object description: traffic data relevant to the specified domain tasks.result.items.metrics.organic: type: array items: type: string description: traffic data from organic search tasks.result.items.metrics.organic.year: type: integer description: year for which the data is provided tasks.result.items.metrics.organic.month: type: integer description: month for which the data is provided tasks.result.items.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.count: type: integer description: total count of organic SERPs that contain the domain tasks.result.items.metrics.paid: type: array items: type: string description: traffic data from paid search tasks.result.items.metrics.paid.year: type: integer description: year for which the data is provided tasks.result.items.metrics.paid.month: type: integer description: month for which the data is provided tasks.result.items.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.count: type: integer description: total count of paid SERPs that contain the domain tasks.result.items.metrics.featured_snippet: type: array items: type: string description: traffic data from the featured snippet results in Google SERP tasks.result.items.metrics.featured_snippet.year: type: integer description: year for which the data is provided tasks.result.items.metrics.featured_snippet.month: type: integer description: month for which the data is provided tasks.result.items.metrics.featured_snippet.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.count: type: integer description: total count of featured snippet items that contain the domain tasks.result.items.metrics.local_pack: type: array items: type: string description: traffic data from the local pack results in SERP tasks.result.items.metrics.local_pack.year: type: integer description: year for which the data is provided tasks.result.items.metrics.local_pack.month: type: integer description: month for which the data is provided tasks.result.items.metrics.local_pack.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.count: type: integer description: total count of local pack items that contain the domain '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: target domains and subdomains required field you can specify domains and subdomains in this field; domains and subdomains should be specified without https:// and www.; you can set up to 1000 domains or subdomains location_name: type: string description: 'full name of the location if you use this field, you don’t have to specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: United Kingdom' location_code: type: integer description: 'location code if you use this field, you don’t have to specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: 2840' language_name: type: string description: 'full name of the language if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: English' language_code: type: string description: 'language code if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: en' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, the data will be provided for the previous 12 months minimal possible value: 2020-10-01 date format: "yyyy-mm-dd"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default; date format: "yyyy-mm-dd" example: "2021-04-01"' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true, only core keywords will be returned, all highly similar keywords will be excluded; default value: false' item_types: type: array items: type: string description: 'display results by item type optional field indicates the type of search results included in the response; Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; possible values: ["organic", "paid", "featured_snippet", "local_pack"] default value: ["organic", "paid"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/historical_bulk_traffic_estimation/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/historical_keyword_data/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02424 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Historical Keyword Data description: 'How a keyword''s own metrics - volume, competition, cpc - moved over time. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This tracks the keyword; `post_dataforseo_labs_google_historical_rank_live` tracks a domain. For the current values use `post_dataforseo_labs_google_keyword_overview_live`.' operationId: post_dataforseo_labs_google_historical_keyword_data_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: keyword keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character) tasks.result.items.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.history: type: array items: type: string description: array of objects with historical data for the keyword tasks.result.items.history.year: type: integer description: year tasks.result.items.history.month: type: integer description: month tasks.result.items.history.keyword_info: type: object description: historical data for the keyword tasks.result.items.history.keyword_info.se_type: type: string description: search engine type tasks.result.items.history.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.history.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.history.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.history.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.history.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.history.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.history.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.history.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.history.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.history.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.history.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.history.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.history.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.history.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.history.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.history.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 700 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the specified keywords will be converted to lowercase format, data will be provided in a separate array note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn’t contain such keywords and cannot return data on them you will not be charged for the keywords omitted in the results learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/historical_keyword_data/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/historical_rank_overview/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.2544 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Historical Rank Overview description: 'A domain''s rank overview as it stood at each point in the available history. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Check `get_dataforseo_labs_google_available_history` first - it names the dates that exist, and asking for a date outside them returns nothing rather than an error. The current snapshot is `post_dataforseo_labs_google_domain_rank_overview_live`.' operationId: post_dataforseo_labs_google_historical_rank_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.target: type: string description: target domain in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains historical ranking and traffic data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.year: type: integer description: year for which the data is provided tasks.result.items.month: type: integer description: month for which the data is provided tasks.result.items.metrics: type: object description: ranking data relevant to the specified domain tasks.result.items.metrics.organic: type: object description: ranking and traffic data from organic search tasks.result.items.metrics.organic.pos_1: type: integer description: 'number of organic SERPs where the domain ranks #1' tasks.result.items.metrics.organic.pos_2_3: type: integer description: 'number of organic SERPs where the domain ranks #2-3' tasks.result.items.metrics.organic.pos_4_10: type: integer description: 'number of organic SERPs where the domain ranks #4-10' tasks.result.items.metrics.organic.pos_11_20: type: integer description: 'number of organic SERPs where the domain ranks #11-20' tasks.result.items.metrics.organic.pos_21_30: type: integer description: 'number of organic SERPs where the domain ranks #21-30' tasks.result.items.metrics.organic.pos_31_40: type: integer description: 'number of organic SERPs where the domain ranks #31-40' tasks.result.items.metrics.organic.pos_41_50: type: integer description: 'number of organic SERPs where the domain ranks #41-50' tasks.result.items.metrics.organic.pos_51_60: type: integer description: 'number of organic SERPs where the domain ranks #51-60' tasks.result.items.metrics.organic.pos_61_70: type: integer description: 'number of organic SERPs where the domain ranks #61-70' tasks.result.items.metrics.organic.pos_71_80: type: integer description: 'number of organic SERPs where the domain ranks #71-80' tasks.result.items.metrics.organic.pos_81_90: type: integer description: 'number of organic SERPs where the domain ranks #81-90' tasks.result.items.metrics.organic.pos_91_100: type: integer description: 'number of organic SERPs where the domain ranks #91-100' tasks.result.items.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.count: type: integer description: total count of organic SERPs that contain the domain tasks.result.items.metrics.organic.estimated_paid_traffic_cost: type: number description: estimated cost of converting organic search traffic into paid represents the estimated monthly cost of running ads (USD) for all keywords that a domain ranks for the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.metrics.organic.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.metrics.organic.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.metrics.organic.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.organic.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.metrics.organic.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.metrics.organic.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.metrics.organic.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.metrics.organic.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.metrics.organic.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.metrics.organic.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.metrics.paid: type: object description: ranking and traffic data from paid search tasks.result.items.metrics.paid.pos_1: type: integer description: 'number of paid SERPs where the domain ranks #1' tasks.result.items.metrics.paid.pos_2_3: type: integer description: 'number of paid SERPs where the domain ranks #2-3' tasks.result.items.metrics.paid.pos_4_10: type: integer description: 'number of paid SERPs where the domain ranks #4-10' tasks.result.items.metrics.paid.pos_11_20: type: integer description: 'number of paid SERPs where the domain ranks #11-20' tasks.result.items.metrics.paid.pos_21_30: type: integer description: 'number of paid SERPs where the domain ranks #21-30' tasks.result.items.metrics.paid.pos_31_40: type: integer description: 'number of paid SERPs where the domain ranks #31-40' tasks.result.items.metrics.paid.pos_41_50: type: integer description: 'number of paid SERPs where the domain ranks #41-50' tasks.result.items.metrics.paid.pos_51_60: type: integer description: 'number of paid SERPs where the domain ranks #51-60' tasks.result.items.metrics.paid.pos_61_70: type: integer description: 'number of paid SERPs where the domain ranks #61-70' tasks.result.items.metrics.paid.pos_71_80: type: integer description: 'number of paid SERPs where the domain ranks #71-80' tasks.result.items.metrics.paid.pos_81_90: type: integer description: 'number of paid SERPs where the domain ranks #81-90' tasks.result.items.metrics.paid.pos_91_100: type: integer description: 'number of paid SERPs where the domain ranks #91-100' tasks.result.items.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.count: type: integer description: total count of paid SERPs that contain the domain tasks.result.items.metrics.paid.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.metrics.paid.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.metrics.paid.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.metrics.paid.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.paid.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.metrics.paid.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.metrics.paid.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.metrics.paid.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.metrics.paid.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.metrics.paid.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.metrics.paid.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain required field the domain name of the target website the domain should be specified without https:// and www. location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' date_from: type: string description: 'starting date of the time range optional field if you don’t specify this field, the data will be provided for the previous 6 months minimal possible value: 2020-10-01 date format: "yyyy-mm-dd"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2021-04-01"' correlate: type: boolean description: 'correlate data with previously obtained datasets optional field default value: true if you use this parameter, our system will correlate data you obtain now with previously obtained datasets this parameter is intended to mitigate any inconsistencies that may result from changes to our database we recommend always setting correlate to true' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true, only data based on core keywords will be returned, data for all highly similar keywords will be excluded; default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response; default value: false; Note: historical clickstream data is available from 2024/05 (May, 2024); with this parameter enabled, you will be charged double the price for the request; learn more about how clickstream-based metrics are calculated in this help center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/historical_rank_overview/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/keyword_ideas/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048 max: 0.264 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keyword Ideas description: 'Expands seed `keywords` into ideas that share their semantic space. Returns `seed_keywords`, `total_count`, `items_count`, `offset`, `offset_token` and `items`. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. Measured at 3.6 KB with a limit of 1. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The equivalent in the other family, `post_dataforseo_keywords_gads_kw_for_keywords_live`, measured 2.8 MB for a single seed because it has no `limit`. Prefer this one. For variants of one phrase rather than the wider space, `post_dataforseo_labs_google_keyword_suggestions_live`.' operationId: post_dataforseo_labs_google_keyword_ideas_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.seed_keywords: type: array items: type: string description: keywords in a POST array keywords are returned with decoded %## (plus character ‘+’ will be decoded to a space character) tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total number of results relevant to your request in our database tasks.result.items_count: type: integer description: number of results returned in the items array tasks.result.offset: type: integer description: current offset value tasks.result.offset_token: type: string description: 'offset token for subsequent requests you can use the string provided in this field to get the subsequent results of the initial task; note: offset_token values are unique for each subsequent task' tasks.result.items: type: array items: type: string description: contains keyword ideas and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: returned keyword idea tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.keyword_info: type: object description: keyword data for the returned keyword idea tasks.result.items.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.keyword_properties.words_count: type: integer description: number of words in the keyword indicates how many words the keyword consists of tasks.result.items.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.serp_info.se_type: type: string description: search engine type tasks.result.items.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible item types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.items.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword tasks.result.items.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.items.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.items.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.items.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.items.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.items.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.items.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.items.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.items.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field UTF-8 encoding The maximum number of keywords you can specify: 200. The keywords will be converted to lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'unique location identifier required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English Note: if omitted, results default to the language with the most keyword records in the specified location; refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language' language_code: type: string description: 'language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en Note: if omitted, results default to the language with the most keyword records in the specified location; refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language' closely_variants: type: boolean description: 'search mode optional field if set to true the results will be based on the phrase-match search algorithm if set to false the results will be based on the broad-match search algorithm default value: false' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' limit: type: integer description: 'the maximum number of keywords in the results array optional field default value: 700 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'offset token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task. learn more about this parameter on our Help Center' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like, not_like you can use the % operator with like and not_like,as well as ilike, not_ilike to match any string of zero or more characters note that you can not filter the results by relevance example: ["keyword_info.search_volume",">",0] [["keyword_info.search_volume","in",[0,1000]], "and", ["keyword_info.competition_level","=","LOW"]] [["keyword_info.search_volume",">",100], "and", [["keyword_info.cpc"," for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter default rule: ["relevance,desc"] relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint. note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["relevance,desc","keyword_info.search_volume,desc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response anyOf: - required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - required: - offset_token tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/keyword_ideas/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/keyword_overview/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.02544 max: 0.06192 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keyword Overview description: 'Everything Labs knows about a list of `keywords` in one call: volume, difficulty, intent, competition and the SERP features they trigger. Returns `se_type`, `location_code`, `language_code`, `items_count` and `items`. Measured at 5.9 KB for one keyword. 💰 Measured at $0.01212 upstream, essentially the flat rate billed - the google_ads endpoints in seo-keywords answer similar questions at $0.09. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Start here when you have keywords; `post_dataforseo_labs_google_keyword_ideas_live` is where to go when you need more of them.' operationId: post_dataforseo_labs_google_keyword_overview_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: keyword keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character) tasks.result.items.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.search_partners: type: boolean description: indicates data for Google and partner sites if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search; if false, the results are returned for Google search sites only tasks.result.items.keyword_info: type: object description: keyword data for the returned keyword tasks.result.items.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.keyword_info.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.items.keyword_info.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_info.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.items.keyword_info.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_info.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.serp_info.se_type: type: string description: search engine type tasks.result.items.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible items types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.items.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 websites ranking organically for the keyword tasks.result.items.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.items.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.items.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.items.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.items.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.items.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.items.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.items.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.items.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'keywords required field The maximum number of keywords you can specify: 700 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the specified keywords will be converted to lowercase format, data will be provided in a separate array note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn’t contain such keywords and cannot return data on them you will not be charged for the keywords omitted in the results learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/keyword_overview/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/keyword_suggestions/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048 max: 0.264 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keyword Suggestions description: 'Long-tail variants containing one `keyword` - the phrase-match view, where `post_dataforseo_labs_google_keyword_ideas_live` is the semantic one. Returns `seed_keyword`, `seed_keyword_data`, `total_count`, `offset_token` and `items`. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. Measured at 3.2 KB with a limit of 1. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_labs_google_keyword_suggestions_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.seed_keyword: type: string description: keyword in a POST array tasks.result.seed_keyword_data: type: object description: keyword data for the seed keyword fields in this object are identical to those of the items array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.offset: type: integer description: current offset value tasks.result.offset_token: type: string description: 'offset token for subsequent requests you can use the string provided in this field to get the subsequent results of the initial task; note: offset_token values are unique for each subsequent task' tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: keyword suggestion tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.keyword_info: type: object description: keyword data for the returned keyword tasks.result.items.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches for this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.keyword_properties.words_count: type: integer description: number of words in the keyword indicates how many words the keyword consists of tasks.result.items.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.serp_info.se_type: type: string description: search engine type tasks.result.items.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible item types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.items.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword tasks.result.items.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.items.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.items.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.items.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.items.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.items.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.items.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.items.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.items.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.items.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.items.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.items.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field UTF-8 encoding the keywords will be converted to lowercase format; learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of the location optional field if you use this field, you don’t need to specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: United Kingdom' location_code: type: integer description: 'location code optional field if you use this field, you don’t need to specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: 2840' language_name: type: string description: 'full name of the language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English Note: if omitted, results default to the language with the most keyword records in the specified location; refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language' language_code: type: string description: 'language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en Note: if omitted, results default to the language with the most keyword records in the specified location; refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language' include_seed_keyword: type: boolean description: 'include data for the seed keyword optional field if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response default value: false' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' exact_match: type: boolean description: 'search for the exact phrase optional field if set to true, the returned keywords will include the exact keyword phrase you specified, with potentially other words before or after that phrase default value: false' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like, not_like you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters example: ["keyword_info.search_volume",">",0] [["keyword_info.search_volume","in",[0,1000]], "and", ["keyword_info.competition_level","=","LOW"]][["keyword_info.search_volume",">",100], "and", [["keyword_info.cpc"," for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order a comma is used as a separator example: ["keyword_info.competition,desc"] default rule: ["keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_info.search_volume,desc","keyword_info.cpc,desc"]' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'offset token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task. learn more about this parameter on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response anyOf: - required: - keyword - required: - offset_token example: - keyword: accounting software location_code: 2840 language_code: en limit: 3 tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/keyword_suggestions/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/keywords_for_app/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Google Play Keywords For App Live description: 'The keywords a Google Play app ranks for. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The Apple twin is `post_dataforseo_labs_apple_keywords_for_app_live`. Distinct from `seo-apps`''s store scraping: this is Labs'' own index, so it pages and costs a seventh of the live listings search there.' operationId: post_dataforseo_labs_google_keywords_for_app_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.app_id: type: string description: id of the app in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains data related to the ranking keywords for the app specified in the app_id field tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: returned keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword info for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive); in this case, will equal null tasks.result.items.keyword_data.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article; in this case, will equal null' tasks.result.items.keyword_data.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword; in this case, will equal null tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword on Google Play tasks.result.items.keyword_data.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request; in this case, will equal null tasks.result.items.keyword_data.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories; in this case, will equal null tasks.result.items.keyword_data.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches for this keyword (as available for the past twelve months), targeted to the specified geographic locations; in this case, will equal null tasks.result.items.ranked_serp_element: type: array items: type: string description: contains data on the domain’s SERP element found for the returned keyword tasks.result.items.ranked_serp_element.se_type: type: string description: search engine type tasks.result.items.ranked_serp_element.serp_item: type: array items: type: string description: contains data on the SERP element the list of supported SERP elements can be found below tasks.result.items.ranked_serp_element.serp_item.type: type: string description: 'type of the SERP element possible values: google_play_search_organic' tasks.result.items.ranked_serp_element.serp_item.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.ranked_serp_element.serp_item.rank_absolute: type: integer description: absolute rank in SERP absolute position among all the elements in SERP tasks.result.items.ranked_serp_element.serp_item.position: type: string description: 'the alignment of the element in SERP can take the following values: left, right' tasks.result.items.ranked_serp_element.serp_item.app_id: type: string description: id of the app tasks.result.items.ranked_serp_element.serp_item.title: type: string description: title of the app tasks.result.items.ranked_serp_element.serp_item.url: type: string description: URL to the app page on Google Play tasks.result.items.ranked_serp_element.serp_item.icon: type: string description: URL to the app icon tasks.result.items.ranked_serp_element.serp_item.reviews_count: type: integer description: the total number of reviews of the app tasks.result.items.ranked_serp_element.serp_item.rating: type: object description: average rating of the app tasks.result.items.ranked_serp_element.serp_item.rating.rating_type: type: string description: 'the type of the rating can take the following values: Max5' tasks.result.items.ranked_serp_element.serp_item.rating.value: type: number description: the value of the rating tasks.result.items.ranked_serp_element.serp_item.rating.votes_count: type: integer description: the amount of feedback in this case, the value will be null tasks.result.items.ranked_serp_element.serp_item.rating.rating_max: type: integer description: the maximum value for a rating_type the maximum value for Max5 is 5 tasks.result.items.ranked_serp_element.serp_item.is_free: type: boolean description: indicates whether the app is free tasks.result.items.ranked_serp_element.serp_item.is_free.current: type: number description: current price refers to the current price indicated in the element tasks.result.items.ranked_serp_element.serp_item.is_free.regular: type: number description: regular price refers to the regular price indicated in the element tasks.result.items.ranked_serp_element.serp_item.is_free.max_value: type: number description: the maximum price refers to the maximum price indicated in the element tasks.result.items.ranked_serp_element.serp_item.is_free.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.ranked_serp_element.serp_item.is_free.is_price_range: type: boolean description: price is provided as a range indicates whether a price is provided in a range tasks.result.items.ranked_serp_element.serp_item.is_free.displayed_price: type: string description: price string in the result raw price string as provided in the result tasks.result.items.ranked_serp_element.serp_item.developer: type: string description: name of the app developer tasks.result.items.ranked_serp_element.serp_item.developer_url: type: string description: URL to the developer page on Google Play tasks.result.items.ranked_serp_element.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.ranked_serp_element.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.ranked_serp_element.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.ranked_serp_element.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00; in this case, will equal null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the apps required field ID of the mobile application on Google Play; you can find the ID in the URL of every app listed on Google Play; example: in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger the id is org.telegram.messenger' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: United States' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the US location only; example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only; example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages; Note: this endpoint currently supports the English language only example: en' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: , , >, >=, =, , in, not_in example: ["keyword_data.keyword_info.search_volume",">",500] [["keyword_data.keyword_info.search_volume","",500],"and",["ranked_serp_element.serp_item.rank_group",">=","10"]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results; possible sorting types: asc – results will be sorted in the ascending order; desc – results will be sorted in the descending order; you should use a comma to specify a sorting type; example: ["ranked_serp_element.serp_item.rank_group,asc"] Note: you can set no more than three sorting rules in a single request; you should use a comma to separate several sorting rules; example: ["ranked_serp_element.serp_item.rank_group,desc","keyword_data.keyword_info.search_volume,asc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/keywords_for_app/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/keywords_for_categories/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keywords For Categories description: 'Every keyword Labs holds for a given category code - the reverse of `post_dataforseo_labs_google_categories_for_domain_live`. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ A broad category holds a great many keywords; set `limit` deliberately rather than relying on a default.' operationId: post_dataforseo_labs_google_keywords_for_categories_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.seed_categories: type: array items: type: string description: categories in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: the total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.offset: type: integer description: current offset value tasks.result.offset_token: type: string description: 'offset token for subsequent requests you can use the string provided in this field to get the subsequent results of the initial task; note: offset_token values are unique for each subsequent task' tasks.result.items: type: array items: type: string description: contains keyword ideas and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: found keyword tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.keyword_info: type: object description: keyword data for the returned keyword idea tasks.result.items.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.keyword_properties.words_count: type: integer description: number of words in the keyword indicates how many words the keyword consists of tasks.result.items.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.serp_info.se_type: type: string description: search engine type tasks.result.items.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible item types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword tasks.result.items.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.items.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.items.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.items.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.items.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.items.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.items.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.items.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.items.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.items.search_intent_info.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.items.search_intent_info.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: category_codes: type: array items: type: integer description: 'product and service categories required field The maximum number of categories you can specify: 20 you can download the full list of possible categories' location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'unique location identifier required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'unique language identifier required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' category_intersection: type: boolean description: 'category intersections optional field if set to true, you will get keywords featured in all specified categories; if set to false, you will keywords that are specified in any of the specified categories; default value: true' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' limit: type: integer description: 'the maximum number of keywords in the results array optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'offset token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task. learn more about this parameter on our Help Center' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like, not_like you can use the % operator with like and not_like,as well as ilike, not_ilike to match any string of zero or more characters example: ["keyword_info.search_volume",">",0] [["keyword_info.search_volume","in",[0,1000]], "and", ["keyword_info.competition_level","=","LOW"]] [["keyword_info.search_volume",">",100], "and", [["keyword_info.cpc"," for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["keyword_info.competition,desc"] default rule: ["keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_info.search_volume,desc","keyword_info.competition,asc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response anyOf: - required: - category_codes allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - required: - offset_token tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/keywords_for_categories/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/keywords_for_site/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.02424 p95: 0.072 max: 0.072 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keywords For Site description: 'The keywords a `target` site ranks for. Returns `se_type`, `target`, `total_count`, `offset_token` and `items`. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. Measured at 3.0 KB with a limit of 1. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The other family''s `post_dataforseo_keywords_gads_kw_for_site_live` answers this at $0.09 and measured 7.2 MB with no limit. This is the same question, paged and at a seventh of the price.' operationId: post_dataforseo_labs_google_kw_for_site_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.target: type: string description: target domain in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total number of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.offset: type: integer description: current offset value tasks.result.offset_token: type: string description: 'offset token for subsequent requests you can use the string provided in this field to get the subsequent results of the initial task; note: offset_token values are unique for each subsequent task' tasks.result.items: type: array items: type: string description: contains keyword ideas and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: returned keyword idea tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.keyword_info: type: object description: keyword data for the returned keyword idea tasks.result.items.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword. This value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.keyword_properties.words_count: type: integer description: number of words in the keyword indicates how many words the keyword consists of tasks.result.items.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.serp_info.se_type: type: string description: search engine type tasks.result.items.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible item types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.serp_info.se_results_count: type: string description: number of search results for the returned keyword tasks.result.items.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword tasks.result.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.avg_backlinks_info.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.avg_backlinks_info.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.avg_backlinks_info.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.avg_backlinks_info.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.avg_backlinks_info.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.avg_backlinks_info.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.avg_backlinks_info.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: target domain required field the domain name of the target website the domain should be specified without https:// location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'unique location identifier required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English Note: if omitted, results default to the language with the most keyword records in the specified location; refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language' language_code: type: string description: 'language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en Note: if omitted, results default to the language with the most keyword records in the specified location; refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_subdomains: type: boolean description: 'indicates if the subdomains will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' limit: type: integer description: 'the maximum number of keywords in the results array optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'offset token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task. learn more about this parameter on our Help Center' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like, not_like you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters note that you can not filter the results by relevance example: ["keyword_info.search_volume",">",0] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter default rule: ["relevance,desc"] relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint.note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["relevance,desc","keyword_info.search_volume,desc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response anyOf: - required: - target allOf: - anyOf: - required: - location_name - required: - location_code - required: - offset_token tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/keywords_for_site/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/related_keywords/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.0312 max: 0.0336 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Related Keywords description: 'Walks Google''s own ''searches related to'' graph outward from a keyword, depth by depth. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Different from both idea endpoints: this follows what Google itself links together, rather than a semantic model or a substring match.' operationId: post_dataforseo_labs_google_related_keywords_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.seed_keyword: type: string description: keyword in a POST array tasks.result.seed_keyword_data: type: array items: type: string description: keyword data for the seed keyword fields in the array are identical to that of keyword_data tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword_data: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword: type: string description: related keyword tasks.result.items.keyword_data.location_code: type: integer description: location code in a POST array tasks.result.items.keyword_data.language_code: type: string description: language code in a POST array tasks.result.items.keyword_data.keyword_info: type: object description: keyword data for the returned keyword tasks.result.items.keyword_data.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_data.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_data.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_data.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_data.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_data.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_data.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_data.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_data.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_data.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_data.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_data.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_data.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_data.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_data.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.keyword_data.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.keyword_data.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.keyword_data.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.keyword_data.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.keyword_data.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.keyword_data.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.keyword_data.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.keyword_data.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.keyword_data.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.keyword_data.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.keyword_data.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.keyword_data.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.keyword_data.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.keyword_data.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_data.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_data.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_data.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_data.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_data.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_data.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_data.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_data.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_data.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.keyword_data.serp_info: type: object description: SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.keyword_data.serp_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.keyword_data.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible item types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.keyword_data.serp_info.se_results_count: type: integer description: number of search results for the returned keyword tasks.result.items.keyword_data.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.serp_info.previous_updated_time: type: string description: 'previous to the most recent date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-10-15 12:57:46 +00:00' tasks.result.items.keyword_data.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword tasks.result.items.keyword_data.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.items.keyword_data.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.items.keyword_data.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.items.keyword_data.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.items.keyword_data.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.items.keyword_data.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.items.keyword_data.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.items.keyword_data.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.items.keyword_data.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.items.keyword_data.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.items.keyword_data.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.items.keyword_data.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.items.keyword_data.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.items.keyword_data.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_data.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.items.keyword_data.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_data.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.items.keyword_data.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.items.keyword_data.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.items.keyword_data.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.depth: type: integer description: keyword search depth tasks.result.items.related_keywords: type: array items: type: string description: list of related keywords represents the list of search queries which are related to the keyword returned in the array above '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field UTF-8 encoding the keywords will be converted to lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' depth: type: integer description: 'keyword search depth optional field default value: 1 number of the returned results depends on the value you set in this field you can specify a level from 0 to 4 estimated number of keywords for each level (maximum): 0 – the keyword set in the keyword field 1 – 8 keywords 2 – 72 keywords 3 – 584 keywords 4 – 4680 keywords' include_seed_keyword: type: boolean description: 'include data for the seed keyword optional field if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response default value: false' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' replace_with_core_keyword: type: boolean description: 'return data for core keyword optional field if true, serp_info and related_keywords will be returned for the main keyword in the group that the specified keyword belongs to; if false, serp_info and related_keywords will be returned for the specified keyword (if available); refer to this help center article for more details; default value: false' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like,not_like you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters example: ["keyword_data.keyword_info.search_volume",">",0] [["keyword_info.search_volume","in",[0,1000]], "and", ["keyword_data.keyword_info.competition_level","=","LOW"]] [["keyword_data.keyword_info.search_volume",">",100], "and", [["keyword_data.keyword_info.cpc"," for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["keyword_data.keyword_info.competition,desc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_data.keyword_info.search_volume,desc","keyword_data.keyword_info.cpc,desc"]' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/related_keywords/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/relevant_pages/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048 max: 0.048 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Relevant Pages description: 'Which pages of a `target` site earn its rankings, ranked by the traffic they bring. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to find the pages worth defending or expanding. For the keywords behind them use `post_dataforseo_labs_google_kw_for_site_live`; for the pages earning links rather than rankings, `post_dataforseo_backlinks_domain_pages_summary_live`.' operationId: post_dataforseo_labs_google_relevant_pages_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.target: type: string description: target domain in a POST array tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: relevant pages and related data tasks.result.page_address: type: string description: absolute URL of the relevant page tasks.result.metrics: type: object description: rankings and traffic metrics for the relevant page tasks.result.metrics.organic: type: object description: ranking and traffic data from organic search tasks.result.metrics.organic.pos_1: type: integer description: 'number of organic SERPs where the page ranks #1' tasks.result.metrics.organic.pos_2_3: type: integer description: 'number of organic SERPs where the page ranks #2-3' tasks.result.metrics.organic.pos_4_10: type: integer description: 'number of organic SERPs where the page ranks #4-10' tasks.result.metrics.organic.pos_11_20: type: integer description: 'number of organic SERPs where the page ranks #11-20' tasks.result.metrics.organic.pos_21_30: type: integer description: 'number of organic SERPs where the page ranks #21-30' tasks.result.metrics.organic.pos_31_40: type: integer description: 'number of organic SERPs where the page ranks #31-40' tasks.result.metrics.organic.pos_41_50: type: integer description: 'number of organic SERPs where the page ranks #41-50' tasks.result.metrics.organic.pos_51_60: type: integer description: 'number of organic SERPs where the page ranks #51-60' tasks.result.metrics.organic.pos_61_70: type: integer description: 'number of organic SERPs where the page ranks #61-70' tasks.result.metrics.organic.pos_71_80: type: integer description: 'number of organic SERPs where the page ranks #71-80' tasks.result.metrics.organic.pos_81_90: type: integer description: 'number of organic SERPs where the page ranks #81-90' tasks.result.metrics.organic.pos_91_100: type: integer description: 'number of organic SERPs where the page ranks #91-100' tasks.result.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the page calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.organic.count: type: integer description: total count of organic SERPs that contain the page tasks.result.metrics.organic.estimated_paid_traffic_cost: type: number description: estimated cost of converting organic search traffic into paid represents the estimated monthly cost (USD) of running ads for all keywords in the category that a page ranks for the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search learn more about how the metric is calculated in this help center article tasks.result.metrics.organic.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the page tasks.result.metrics.organic.is_up: type: integer description: rank went up indicates how many ranked elements of the page went up tasks.result.metrics.organic.is_down: type: integer description: rank went down indicates how many ranked elements of the page went down tasks.result.metrics.organic.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the page were previously presented in SERPs, but weren’t found during the last check tasks.result.metrics.organic.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.organic.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.organic.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.metrics.organic.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.metrics.organic.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.organic.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.metrics.organic.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.metrics.organic.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.metrics.organic.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.metrics.organic.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.metrics.paid: type: object description: ranking and traffic data from paid search tasks.result.metrics.paid.pos_1: type: integer description: 'number of paid SERPs where the page ranks #1' tasks.result.metrics.paid.pos_2_3: type: integer description: 'number of paid SERPs where the page ranks #2-3' tasks.result.metrics.paid.pos_4_10: type: integer description: 'number of paid SERPs where the page ranks #4-10' tasks.result.metrics.paid.pos_11_20: type: integer description: 'number of paid SERPs where the page ranks #11-20' tasks.result.metrics.paid.pos_21_30: type: integer description: 'number of paid SERPs where the page ranks #21-30' tasks.result.metrics.paid.pos_31_40: type: integer description: 'number of paid SERPs where the page ranks #31-40' tasks.result.metrics.paid.pos_41_50: type: integer description: 'number of paid SERPs where the page ranks #41-50' tasks.result.metrics.paid.pos_51_60: type: integer description: 'number of paid SERPs where the page ranks #51-60' tasks.result.metrics.paid.pos_61_70: type: integer description: 'number of paid SERPs where the page ranks #61-70' tasks.result.metrics.paid.pos_71_80: type: integer description: 'number of paid SERPs where the page ranks #71-80' tasks.result.metrics.paid.pos_81_90: type: integer description: 'number of paid SERPs where the page ranks #81-90' tasks.result.metrics.paid.pos_91_100: type: integer description: 'number of paid SERPs where the page ranks #91-100' tasks.result.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the page calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.paid.count: type: integer description: total count of paid SERPs that contain the page tasks.result.metrics.paid.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.paid.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the page tasks.result.metrics.paid.is_up: type: integer description: rank went up indicates how many ranked elements of the page went up tasks.result.metrics.paid.is_down: type: integer description: rank went down indicates how many ranked elements of the page went down tasks.result.metrics.paid.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the page were previously presented in SERPs, but weren’t found during the last check tasks.result.metrics.paid.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.paid.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.paid.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.metrics.paid.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.metrics.paid.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.paid.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.metrics.paid.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.metrics.paid.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.metrics.paid.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.metrics.paid.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.metrics.featured_snippet: type: object description: ranking and traffic data from the featured snippet results in Google SERP tasks.result.metrics.featured_snippet.pos_1: type: integer description: 'number of featured snippet items where the page ranks #1' tasks.result.metrics.featured_snippet.pos_2_3: type: integer description: 'number of featured snippet items where the page ranks #2-3' tasks.result.metrics.featured_snippet.pos_4_10: type: integer description: 'number of featured snippet items where the page ranks #4-10' tasks.result.metrics.featured_snippet.pos_11_20: type: integer description: 'number of featured snippet items where the page ranks #11-20' tasks.result.metrics.featured_snippet.pos_21_30: type: integer description: 'number of featured snippet items where the page ranks #21-30' tasks.result.metrics.featured_snippet.pos_31_40: type: integer description: 'number of featured snippet items where the page ranks #31-40' tasks.result.metrics.featured_snippet.pos_41_50: type: integer description: 'number of featured snippet items where the page ranks #41-50' tasks.result.metrics.featured_snippet.pos_51_60: type: integer description: 'number of featured snippet items where the page ranks #51-60' tasks.result.metrics.featured_snippet.pos_61_70: type: integer description: 'number of featured snippet items where the page ranks #61-70' tasks.result.metrics.featured_snippet.pos_71_80: type: integer description: 'number of featured snippet items where the page ranks #71-80' tasks.result.metrics.featured_snippet.pos_81_90: type: integer description: 'number of featured snippet items where the page ranks #81-90' tasks.result.metrics.featured_snippet.pos_91_100: type: integer description: 'number of featured snippet items where the page ranks #91-100' tasks.result.metrics.featured_snippet.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the page calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.featured_snippet.count: type: integer description: total count of featured snippet items that contain the page tasks.result.metrics.featured_snippet.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.featured_snippet.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the page tasks.result.metrics.featured_snippet.is_up: type: integer description: rank went up indicates how many ranked elements of the page went up tasks.result.metrics.featured_snippet.is_down: type: integer description: rank went down indicates how many ranked elements of the page went down tasks.result.metrics.featured_snippet.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the page were previously presented in SERPs, but weren’t found during the last check tasks.result.metrics.featured_snippet.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.featured_snippet.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.featured_snippet.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.metrics.featured_snippet.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.metrics.featured_snippet.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.featured_snippet.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.metrics.featured_snippet.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.metrics.featured_snippet.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.metrics.featured_snippet.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.metrics.featured_snippet.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.metrics.local_pack: type: object description: ranking and traffic data from the local pack results in SERP tasks.result.metrics.local_pack.pos_1: type: integer description: 'number of local pack items where the page ranks #1' tasks.result.metrics.local_pack.pos_2_3: type: integer description: 'number of local pack items where the page ranks #2-3' tasks.result.metrics.local_pack.pos_4_10: type: integer description: 'number of local pack items where the page ranks #4-10' tasks.result.metrics.local_pack.pos_11_20: type: integer description: 'number of local pack items where the page ranks #11-20' tasks.result.metrics.local_pack.pos_21_30: type: integer description: 'number of local pack items where the page ranks #21-30' tasks.result.metrics.local_pack.pos_31_40: type: integer description: 'number of local pack items where the page ranks #31-40' tasks.result.metrics.local_pack.pos_41_50: type: integer description: 'number of local pack items where the page ranks #41-50' tasks.result.metrics.local_pack.pos_51_60: type: integer description: 'number of local pack items where the page ranks #51-60' tasks.result.metrics.local_pack.pos_61_70: type: integer description: 'number of local pack items where the page ranks #61-70' tasks.result.metrics.local_pack.pos_71_80: type: integer description: 'number of local pack items where the page ranks #71-80' tasks.result.metrics.local_pack.pos_81_90: type: integer description: 'number of local pack items where the page ranks #81-90' tasks.result.metrics.local_pack.pos_91_100: type: integer description: 'number of local pack items where the page ranks #91-100' tasks.result.metrics.local_pack.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the page calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.local_pack.count: type: integer description: total count of local pack items that contain the page tasks.result.metrics.local_pack.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the page ranks for learn more about how the metric is calculated in this help center article tasks.result.metrics.local_pack.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the page tasks.result.metrics.local_pack.is_up: type: integer description: rank went up indicates how many ranked elements of the page went up tasks.result.metrics.local_pack.is_down: type: integer description: rank went down indicates how many ranked elements of the page went down tasks.result.metrics.local_pack.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the page were previously presented in SERPs, but weren’t found during the last check tasks.result.metrics.local_pack.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.local_pack.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.local_pack.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.metrics.local_pack.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.metrics.local_pack.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.metrics.local_pack.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.metrics.local_pack.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.metrics.local_pack.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.metrics.local_pack.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.metrics.local_pack.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain required field the domain name of the target website the domain should be specified without https:// and www. location_name: type: string description: 'full name of the location optional field if you use this field, you don’t need to specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: United Kingdom' location_code: type: integer description: 'location code optional field if you use this field, you don’t need to specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: 2840' language_name: type: string description: 'full name of the language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: English' language_code: type: string description: 'language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: en' item_types: type: array items: type: string description: 'display results by item type optional field indicates the type of search results included in the response Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response; possible values: ["organic", "paid", "featured_snippet", "local_pack"] default value: ["organic", "paid"]' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' limit: type: integer description: 'the maximum number of returned pages optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned pages optional field default value: 0 if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages' historical_serp_mode: type: string description: 'data collection mode optional field you can use this field to filter the results; possible types of filtering: live — return metrics for SERPs in which the specified target currently has ranking results; lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn’t have them during the last check; all — return metrics for both types of SERPs. default value: live' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true, only core keywords will be returned, all highly similar keywords will be excluded; default value: false' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in example: ["metrics.paid.count",">",0] [["metrics.organic.count",">",50],"and",["metrics.organic.pos_1","",0]] [[""metrics.organic.count",">",50"], "and", [["metrics.organic.pos_1","",0],"or",["metrics.organic.pos_2_3","",0]]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to specify a sorting type example: ["metrics.paid.etv,asc"] Note: you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["metrics.organic.etv,desc","metrics.paid.count,asc"] default rule: ["metrics.organic.count,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/relevant_pages/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/search_intent/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.002424 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Search Intent description: 'Classifies `keywords` as informational, navigational, commercial or transactional. Returns `language_code`, `items_count` and `items`. Measured at 673 bytes and **$0.001212 - ten times cheaper than everything else in this family**, so classify freely. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Intent decides what a page has to be before volume decides whether it is worth writing; pair it with `post_dataforseo_labs_google_keyword_overview_live`.' operationId: post_dataforseo_labs_google_search_intent_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: array of items with relevant traffic estimation data tasks.result.items.keyword: type: string description: target keyword in a POST array tasks.result.items.keyword_intent: type: object description: search intent data relevant for the specified keyword tasks.result.items.keyword_intent.label: type: string description: 'search intent name possible values: informational, navigational, commercial, transactional' tasks.result.items.keyword_intent.probability: type: number description: search intent probability 1 indicates the highest probability tasks.result.items.secondary_keyword_intents: type: array items: type: string description: contains objects with other possible search intents for the specified keyword tasks.result.items.secondary_keyword_intents.label: type: string description: 'search intent name possible values: informational, navigational, commercial, transactional' tasks.result.items.secondary_keyword_intents.probability: type: number description: search intent probability '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: 'target keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000; the keywords will be converted to lowercase format learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' language_name: type: string description: 'full name of the language required field if don’t specify language_code you can receive the list of available languages with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages Note: this endpoint currently supports the following languages only: Arabic, ar, Chinese(Traditional), zh-TW, Czech, cs, Danish, da, Dutch, nl, English, en, Finnish, fi, French, fr, German, de, Hebrew, he, Hindi, hi, Italian, it, Japanese, ja, Korean, ko, Malay, ms, Norwegian(Bokmål), nb, Polish, pl, Portuguese, pt, Romanian, ro, Russian, ru, Spanish, es, Swedish, sv, Thai, th, Ukrainian, uk, Vietnamese, vi, Bulgarian, bg, Croatian, hr, Serbian, sr, Slovenian, sl, Bosnian, bs, Greek, el, Hungarian, hu, Slovak, sk, Turkish, tr example: English' language_code: type: string description: 'language code required field if don’t specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages Note: this endpoint currently supports these languages only; example: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/search_intent/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/serp_competitors/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.0384 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: SERP Competitors description: 'The domains ranking alongside you for a set of `keywords`, with how many they share. Returns `se_type`, `seed_keywords`, `total_count`, `items_count` and `items`. Measured at 894 bytes. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ These are **search** competitors, decided by shared rankings. The link-graph equivalent is `post_dataforseo_backlinks_competitors_live`, and the two lists often disagree - which is itself informative.' operationId: post_dataforseo_labs_google_serp_competitors_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.seed_keywords: type: array items: type: string description: keywords specified in the request keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character) tasks.result.location_code: type: integer description: location code in a POST array if there is no data, then the value is null tasks.result.language_code: type: string description: language code in a POST array if there is no data, then the value is null tasks.result.total_count: type: integer description: the total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains detected SERP competitors and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.domain: type: string description: domain name of the detected SERP competitor tasks.result.items.avg_position: type: integer description: the average position of the domain for the specified keywords the arithmetic mean of values in the keywords_positions array tasks.result.items.median_position: type: integer description: the median position of the domain for the specified keywords the median of the values in the keywords_positions array tasks.result.items.rating: type: integer description: the margin between the greatest possible and actual keyword positions represents the relative visibility rate of the domain in SERP for the specified keywords calculated as sum(100-keywords_positions) tasks.result.items.etv: type: number description: estimated traffic volume represents the estimated monthly traffic that specified keywords are driving to the website calculated as the sum of the products of the specified keywords’ search volume values and CTR (click-through-rate) rates at certain positions in SERP learn more about how the metric is calculated in this help center article tasks.result.items.keywords_count: type: integer description: the number of specified keywords the domain has positions for in SERPs tasks.result.items.visibility: type: number description: SERP visibility rate represents the website visibility rate based on the SERP positions of the specified keywords Keywords with positions in the range from 1 to 10 are assigned the visibility index from 1 to 0.1, respectively Keywords with positions in the range from 11 to 20 have the fixed visibility index of 0.05 keywords with positions from 20 to 100 have the visibility index equal to 0 tasks.result.items.relevant_serp_items: type: integer description: the number of SERP elements relevant to the domain represents the number of search results in SERP relevant to the domain for the specified keywords tasks.result.items.keywords_positions: type: object description: keyword positions SERP positions the related domain holds in SERP for the specified keywords '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keywords: type: array items: type: string description: keywords array required field the results will be based on the keywords you specify in this array UTF-8 encoding; the keywords will be converted to lowercase format; you can specify the maximum of 200 keywords learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with location_name parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'unique location identifier required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'unique language identifier required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' include_subdomains: type: boolean description: 'indicates if the subdomains will be included in the search optional field if set to false, the subdomains will be ignored default value: true' item_types: type: array items: type: string description: 'search results type indicates type of search results included in the response optional field possible values: ["organic", "paid", "featured_snippet", "local_pack"] default value: ["organic", "paid"]' limit: type: integer description: 'the maximum number of returned domains optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned domains optional field default value: 0 if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like, not_like you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters example: ["median_position","in",[1,10]] [["median_position","in",[1,10]],"and",["domain","not_like","%wikipedia.org%"]] [["domain","not_like","%wikipedia.org%"], "and", [["relevant_serp_items",">",0],"or",["median_position","in",[1,10]]]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order the comma is used as a separator example: ["avg_position,asc"] default rule: ["rating,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["avg_position,asc","etv,desc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keywords allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/serp_competitors/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/subdomains/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Subdomains description: 'The subdomains of a `target` and the search footprint of each. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Useful when a domain''s traffic is concentrated somewhere other than www - a docs or blog subdomain carrying the site is invisible in `post_dataforseo_labs_google_domain_rank_overview_live`.' operationId: post_dataforseo_labs_google_subdomains_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.target: type: string description: domain in a POST array tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains subdomains and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.subdomain: type: string description: returned subdomain tasks.result.items.metrics: type: object description: ranking data relevant to subdomain tasks.result.items.metrics.organic: type: object description: ranking and traffic data from organic search tasks.result.items.metrics.organic.pos_1: type: integer description: 'number of organic SERPs where the domain ranks #1' tasks.result.items.metrics.organic.pos_2_3: type: integer description: 'number of organic SERPs where the domain ranks #2-3' tasks.result.items.metrics.organic.pos_4_10: type: integer description: 'number of organic SERPs where the domain ranks #4-10' tasks.result.items.metrics.organic.pos_11_20: type: integer description: 'number of organic SERPs where the domain ranks #11-20' tasks.result.items.metrics.organic.pos_21_30: type: integer description: 'number of organic SERPs where the domain ranks #21-30' tasks.result.items.metrics.organic.pos_31_40: type: integer description: 'number of organic SERPs where the domain ranks #31-40' tasks.result.items.metrics.organic.pos_41_50: type: integer description: 'number of organic SERPs where the domain ranks #41-50' tasks.result.items.metrics.organic.pos_51_60: type: integer description: 'number of organic SERPs where the domain ranks #51-60' tasks.result.items.metrics.organic.pos_61_70: type: integer description: 'number of organic SERPs where the domain ranks #61-70' tasks.result.items.metrics.organic.pos_71_80: type: integer description: 'number of organic SERPs where the domain ranks #71-80' tasks.result.items.metrics.organic.pos_81_90: type: integer description: 'number of organic SERPs where the domain ranks #81-90' tasks.result.items.metrics.organic.pos_91_100: type: integer description: 'number of organic SERPs where the domain ranks #91-100' tasks.result.items.metrics.organic.etv: type: number description: estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.count: type: integer description: total count of organic SERPs that contain the domain tasks.result.items.metrics.organic.estimated_paid_traffic_cost: type: number description: estimated cost of converting organic search traffic into paid represents the estimated monthly cost (USD) of running ads for all keywords in the category that a domain ranks for the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.metrics.organic.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.metrics.organic.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.metrics.organic.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.organic.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.metrics.organic.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.metrics.organic.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.organic.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.metrics.organic.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.metrics.organic.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.metrics.organic.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.metrics.organic.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.metrics.paid: type: object description: ranking and traffic data from paid search tasks.result.items.metrics.paid.pos_1: type: integer description: 'number of paid SERPs where the domain ranks #1' tasks.result.items.metrics.paid.pos_2_3: type: integer description: 'number of paid SERPs where the domain ranks #2-3' tasks.result.items.metrics.paid.pos_4_10: type: integer description: 'number of paid SERPs where the domain ranks #4-10' tasks.result.items.metrics.paid.pos_11_20: type: integer description: 'number of paid SERPs where the domain ranks #11-20' tasks.result.items.metrics.paid.pos_21_30: type: integer description: 'number of paid SERPs where the domain ranks #21-30' tasks.result.items.metrics.paid.pos_31_40: type: integer description: 'number of paid SERPs where the domain ranks #31-40' tasks.result.items.metrics.paid.pos_41_50: type: integer description: 'number of paid SERPs where the domain ranks #41-50' tasks.result.items.metrics.paid.pos_51_60: type: integer description: 'number of paid SERPs where the domain ranks #51-60' tasks.result.items.metrics.paid.pos_61_70: type: integer description: 'number of paid SERPs where the domain ranks #61-70' tasks.result.items.metrics.paid.pos_71_80: type: integer description: 'number of paid SERPs where the domain ranks #71-80' tasks.result.items.metrics.paid.pos_81_90: type: integer description: 'number of paid SERPs where the domain ranks #81-90' tasks.result.items.metrics.paid.pos_91_100: type: integer description: 'number of paid SERPs where the domain ranks #91-100' tasks.result.items.metrics.paid.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.count: type: integer description: total count of paid SERPs that contain the domain tasks.result.items.metrics.paid.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.metrics.paid.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.metrics.paid.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.metrics.paid.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.paid.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.metrics.paid.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.metrics.paid.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.paid.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.metrics.paid.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.metrics.paid.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.metrics.paid.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.metrics.paid.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.metrics.featured_snippet: type: object description: ranking and traffic data from the featured snippet results in Google SERP tasks.result.items.metrics.featured_snippet.pos_1: type: integer description: 'number of featured snippet items where the domain ranks #1' tasks.result.items.metrics.featured_snippet.pos_2_3: type: integer description: 'number of featured snippet items where the domain ranks #2-3' tasks.result.items.metrics.featured_snippet.pos_4_10: type: integer description: 'number of featured snippet items where the domain ranks #4-10' tasks.result.items.metrics.featured_snippet.pos_11_20: type: integer description: 'number of featured snippet items where the domain ranks #11-20' tasks.result.items.metrics.featured_snippet.pos_21_30: type: integer description: 'number of featured snippet items where the domain ranks #21-30' tasks.result.items.metrics.featured_snippet.pos_31_40: type: integer description: 'number of featured snippet items where the domain ranks #31-40' tasks.result.items.metrics.featured_snippet.pos_41_50: type: integer description: 'number of featured snippet items where the domain ranks #41-50' tasks.result.items.metrics.featured_snippet.pos_51_60: type: integer description: 'number of featured snippet items where the domain ranks #51-60' tasks.result.items.metrics.featured_snippet.pos_61_70: type: integer description: 'number of featured snippet items where the domain ranks #61-70' tasks.result.items.metrics.featured_snippet.pos_71_80: type: integer description: 'number of featured snippet items where the domain ranks #71-80' tasks.result.items.metrics.featured_snippet.pos_81_90: type: integer description: 'number of featured snippet items where the domain ranks #81-90' tasks.result.items.metrics.featured_snippet.pos_91_100: type: integer description: 'number of featured snippet items where the domain ranks #91-100' tasks.result.items.metrics.featured_snippet.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.count: type: integer description: total count of featured snippet items that contain the domain tasks.result.items.metrics.featured_snippet.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.metrics.featured_snippet.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.metrics.featured_snippet.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.metrics.featured_snippet.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.featured_snippet.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.metrics.featured_snippet.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.metrics.featured_snippet.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.featured_snippet.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.metrics.featured_snippet.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.metrics.featured_snippet.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.metrics.featured_snippet.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.metrics.featured_snippet.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.metrics.local_pack: type: object description: ranking and traffic data from the local pack results in SERP tasks.result.items.metrics.local_pack.pos_1: type: integer description: 'number of local pack items where the domain ranks #1' tasks.result.items.metrics.local_pack.pos_2_3: type: integer description: 'number of local pack items where the domain ranks #2-3' tasks.result.items.metrics.local_pack.pos_4_10: type: integer description: 'number of local pack items where the domain ranks #4-10' tasks.result.items.metrics.local_pack.pos_11_20: type: integer description: 'number of local pack items where the domain ranks #11-20' tasks.result.items.metrics.local_pack.pos_21_30: type: integer description: 'number of local pack items where the domain ranks #21-30' tasks.result.items.metrics.local_pack.pos_31_40: type: integer description: 'number of local pack items where the domain ranks #31-40' tasks.result.items.metrics.local_pack.pos_41_50: type: integer description: 'number of local pack items where the domain ranks #41-50' tasks.result.items.metrics.local_pack.pos_51_60: type: integer description: 'number of local pack items where the domain ranks #51-60' tasks.result.items.metrics.local_pack.pos_61_70: type: integer description: 'number of local pack items where the domain ranks #61-70' tasks.result.items.metrics.local_pack.pos_71_80: type: integer description: 'number of local pack items where the domain ranks #71-80' tasks.result.items.metrics.local_pack.pos_81_90: type: integer description: 'number of local pack items where the domain ranks #81-90' tasks.result.items.metrics.local_pack.pos_91_100: type: integer description: 'number of local pack items where the domain ranks #91-100' tasks.result.items.metrics.local_pack.etv: type: number description: estimated traffic volume estimated paid monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.count: type: integer description: total count of local pack items that contain the domain tasks.result.items.metrics.local_pack.estimated_paid_traffic_cost: type: number description: estimated cost of monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values of all keywords in the category that the domain ranks for learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.is_new: type: integer description: number of new ranked elements indicates how many new ranked elements were found for the indicated target tasks.result.items.metrics.local_pack.is_up: type: integer description: rank went up indicates how many ranked elements of the indicated target went up tasks.result.items.metrics.local_pack.is_down: type: integer description: rank went down indicates how many ranked elements of the indicated target went down tasks.result.items.metrics.local_pack.is_lost: type: integer description: lost ranked elements indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren’t found during the last check tasks.result.items.metrics.local_pack.clickstream_etv: type: integer description: estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.clickstream_gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.clickstream_gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.metrics.local_pack.clickstream_gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.metrics.local_pack.clickstream_age_distribution: type: object description: distribution of clickstream-based metrics by age to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article tasks.result.items.metrics.local_pack.clickstream_age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.metrics.local_pack.clickstream_age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.metrics.local_pack.clickstream_age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.metrics.local_pack.clickstream_age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.metrics.local_pack.clickstream_age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain required field the domain name of the target website the domain should be specified without https:// and www. location_name: type: string description: 'full name of the location optional field if you use this field, you don’t need to specify location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: United Kingdom' location_code: type: integer description: 'location code optional field if you use this field, you don’t need to specify location_name you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available locations example: 2840' language_name: type: string description: 'full name of the language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: English' language_code: type: string description: 'language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages ignore this field to get the results for all available languages example: en' item_types: type: array items: type: string description: 'display results by item type optional field indicates the type of search results included in the response Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response; possible values: ["organic", "paid", "featured_snippet", "local_pack"] default value: ["organic", "paid"]' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' historical_serp_mode: type: string description: 'data collection mode optional field you can use this field to filter the results; possible types of filtering: live — return metrics for SERPs in which the specified target currently has ranking results; lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn’t have them during the last check; all — return metrics for both types of SERPs. default value: live' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true, only core keywords will be returned, all highly similar keywords will be excluded; default value: false' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in example: ["metrics.paid.count",">",0] [["metrics.paid.count",">",0],"and",["metrics.paid.etv",">","50"]] [["metrics.organic.count",">","10"], "and", [["metrics.organic.pos_1","",0],"or",["metrics.organic.pos_2_3","",0]]] for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to specify a sorting type example: ["metrics.paid.etv,asc"] Note: you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["metrics.organic.etv,desc","metrics.paid.count,asc"] default rule: ["metrics.organic.count,desc"] Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array' limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/subdomains/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/google/top_searches/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02472 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Top Searches description: 'The highest-volume keywords in a location, unfiltered by seed or site. Pages with `limit`, `offset` and `offset_token`; use the token past the first pages. 💰 Measured at $0.01212 upstream, essentially the flat rate billed. **This family is the one to reach for by default**: the google_ads endpoints in seo-keywords answer similar questions at $0.09 - seven times more - and return megabytes with no way to cap them, where this one takes a `limit`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the discovery end of the family: use it when there is no seed keyword yet, then narrow with `post_dataforseo_labs_google_keyword_ideas_live`.' operationId: post_dataforseo_labs_google_top_searches_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.se_type: type: string description: search engine type tasks.result.location_code: type: integer description: location code in a POST array tasks.result.language_code: type: string description: language code in a POST array tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.offset: type: integer description: current offset value tasks.result.offset_token: type: string description: 'offset token for subsequent requests you can use the string provided in this field to get the subsequent results of the initial task; note: offset_token values are unique for each subsequent task' tasks.result.items: type: array items: type: string description: contains keywords and related data tasks.result.items.se_type: type: string description: search engine type tasks.result.items.keyword: type: string description: keyword tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.keyword_info: type: object description: keyword data for the returned keyword tasks.result.items.keyword_info.se_type: type: string description: search engine type tasks.result.items.keyword_info.last_updated_time: type: string description: 'date and time when keyword data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info.competition: type: number description: competition represents the relative amount of competition associated with the given keyword; the value is based on Google Ads data and can be between 0 and 1 (inclusive) tasks.result.items.keyword_info.competition_level: type: string description: 'competition level represents the relative level of competition associated with the given keyword in paid SERP only; possible values: LOW, MEDIUM, HIGH if competition level is unknown, the value is null; learn more about the metric in this help center article' tasks.result.items.keyword_info.cpc: type: number description: cost-per-click represents the average cost per click (USD) historically paid for the keyword tasks.result.items.keyword_info.search_volume: type: integer description: average monthly search volume rate represents the (approximate) number of searches for the given keyword idea on google.com tasks.result.items.keyword_info.low_top_of_page_bid: type: number description: minimum bid for the ad to be displayed at the top of the first page indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.high_top_of_page_bid: type: number description: maximum bid for the ad to be displayed at the top of the first page indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers) the value may differ depending on the location specified in a POST request tasks.result.items.keyword_info.categories: type: array items: type: string description: product and service categories you can download the full list of possible categories tasks.result.items.keyword_info.monthly_searches: type: array items: type: string description: monthly searches represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations tasks.result.items.keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info.monthly_searches.search_volume: type: integer description: monthly average search volume rate tasks.result.items.keyword_info.search_volume_trend: type: object description: search volume trend changes represents search volume change in percent compared to the previous period tasks.result.items.keyword_info.search_volume_trend.monthly: type: integer description: search volume change in percent compared to the previous month tasks.result.items.keyword_info.search_volume_trend.quarterly: type: integer description: search volume change in percent compared to the previous quarter tasks.result.items.keyword_info.search_volume_trend.yearly: type: integer description: search volume change in percent compared to the previous year tasks.result.items.clickstream_keyword_info: type: object description: clickstream data for the returned keyword to retrieve results for this field, the parameter include_clickstream_data must be set to true tasks.result.items.clickstream_keyword_info.search_volume: type: integer description: monthly average clickstream search volume rate tasks.result.items.clickstream_keyword_info.last_updated_time: type: string description: 'date and time when the clickstream dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”' tasks.result.items.clickstream_keyword_info.gender_distribution: type: object description: distribution of estimated clickstream-based metrics by gender learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.gender_distribution.female: type: integer description: number of female users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.gender_distribution.male: type: integer description: number of male users in the relevant clickstream dataset tasks.result.items.clickstream_keyword_info.age_distribution: type: object description: distribution of clickstream-based metrics by age learn more about how the metric is calculated in this help center article tasks.result.items.clickstream_keyword_info.age_distribution.18-24: type: integer description: number of users in the relevant clickstream dataset that fall within the 18-24 age range tasks.result.items.clickstream_keyword_info.age_distribution.25-34: type: integer description: number of users in the relevant clickstream dataset that fall within the 25-34 age range tasks.result.items.clickstream_keyword_info.age_distribution.35-44: type: integer description: number of users in the relevant clickstream dataset that fall within the 35-44 age range tasks.result.items.clickstream_keyword_info.age_distribution.45-54: type: integer description: number of users in the relevant clickstream dataset that fall within the 45-54 age range tasks.result.items.clickstream_keyword_info.age_distribution.55-64: type: integer description: number of users in the relevant clickstream dataset that fall within the 55-64 age range tasks.result.items.clickstream_keyword_info.monthly_searches: type: array items: type: string description: monthly clickstream search volume rates array of objects with clickstream search volume rates in a certain month of a year tasks.result.items.clickstream_keyword_info.monthly_searches.year: type: integer description: year tasks.result.items.clickstream_keyword_info.monthly_searches.month: type: integer description: month tasks.result.items.clickstream_keyword_info.monthly_searches.search_volume: type: integer description: clickstream-based search volume rate in a certain month of a year tasks.result.items.keyword_properties: type: object description: additional information about the keyword tasks.result.items.keyword_properties.se_type: type: string description: search engine type tasks.result.items.keyword_properties.core_keyword: type: string description: main keyword in a group contains the main keyword in a group determined by the synonym clustering algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword tasks.result.items.keyword_properties.synonym_clustering_algorithm: type: string description: 'the algorithm used to identify synonyms possible values: keyword_metrics – indicates the algorithm based on keyword_info parameters text_processing – indicates the text-based algorithm if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword' tasks.result.items.keyword_properties.keyword_difficulty: type: integer description: difficulty of ranking in the first top-10 organic results for a keyword indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100; calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP; learn more about the metric in this help center guide tasks.result.items.keyword_properties.detected_language: type: string description: detected language of the keyword indicates the language of the keyword as identified by our system tasks.result.items.keyword_properties.is_another_language: type: boolean description: detected language of the keyword is different from the set language if true, the language set in the request does not match the language determined by our system for a given keyword tasks.result.items.keyword_properties.words_count: type: integer description: number of words in the keyword indicates how many words the keyword consists of tasks.result.items.serp_info: type: object description: Google SERP data the value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database tasks.result.items.serp_info.se_type: type: string description: search engine type tasks.result.items.serp_info.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.serp_info.serp_item_types: type: array items: type: string description: 'types of search results in SERP contains types of search results (items) found in SERP possible item types: answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview; note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements' tasks.result.items.serp_info.se_results_count: type: integer description: number of search results for the returned keyword tasks.result.items.serp_info.last_updated_time: type: string description: 'date and time when SERP data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.avg_backlinks_info: type: object description: backlink data for the returned keyword this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword tasks.result.items.avg_backlinks_info.se_type: type: string description: search engine type tasks.result.items.avg_backlinks_info.backlinks: type: number description: average number of backlinks tasks.result.items.avg_backlinks_info.dofollow: type: number description: average number of dofollow links tasks.result.items.avg_backlinks_info.referring_pages: type: number description: average number of referring pages tasks.result.items.avg_backlinks_info.referring_domains: type: number description: average number of referring domains tasks.result.items.avg_backlinks_info.referring_main_domains: type: number description: average number of referring main domains tasks.result.items.avg_backlinks_info.rank: type: number description: average rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.main_domain_rank: type: number description: average main domain rank learn more about the metric and its calculation formula in this help center article tasks.result.items.avg_backlinks_info.last_updated_time: type: string description: 'date and time when backlink data was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.search_intent_info: type: object description: search intent info for the returned keyword learn about search intent in this help center article tasks.result.items.search_intent_info.se_type: type: string description: 'search engine type possible values: google' tasks.result.items.search_intent_info.main_intent: type: string description: 'main search intent possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.foreign_intent: type: array items: type: string description: 'supplementary search intents possible values: informational, navigational, commercial, transactional' tasks.result.items.search_intent_info.last_updated_time: type: string description: 'date and time when search intent data was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info_normalized_with_bing: type: object description: contains keyword search volume normalized with Bing search volume tasks.result.items.keyword_info_normalized_with_bing.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info_normalized_with_bing.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_info_normalized_with_bing.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with Bing data tasks.result.items.keyword_info_normalized_with_bing.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_info_normalized_with_bing.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info_normalized_with_bing.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info_normalized_with_bing.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year tasks.result.items.keyword_info_normalized_with_clickstream: type: object description: contains keyword search volume normalized with clickstream data tasks.result.items.keyword_info_normalized_with_clickstream.last_updated_time: type: string description: 'date and time when the dataset was updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.keyword_info_normalized_with_clickstream.search_volume: type: integer description: current search volume rate of a keyword tasks.result.items.keyword_info_normalized_with_clickstream.is_normalized: type: boolean description: keyword info is normalized if true, values are normalized with clickstream data tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches: type: integer description: monthly search volume rates array of objects with search volume rates in a certain month of a year tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches.year: type: integer description: year tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches.month: type: integer description: month tasks.result.items.keyword_info_normalized_with_clickstream.monthly_searches.search_volume: type: integer description: search volume rate in a certain month of a year '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: location_name: type: string description: 'full name of the location required field if you don’t specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840' language_name: type: string description: 'full name of the language required field if you don’t specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en' include_serp_info: type: boolean description: 'include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false' include_clickstream_data: type: boolean description: 'include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article' ignore_synonyms: type: boolean description: 'ignore highly similar keywords optional field if set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, match, not_match, ilike, not_ilike, like,not_like you can use the % operator with like and not_like,as well as ilike and not_ilike to match any string of zero or more characters example: ["keyword_info.search_volume",">",0] [["keyword_info.search_volume","in",[0,1000]], "and", ["keyword_info.competition_level","=","LOW"]] [["keyword_info.search_volume",">",100], "and", [["keyword_info.cpc"," for more information about filters, please refer to Dataforseo Labs – Filters or this help center guide' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["keyword_info.competition,desc"] default rule: ["keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_info.search_volume,desc","keyword_info.cpc,desc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response limit: type: integer description: 'the maximum number of returned keywords optional field note: you can get more than 1000 results by using the offset_token provided in the response to each subsequent request default value: 1000 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'offset token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task. learn more about this parameter on our Help Center' anyOf: - allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - required: - offset_token tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/google/top_searches/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/dataforseo_labs/status: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: DataForSEO Labs Status description: 'How current Labs'' data is, per marketplace: `google`, `bing` and `amazon`. Measured at 496 bytes, the smallest response in this family. Free: upstream cost is 0. Worth a call before a decision that rests on freshness - every other number in this family is only as current as this says.' operationId: get_dataforseo_labs_status responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: the data specified in the API call tasks.result: type: array items: type: string description: array of results tasks.result.google: type: object description: update information for the Google endpoints tasks.result.google.date_update: type: string description: 'update date of the Google endpoints indicates the last date when the Google endpoints of DataForSEO Labs API were updated; example: 2022-05-16' tasks.result.bing: type: object description: update information for the Bing endpoints tasks.result.bing.date_update: type: string description: 'update date of the Bing endpoints indicates the last date when the Bing endpoints of DataForSEO Labs API were updated; example: 2022-05-16' tasks.result.amazon: type: object description: update information for the Amazon endpoints tasks.result.amazon.date_update: type: string description: 'update date of the Amazon endpoints indicates the last date when the Amazon endpoints of DataForSEO Labs API were updated; example: 2022-05-23' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/dataforseo_labs/status source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/anchors/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.04872 max: 0.0552 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Anchors description: 'The anchor texts pointing at one `target`, one row per distinct anchor with `anchor`, `rank`, `backlinks`, `first_seen`, `lost_date`, `backlinks_spam_score`, `broken_backlinks` and `broken_pages`. Measured at 1.2 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to see how the web describes a site - over-optimised anchors show up here. The link-level view is `post_dataforseo_backlinks_backlinks_live`; the domain-level one is `post_dataforseo_backlinks_referring_domains_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_anchors_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target in the post array tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_anchor’ tasks.result.items.anchor: type: string description: anchor of the backlink tasks.result.items.rank: type: integer description: rank of the anchor links rank volume that referring websites pass to the target through links with a particular anchor rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: indicates the number of backlinks tasks.result.items.first_seen: type: string description: 'date and time when our crawler found the backlink with this anchor for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.lost_date: type: string description: 'date and time when the last backlink with this anchor was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.backlinks_spam_score: type: integer description: average spam score of all backlinks with this anchor learn more about how the metric is calculated on this help center page tasks.result.items.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the target tasks.result.items.broken_pages: type: integer description: number of broken pages number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to tasks.result.items.referring_domains: type: integer description: indicates the number of referring domains tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.items.referring_main_domains: type: integer description: indicates the number of referring main domains tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.items.referring_ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.referring_subnets: type: integer description: number of referring subnetworks tasks.result.items.referring_pages: type: integer description: indicates the number of pages pointing to target with this anchor tasks.result.items.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.items.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and link count per each semantic location you can get the full list of semantic elements here examples: article, section, summary' tasks.result.items.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target with this anchor '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get anchors for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) limit: type: integer description: 'the maximum number of returned anchors optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned anchors optional field default value: 0 if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["referring_links_types.anchors",">","1"] [["broken_pages",">","2"], "and", ["backlinks",">","10"]] [["first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["anchor","like","%seo%"],"or",["referring_domains",">","10"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["backlinks,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["backlinks,desc","rank,asc"]' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": [["dofollow", "=", true]]' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the target will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates whether the backlinks from subdomains of the target are excluded optional field if set to false, the backlinks from subdomains of the target will be ommited and you won’t receive the same domain in the response; default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/anchors/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/backlinks/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048936 max: 0.084 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlinks description: 'The individual inbound links to one `target`, one row per link. Returns `total_count`, `items_count`, `items` and a `search_after_token` for paging - use that rather than `offset` past the first few pages. `mode` and `custom_mode` control grouping, `backlinks_status_type` selects live, lost or all. Measured at 2.5 KB for one link. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For counts rather than rows use `post_dataforseo_backlinks_summary_live`; for the linking domains grouped, `post_dataforseo_backlinks_referring_domains_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_backlinks_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target domain in a POST array tasks.result.mode: type: string description: mode specified in a POST array tasks.result.custom_mode: type: object description: custom mode specified in a POST array tasks.result.total_count: type: integer description: total amount of results relevant the request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.type: type: string description: type of element = ‘backlink’ tasks.result.items.domain_from: type: string description: domain referring to the target domain or webpage tasks.result.items.url_from: type: string description: URL of the page where the backlink is found tasks.result.items.url_from_https: type: boolean description: indicates whether the referring URL is secured with HTTPS if true, the referring URL is secured with HTTPS tasks.result.items.domain_to: type: string description: domain the backlink is pointing to tasks.result.items.url_to: type: string description: URL the backlink is pointing to tasks.result.items.url_to_https: type: boolean description: indicates if the URL the backlink is pointing to is secured with HTTPS if true, the URL is secured with HTTPS tasks.result.items.tld_from: type: string description: top-level domain of the referring URL tasks.result.items.is_new: type: boolean description: indicates whether the backlink is new if true, the backlink was found on the page last time our crawler visited it tasks.result.items.is_lost: type: boolean description: indicates whether the backlink was removed if true, the backlink or the entire page was removed tasks.result.items.backlink_spam_score: type: integer description: spam score of the backlink learn more about how the metric is calculated on this help center page tasks.result.items.rank: type: integer description: backlink rank rank that the given backlink passes to the target rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.page_from_rank: type: integer description: page rank of the referring page page_from_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.domain_from_rank: type: integer description: domain rank of the referring domain domain_from_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.domain_from_platform_type: type: array items: type: string description: 'platform types of the referring domain possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.domain_from_is_ip: type: boolean description: indicates if the domain is IP if true, the domain functions as an IP address and does not have a domain name tasks.result.items.domain_from_ip: type: string description: IP address of the referring domain tasks.result.items.domain_from_country: type: string description: ISO country code of the referring domain tasks.result.items.page_from_external_links: type: integer description: number of external links found on the referring page tasks.result.items.page_from_internal_links: type: integer description: number of internal links found on the referring page tasks.result.items.page_from_size: type: integer description: 'size of the referring page, in bytes example: 63357' tasks.result.items.page_from_encoding: type: string description: 'character encoding of the referring page example: utf-8' tasks.result.items.page_from_language: type: string description: 'language of the referring page in ISO 639-1 format example: en' tasks.result.items.page_from_title: type: string description: title of the referring page tasks.result.items.page_from_status_code: type: integer description: 'HTTP status code returned by the referring page example: 200' tasks.result.items.first_seen: type: string description: 'date and time when our crawler found the backlink for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.prev_seen: type: string description: 'previous to the most recent date when our crawler visited the backlink in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.last_seen: type: string description: 'most recent date when our crawler visited the backlink in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.item_type: type: string description: 'link type possible values: anchor, image, meta, canonical, alternate, redirect' tasks.result.items.attributes: type: array items: type: string description: 'link attributes of the referring links example: nofollow' tasks.result.items.dofollow: type: boolean description: indicates whether the backlink is dofollow if false, the backlink is nofollow tasks.result.items.original: type: boolean description: indicates whether the backlink was present on the referring page when our crawler first visited it tasks.result.items.alt: type: string description: alternative text of the image this field will be null if backlink type is not image tasks.result.items.image_url: type: string description: URL of the image the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available) tasks.result.items.anchor: type: string description: anchor text of the backlink tasks.result.items.text_pre: type: string description: snippet before the anchor text tasks.result.items.text_post: type: string description: snippet after the anchor text tasks.result.items.semantic_location: type: string description: 'indicates semantic element in HTML where the backlink is found you can get the full list of semantic elements here examples: article, section, summary' tasks.result.items.links_count: type: integer description: number of identical backlinks found on the referring page tasks.result.items.group_count: type: integer description: indicates total number of backlinks from this domain for example, if mode is set to one_per_domain, this field will indicate the total number of backlinks coming from this domain tasks.result.items.is_broken: type: boolean description: indicates whether the backlink is broken if true, the backlink is pointing to a page responding with a 4xx or 5xx status code tasks.result.items.url_to_status_code: type: integer description: 'status code of the referenced page if the value is null, our crawler hasn’t yet visited the webpage the link is pointing to example: 200' tasks.result.items.url_to_spam_score: type: integer description: spam score of the referenced page if the value is null, our crawler hasn’t yet visited the webpage the link is pointing to; learn more about how the metric is calculated on this help center page tasks.result.items.url_to_redirect_target: type: string description: target url of the redirect target page the redirect is pointing to tasks.result.items.is_indirect_link: type: boolean description: indicates whether the backlink is an indirect link if true, the backlink is an indirect link pointing to a page that either redirects to url_to, or points to a canonical page tasks.result.items.indirect_link_path: type: array items: type: string description: indirect link path indicates a URL or a sequence of URLs that lead to url_to tasks.result.items.indirect_link_path.type: type: string description: 'indirect link type possible values: redirect, canonical' tasks.result.items.indirect_link_path.status_code: type: integer description: HTTP status code of the URL tasks.result.items.indirect_link_path.url: type: string description: indirect link URL tasks.result.search_after_token: type: string description: token for subsequent requests by specifying the unique search_after_token when setting a new task, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get backlinks for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) mode: type: string description: 'results grouping type optional field possible grouping types: as_is – returns all backlinks one_per_domain – returns one backlink per domain one_per_anchor – returns one backlink per anchor default value: as_is' custom_mode: type: object description: 'detailed results grouping type optional field use this object to get a specific number of backlinks per field if you use custom_mode, then mode will be ignored example: "custom_mode": {"field": "domain", "value": 100}' properties: field: type: string value: type: integer filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: =, , in, not_in, like, not_like, ilike, not_ilike, regex, not_regex, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["rank",">","80"] [["page_from_rank",">","55"], "and", ["dofollow","=",true]] [["first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["anchor","like","%seo%"],"or",["text_pre","like","%seo%"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["rank,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["domain_from_rank,desc","page_from_rank,asc"]' offset: type: integer description: 'offset in the results array of the returned backlinks optional field default value: 0 if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks; Note: the maximum value is 20,000, use the search_after_token if you would like to offset more results' search_after_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request; by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task ; Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request' limit: type: integer description: 'the maximum number of returned backlinks optional field default value: 100 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates if internal backlinks from subdomains to the target will be excluded from the results optional field if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target if set to false, internal links will be included in the results default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/backlinks/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_backlinks/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.04908 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Backlinks description: 'Backlink counts for many `targets` at once - one row of `target` and `backlinks`. Measured at 558 bytes for two targets. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to rank a list before spending a per-target call on any of them; `post_dataforseo_backlinks_summary_live` gives the full profile of one. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_backlinks_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlink data tasks.result.items.target: type: string description: domain, subdomain or webpage from a POST array tasks.result.items.backlinks: type: integer description: number of backlinks pointing to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: 'domains, subdomains or webpages to get the number of backlinks for required field you can set up to 1000 domains, subdomains or webpages the domain or subdomain should be specified without https:// and www. the page should be specified with absolute URL (including http:// or https://) example: "targets": [ "forbes.com", "cnn.com", "bbc.com", "yelp.com", "https://www.apple.com/iphone/", "https://ahrefs.com/blog/", "ibm.com", "https://variety.com/", "https://stackoverflow.com/", "www.trustpilot.com" ]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_backlinks/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_new_lost_backlinks/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048432 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk New & Lost Backlinks description: 'New and lost backlink counts for many `targets` since `date_from` - one row of `target`, `new_backlinks` and `lost_backlinks`. Measured at 654 bytes for two targets. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to spot which sites in a list are gaining or bleeding links. For one target broken into periods use `post_dataforseo_backlinks_timeseries_new_lost_live`; for referring domains rather than links, `post_dataforseo_backlinks_bulk_new_lost_ref_domains_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_new_lost_backlinks_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.target: type: string description: domain, subdomain or webpage from a POST array tasks.result.items.new_backlinks: type: integer description: number of new backlinks number of new backlinks pointing to the target tasks.result.items.lost_backlinks: type: integer description: number of lost backlinks number of lost backlinks of the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: 'domains, subdomains or webpages to get new & lost backlinks for required field you can set up to 1000 domains, subdomains or webpages the domain or subdomain should be specified without https:// and www. the page should be specified with absolute URL (including http:// or https://) example: "targets": [ "forbes.com", "cnn.com", "bbc.com", "yelp.com", "https://www.apple.com/iphone/", "https://ahrefs.com/blog/", "ibm.com", "https://variety.com/", "https://stackoverflow.com/", "www.trustpilot.com" ]' date_from: type: string description: 'starting date of the time range optional field this field indicates the date which will be used as a threshold for new and lost backlinks; the backlinks that appeared in our index after the specified date will be considered as new; the backlinks that weren’t found after the specified date, but were present before, will be considered as lost; default value: today’s date -(minus) one month; e.g. if today is 2021-10-13, default date_from will be 2021-09-13. minimum value equals today’s date -(minus) one year; e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13. date format: "yyyy-mm-dd" example: "2021-01-01"' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_new_lost_backlinks/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_new_lost_referring_domains/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048144 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk New & Lost Referring Domains description: 'New and lost referring domains for many `targets` since `date_from`: `new_referring_domains`, `lost_referring_domains`, `new_referring_main_domains` and `lost_referring_main_domains` per target. Measured at 836 bytes for two targets. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Prefer this over `post_dataforseo_backlinks_bulk_new_lost_backlinks_live` when judging whether a site is genuinely gaining relationships - domains churn less than links. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_new_lost_ref_domains_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.target: type: string description: domain, subdomain or webpage from a POST array tasks.result.items.new_referring_domains: type: integer description: number of new referring domains number of new referring domains pointing to the target tasks.result.items.lost_referring_domains: type: integer description: number of lost referring domains number of lost referring domains of the target tasks.result.items.new_referring_main_domains: type: integer description: number of new referring main domains pointing to the target tasks.result.items.lost_referring_main_domains: type: integer description: number of lost referring main domains pointing to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: 'domains, subdomains or webpages to get new & lost referring domains for required field you can set up to 1000 domains, subdomains or webpages the domain or subdomain should be specified without https:// and www. the page should be specified with absolute URL (including http:// or https://) example: "targets": [ "forbes.com", "cnn.com", "bbc.com", "yelp.com", "https://www.apple.com/iphone/", "https://ahrefs.com/blog/", "ibm.com", "https://variety.com/", "https://stackoverflow.com/", "www.trustpilot.com" ]' date_from: type: string description: 'starting date of the time range optional field this field indicates the date which will be used as a threshold for new and lost referring domains; the referring domains that appeared in our index after the specified date will be considered as new; the referring domains that weren’t found after the specified date, but were present before, will be considered as lost; default value: today’s date -(minus) one month; e.g. if today is 2021-10-13, default date_from will be 2021-09-13. minimum value equals today’s date -(minus) one year; e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13. date format: "yyyy-mm-dd" example: "2021-01-01"' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_new_lost_referring_domains/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_pages_summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048144 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Pages Summary description: 'Page-level backlink metrics for many `targets` at once: one row per `url` with `rank`, `main_domain_rank`, `backlinks`, `first_seen`, `lost_date`, `backlinks_spam_score` and `broken_backlinks`. Measured at 3.3 KB for two targets - the heaviest bulk endpoint, since it returns pages rather than one row per target. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The single-target version is `post_dataforseo_backlinks_domain_pages_summary_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_pages_summary_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_page_summary’ tasks.result.items.url: type: string description: page URL tasks.result.items.rank: type: integer description: page rank rank of the page on the target website rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.main_domain_rank: type: integer description: rank of the main domain rank of the main domain is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: number of backlinks tasks.result.items.first_seen: type: string description: 'date and time when our crawler found a backlink to this page for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.lost_date: type: string description: 'date and time when the last backlink to this page was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.backlinks_spam_score: type: integer description: average spam score of the backlinks pointing to the page learn more about how the metric is calculated on this help center page tasks.result.items.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the page tasks.result.items.broken_pages: type: integer description: number of broken pages number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to tasks.result.items.referring_domains: type: integer description: indicates the number domains referring to the page tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.items.referring_main_domains: type: integer description: indicates the number of referring main domains tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.items.referring_ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.referring_subnets: type: integer description: number of referring subnetworks tasks.result.items.referring_pages: type: integer description: indicates the number of pages pointing to the relevant url tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target tasks.result.items.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.items.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and link count per each semantic location you can get the full list of semantic elements here examples: article, section, footer' tasks.result.items.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: domains, subdomains or webpages to get summary data for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) you can specify up to 1000 pages, domains, or subdomains in each request. note that the URLs you set in a single request cannot belong to more than 100 different domains. include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_pages_summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_ranks/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048576 max: 0.04908 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Ranks description: 'The rank of up to a thousand `targets` in one call - one row of `target` and `rank`. Measured at 533 bytes for two targets, the leanest endpoint here. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The bulk family takes `targets` as a **plain array**, unlike the intersection endpoints which key theirs by position. For everything known about a single target use `post_dataforseo_backlinks_summary_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_ranks_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.target: type: string description: domain, subdomain or webpage from a POST array tasks.result.items.rank: type: integer description: rank of the target values represent real-time data for the date of the request rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: 'domains, subdomains or webpages to get rank for required field you can set up to 1000 domains, subdomains or webpages the domain or subdomain should be specified without https:// and www. the page should be specified with absolute URL (including http:// or https://) example: "targets": [ "forbes.com", "cnn.com", "bbc.com", "yelp.com", "https://www.apple.com/iphone/", "https://ahrefs.com/blog/", "ibm.com", "https://variety.com/", "https://stackoverflow.com/", "www.trustpilot.com" ]' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_ranks/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_referring_domains/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.048072 p95: 0.0498 max: 0.050304 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Referring Domains description: 'Referring-domain counts for many `targets`: `referring_domains`, `referring_domains_nofollow`, `referring_main_domains` and `referring_main_domains_nofollow` per target. Measured at 1.7 KB for two targets. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The nofollow split is the useful part - a large gap means the raw count overstates authority. For the domains themselves use `post_dataforseo_backlinks_referring_domains_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_referring_domains_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.target: type: string description: domain, subdomain or webpage from a POST array tasks.result.items.referring_domains: type: integer description: number of referring domains pointing to the target note that we calculate main domains (root domains, like example.com) and their subdomains (e.g. blog.example.com) separately for this metric tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.items.referring_main_domains: type: integer description: number of referring main domains pointing to the target the number of primary (root) domains referring to your target tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: 'domains, subdomains or webpages to get the number of referring domains for required field you can set up to 1000 domains, subdomains or webpages the domain or subdomain should be specified without https:// and www. the page should be specified with absolute URL (including http:// or https://) example: "targets": [ "forbes.com", "cnn.com", "bbc.com", "yelp.com", "https://www.apple.com/iphone/", "https://ahrefs.com/blog/", "ibm.com", "https://variety.com/", "https://stackoverflow.com/", "www.trustpilot.com" ]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_referring_domains/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/bulk_spam_score/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048144 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Bulk Spam Score description: 'Spam score for many `targets` at once - one row of `target` and `spam_score`. Measured at 624 bytes for two targets. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to screen a prospect list before outreach. The per-target profile including spam score is `post_dataforseo_backlinks_summary_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_bulk_spam_score_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.type: type: string description: type = ‘backlinks_bulk_spam_score’ tasks.result.items.target: type: string description: domain, subdomain or webpage from a POST array tasks.result.items.spam_score: type: integer description: average spam score the target learn more about how the metric is calculated '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: 'domains, subdomains or webpages to get rank for required field you can set up to 1000 domains, subdomains or webpages the domain or subdomain should be specified without https:// and www. the page should be specified with absolute URL (including http:// or https://) example: "targets": [ "forbes.com", "cnn.com", "bbc.com", "yelp.com", "https://www.apple.com/iphone/", "https://ahrefs.com/blog/", "ibm.com", "https://variety.com/", "https://stackoverflow.com/", "www.trustpilot.com" ]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/bulk_spam_score/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/competitors/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048072 max: 0.050736 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Competitors description: 'Sites sharing referring domains with one `target`, ranked by how many they share. Each row gives `target`, `rank` and `intersections` - the count of shared linking domains. `main_domain`, `exclude_large_domains` and `exclude_internal_backlinks` shape what counts. Measured at 570 bytes, the smallest response in this family. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. These are link-graph competitors, not search competitors; for the latter use `post_dataforseo_labs_google_serp_competitors_live`. To see the actual shared domains use `post_dataforseo_backlinks_domain_intersection_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_competitors_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the items array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_competitors’ tasks.result.items.target: type: string description: competitor domain tasks.result.items.rank: type: integer description: domain rank domain rank across all domains in the database rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.intersections: type: integer description: indicates the number of backlink intersections with the target specified in the POST array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get competitor domains for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) limit: type: integer description: 'the maximum number of returned domains optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned domains optional field default value: 0 if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["rank",">","100"] [["target","like","%forbes%"], "and", [["rank",">","100"],"or",["intersections",">","5"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["rank,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["intersections,desc","rank,asc"]' main_domain: type: boolean description: 'indicates if only main domain of the target will be included in the search optional field if set to true, only the main domain will be included in search; default value: true' exclude_large_domains: type: boolean description: 'indicates whether large domain will appear in results optional field if set to true, the results from the large domain (google.com, amazon.com, etc.) will be omitted; default value: true' exclude_internal_backlinks: type: boolean description: 'indicates if internal backlinks from subdomains to the target will be excluded from the results optional field if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target if set to false, internal links will be included in the results default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/competitors/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/domain_intersection/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.05016 max: 0.066 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Intersection description: 'The domains linking to several targets at once. ⚠️ `targets` here is an **object keyed by position** - `{"1": "a.com", "2": "b.com"}` - not the array the bulk endpoints take. `exclude_targets` removes sites from the comparison. Each row carries `domain_intersection` and a `summary` per target. Measured at 2.0 KB for one row. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to find who links to your competitors but not to you. The page-level equivalent is `post_dataforseo_backlinks_page_intersection_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_domain_intersection_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.targets: type: object description: target domains, subdomains or webpages in a POST array tasks.result.total_count: type: integer description: total amount of results relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains domain that link to all targets from the POST array tasks.result.items.domain_intersection: type: object description: contains data on domains that link to the corresponding targets specified in the POST array data is provided in separate objects corresponding to domains, subdomains or pages specified in the targets object tasks.result.items.1: type: object description: contains data on a domain that links to the corresponding target from the POST array field name varies in the range from 1 to 20 according to the number of domains, subdomains, or pages in the targets object tasks.result.items.1.type: type: string description: type of element = ‘backlinks_domain_intersection’ tasks.result.items.1.target: type: string description: domain that links to the corresponding target from the POST array tasks.result.items.1.rank: type: integer description: rank referred to the target from the POST array indicates the rank that the referring domain (target above) refers to your target from the POST array; rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.1.backlinks: type: integer description: indicates the number of backlinks tasks.result.items.1.first_seen: type: string description: 'date and time when our crawler found the backlink from this target for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.1.lost_date: type: integer description: 'date and time when the last backlink from this target was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.1.backlinks_spam_score: type: integer description: average spam score of the backlinks pointing to the target learn more about how the metric is calculated on this help center page tasks.result.items.1.broken_backlinks: type: integer description: number of broken backlinks tasks.result.items.1.broken_pages: type: integer description: number of broken pages tasks.result.items.1.referring_domains: type: integer description: number of referring domains tasks.result.items.1.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the corresponding target tasks.result.items.1.referring_main_domains: type: integer description: number of referring main domains tasks.result.items.1.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.items.1.referring_ips: type: integer description: number of referring IP addresses tasks.result.items.1.referring_subnets: type: integer description: number of referring subnetworks tasks.result.items.1.referring_pages: type: integer description: indicates the number of pages pointing to the target tasks.result.items.1.referring_links_tld: type: object description: top level domains of the referring links contains top-level domains and referring link count per each tasks.result.items.1.referring_links_types: type: object description: 'types of the referring links indicates the types of referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.1.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and the link count per each attribute tasks.result.items.1.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.1.referring_links_semantic_locations: type: object description: semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and the link count per each semantic location you can get the full list of semantic elements here tasks.result.items.1.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.1.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target tasks.result.items.summary: type: object description: contains the domain intersections summary tasks.result.items.intersections_count: type: integer description: total number of intersections '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: object description: 'domains, subdomains or webpages to get links for required field you can set up to 20 domains, subdomains or webpages a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) example: "targets": { "1": "http://planet.postgresql.org/", "2": "http://gborg.postgresql.org/" }' additionalProperties: type: string exclude_targets: type: array items: type: string description: 'domains, subdomains or webpages you want to exclude optional field you can specify up to 10 domains, subdomains or webpages if you use this array, results will contain the referring domains that link to targets but don’t link to exclude_targets example: "exclude_targets": [ "bbc.com", "https://www.apple.com/iphone/*", "https://dataforseo.com/apis/*"]' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["1.internal_links_count",">","1"] [["2.referring_pages",">","2"], "and", ["1.backlinks",">","10"]] [["1.first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["2.target","like","%dataforseo.com%"],"or",["1.referring_domains",">","10"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["backlinks,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["backlinks,desc","rank,asc"]' offset: type: integer description: 'offset in the array of returned results optional field default value: 0 if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks' limit: type: integer description: 'the maximum number of returned results optional field default value: 100 maximum value: 1000' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": [["dofollow", "=", true]]' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the targets will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates whether the backlinks from subdomains of the target are excluded optional field if set to false, the backlinks from subdomains of the target will be omitted and you won’t receive the same domain in the response; default value: true' intersection_mode: type: string description: 'indicates whether to intersect backlinks optional field use this field to intersect or merge results for the specified domains possible values: all, partial all – results are based on all backlinks; partial – results are based on the intersecting backlinks only; default value: all' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/domain_intersection/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/domain_pages/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048072 max: 0.048216 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Pages description: 'The pages of one `target` that have inbound links, with the crawler''s view of each: `main_domain`, `domain`, `tld`, `page`, `ip`, `first_visited`, `prev_visited` and `fetch_time`. Measured at 2.0 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it to find which pages actually earn links. For per-page backlink counts rather than crawl metadata use `post_dataforseo_backlinks_domain_pages_summary_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_domain_pages_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target in a POST array tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the items array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_domain_page’ tasks.result.items.main_domain: type: string description: main website domain main website domain does not include subdomains tasks.result.items.domain: type: string description: domain domain where the page was found tasks.result.items.tld: type: string description: top-level domain top-level domain in the DNS root zone tasks.result.items.page: type: string description: page URL relevant page URL tasks.result.items.ip: type: string description: Internet Protocol address tasks.result.items.first_visited: type: string description: 'date and time of the first page visit date and time when our crawler visited this page for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.prev_visited: type: string description: 'previous to the most recent date when our crawler visited the page in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.fetch_time: type: string description: 'most recent date and time when our crawler visited the page in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.status code: type: integer description: HTTP status code of the page tasks.result.items.location: type: string description: location header indicates the URL to redirect a page to if exists tasks.result.items.size: type: integer description: indicates the page size, in bytes tasks.result.items.encoded_size: type: integer description: page size after encoding indicates the size of the encoded page, in bytes tasks.result.items.content_encoding: type: string description: type of encoding tasks.result.items.media_type: type: string description: types of media used to display a page tasks.result.items.server: type: string description: server version tasks.result.items.meta: type: object description: page meta data tasks.result.items.meta.title: type: string description: page title tasks.result.items.meta.canonical: type: string description: canonical page tasks.result.items.meta.internal_links_count: type: integer description: number of internal links on the page tasks.result.items.meta.external_links_count: type: integer description: number of external links on the page tasks.result.items.meta.images_count: type: integer description: number of images on the page tasks.result.items.meta.words_count: type: integer description: number of words on the page tasks.result.items.meta.page_spam_score: type: integer description: spam score of the page learn more about how the metric is calculated on this help center page tasks.result.items.meta.social_media_tags: type: object description: array of social media tags found on the page contains social media tags and their content supported tags include but are not limited to Open Graph and Twitter card tasks.result.items.meta.h1: type: array items: type: string description: h1 tag content of h1 tags tasks.result.items.meta.h2: type: array items: type: string description: h2 tag content of h2 tags tasks.result.items.meta.h3: type: array items: type: string description: h3 tag content of h3 tags tasks.result.items.meta.images_alt: type: array items: type: string description: content of alt tags tasks.result.items.meta.powered_by: type: array items: type: string description: CMS details tasks.result.items.meta.language: type: string description: 'page content language example: en' tasks.result.items.meta.charset: type: string description: 'character encoding examples: utf-8' tasks.result.items.meta.platform_type: type: array items: type: string description: type of a platform tasks.result.items.meta.technologies: type: object description: website technologies tasks.result.items.meta.technologies.cms: type: string description: content management system tasks.result.items.meta.technologies.blogs: type: string description: blog management system tasks.result.items.meta.technologies.cdn: type: string description: content delivery network tasks.result.items.page_summary: type: object description: contains backlink data for this page tasks.result.items.page_summary.first_seen: type: string description: 'date and time when our crawler found the backlink for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.page_summary.lost_date: type: string description: 'date and time when the last backlink for this page was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.page_summary.rank: type: integer description: page rank rank of the page rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.page_summary.backlinks: type: integer description: indicates the number of backlinks tasks.result.items.page_summary.backlinks_spam_score: type: integer description: average spam score of the backlinks pointing to the page learn more about how the metric is calculated on this help center page tasks.result.items.page_summary.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the page tasks.result.items.page_summary.broken_pages: type: integer description: number of broken pages number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to tasks.result.items.page_summary.referring_domains: type: integer description: indicates the number of referring domains tasks.result.items.page_summary.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the page tasks.result.items.page_summary.referring_main_domains: type: integer description: indicates the number of referring main domains tasks.result.items.page_summary.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the page tasks.result.items.page_summary.referring ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.page_summary.referring subnets: type: integer description: number of referring subnetworks tasks.result.items.page_summary.referring_pages: type: integer description: indicates the number of pages pointing to the page tasks.result.items.page_summary.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.items.page_summary.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.page_summary.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.page_summary.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.page_summary.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and link count per each semantic location you can get the full list of semantic elements here examples: article, section, summary' tasks.result.items.page_summary.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.page_summary.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'domain or subdomain required field a domain or a subdomain should be specified without https:// and www. example: forbes.com' limit: type: integer description: 'the maximum number of returned pages optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned pages optional field default value: 0 if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["meta.internal_links_count",">","1"] [["meta.external_links_count",">","2"], "and", ["backlinks",">","10"]] [["first_visited",">","2017-10-23 11:31:45 +00:00"], "and", [["title","like","%seo%"],"or",["referring_domains",">","10"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["page_summary.backlinks,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["page_summary.backlinks,desc","page_summary.rank,asc"]' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": ["dofollow", "=", true]' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates if internal backlinks from subdomains to the target will be excluded from the results optional field if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target if set to false, internal links will be included in the results default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/domain_pages/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/domain_pages_summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048072 max: 0.051528 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Pages Summary description: 'Per-page backlink metrics for one `target`: one row per `url` with `rank`, `backlinks`, `first_seen`, `lost_date`, `backlinks_spam_score`, `broken_backlinks` and `broken_pages`. Measured at 1.3 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The page-level twin of `post_dataforseo_backlinks_summary_live`, which reports the same metrics for the domain as a whole. For crawl metadata about those pages instead, use `post_dataforseo_backlinks_domain_pages_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_domain_pages_summary_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target in the post array tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_page_summary’ tasks.result.items.url: type: string description: page URL tasks.result.items.rank: type: integer description: page rank rank of the page rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: number of backlinks tasks.result.items.first_seen: type: string description: 'date and time when our crawler found a backlink to this page for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.lost_date: type: string description: 'date and time when the last backlink to this page was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.backlinks_spam_score: type: integer description: average spam score of the backlinks pointing to the page learn more about how the metric is calculated on this help center page tasks.result.items.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the page tasks.result.items.broken_pages: type: integer description: number of broken pages number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to tasks.result.items.referring_domains: type: integer description: indicates the number domains referring to the page tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the page tasks.result.items.referring_main_domains: type: integer description: indicates the number of referring main domains tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the page tasks.result.items.referring_ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.referring_subnets: type: integer description: number of referring subnetworks tasks.result.items.referring_pages: type: integer description: indicates the number of pages pointing to the relevant url tasks.result.items.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.items.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and link count per each semantic location you can get the full list of semantic elements here examples: article, section, footer' tasks.result.items.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get summary data for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) limit: type: integer description: 'the maximum number of returned anchors optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned anchors optional field default value: 0 if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["referring_links_types.anchors",">","1"] [["broken_pages",">","2"], "and", ["backlinks",">","10"]] [["first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["anchor","like","%seo%"],"or",["referring_domains",">","10"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["backlinks,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["backlinks,desc","rank,asc"]' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": [["dofollow", "=", true]]' include_subdomains: type: boolean description: 'indicates if the subdomains of the target domain will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the target will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates whether the backlinks from subdomains of the target are excluded optional field if set to false, backlinks from the subdomains of the target domain will be ommited and you won’t receive the same domain in the response; default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/domain_pages_summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/history/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048144 max: 0.052248 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlinks History description: 'One `target`''s backlink profile as it stood on each date in a range, with `date_from`, `date_to` and one item per point. Measured at 4.1 KB for two months - the largest response in this family, because each point repeats a full metric set. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For the current profile only use `post_dataforseo_backlinks_summary_live`. For a lighter time series, `post_dataforseo_backlinks_timeseries_summary_live` reports fewer metrics per point. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_history_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target from the POST array tasks.result.date_from: type: string description: 'starting date of the time range in the UTC format: “yyyy-mm-dd” example: 2019-01-01' tasks.result.date_to: type: string description: 'ending date of the time range in the UTC format: "yyyy-mm-dd" example: "2019-01-15"' tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains historical backlink data for the specified domain the data is provided month-by-month; the metrics are aggregated according to the backlinks the specified domain had on the first day of each given month tasks.result.items.type: type: string description: type of element = ‘backlinks_history’ tasks.result.items.date: type: string description: 'date and time when the data for the target was stored in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.rank: type: integer description: domain rank on the given date learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: number of backlinks tasks.result.items.new_backlinks: type: integer description: 'number of new backlinks for the target data is provided based in a comparison with the previous period Note: this data is available from May 2021; if the date range specified in the POST request precedes May 2021, the field will equal 0' tasks.result.items.lost_backlinks: type: integer description: 'number of lost backlinks for the target data is provided based in a comparison with the previous period Note: this data is available from May 2021; if the date range specified in the POST request precedes May 2021, the field will equal 0' tasks.result.items.new_referring_domains: type: integer description: 'number of new referring domains for the target data is provided based in a comparison with the previous period Note: this data is available from May 2021; if the date range specified in the POST request precedes May 2021, the field will equal 0' tasks.result.items.lost_referring_domains: type: integer description: 'number of lost referring domains for the target data is provided based in a comparison with the previous period Note: this data is available from May 2021; if the date range specified in the POST request precedes May 2021, the field will equal 0' tasks.result.items.crawled_pages: type: integer description: number of crawled pages for the target tasks.result.items.info: type: object description: information about the target tasks.result.items.info.server: type: string description: server tasks.result.items.info.cms: type: string description: content management system tasks.result.items.info.platform_type: type: array items: type: string description: platform type tasks.result.items.info.ip_address: type: string description: IP address of the target tasks.result.items.info.country: type: string description: country code that the target domain is determined to belong to tasks.result.items.info.is_ip: type: boolean description: indicates if the target is IP if true, the domain, subdomain or webpage functions as an IP address and does not have a domain name tasks.result.items.info.target_spam_score: type: integer description: spam score of the target if the target is a domain/subdomain, this fields indicates the average spam score of all pages of that domain/subdomain; learn more about how the metric is calculated on this help center page tasks.result.items.internal_links_count: type: integer description: number of internal links calculated as the sum of internal links on the pages of the specified target tasks.result.items.external_links_count: type: integer description: number of external links on the page calculated as the sum of external links on the pages of the specified target tasks.result.items.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the target tasks.result.items.broken_pages: type: integer description: number of broken pages number of pages that receive backlinks but respond with 4xx or 5xx status codes tasks.result.items.referring_domains: type: integer description: number of referring domains referring domains include subdomains that are counted as separate domains for this metric tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.items.referring_main_domains: type: integer description: number of referring main domains tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.items.referring_ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.referring_subnets: type: integer description: number of referring subnetworks tasks.result.items.referring_pages: type: integer description: number of pages pointing to the target tasks.result.items.referring_links_tld: type: object description: top-level domains of the referring links contains top-level domains and referring link count per each tasks.result.items.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and link count per each semantic location you can get the full list of semantic elements here examples: article, section, summary' tasks.result.items.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain required field a domain should be specified without https:// and www. date_from: type: string description: 'starting date of the time range optional field minimum value 2019-01-01 if you don’t specify this field, the minimum value will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/history/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/index: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlinks Index description: 'How much of the web DataForSEO''s backlink crawler has indexed: `total_backlinks`, `total_pages` and an `index_history` array of `date`, `total_backlinks` and `total_pages`. Measured at 1.4 KB. **Free - upstream cost is 0, the only endpoint in this family that is.** Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. It says nothing about any particular site; it is the denominator behind every other number here, useful for judging whether a coverage gap is the site''s or the crawler''s.' operationId: get_dataforseo_backlinks_index responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.total_backlinks: type: integer description: total number of backlinks our database contains for the moment of checking tasks.result.total_pages: type: integer description: total number of pages our database contains for the moment of checking tasks.result.total_domains: type: integer description: total number of domains our database contains for the moment of checking tasks.result.index_history: type: array items: type: string description: index volume data for the past 12 months tasks.result.index_history.date: type: string description: 'date for which index volume data is provided in the UTC format: “yyyy-mm-dd” example: 2021-10-01' tasks.result.index_history.total_backlinks: type: integer description: total number of backlinks our database contained on the given date tasks.result.index_history.total_pages: type: integer description: total number of pages our database contained on the given date tasks.result.index_history.total_domains: type: integer description: total number of domains our database contained on the given date '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/index source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/page_intersection/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048216 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Page Intersection description: 'The pages linking to several target URLs at once, rather than the domains. ⚠️ `targets` is an **object keyed by position** and takes full URLs, not bare domains. Each row carries `page_intersection` and a `summary` per target. Measured at 3.9 KB for one row - the heaviest row shape here, since each carries a summary per target. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The domain-level equivalent is `post_dataforseo_backlinks_domain_intersection_live`, which is the one to reach for first. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_page_intersection_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.targets: type: object description: targets from a POST array tasks.result.total_count: type: integer description: total amount of results relevant the request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.page_intersection: type: object description: contains data on pages that link to the corresponding targets specified in the POST array data is provided in separate objects corresponding to pages specified in the targets object tasks.result.page_intersection.1: type: array items: type: string description: contains data on a referring page that links to the corresponding target from the POST array field name varies in the range from 1 to 20 according to the number of domains, subdomains or pages in the targets object tasks.result.page_intersection.1.type: type: string description: type of element = ‘backlinks_page_intersection’ tasks.result.page_intersection.1.domain_from: type: string description: domain referring to the target domain or webpage tasks.result.page_intersection.1.url_from: type: string description: URL of the page where the backlink is found tasks.result.page_intersection.1.url_from_https: type: boolean description: indicates whether the referring URL is secured with HTTPS if true, the referring URL is secured with HTTPS tasks.result.page_intersection.1.domain_to: type: string description: domain the backlink is pointing to tasks.result.page_intersection.1.url_to: type: string description: URL the backlink is pointing to tasks.result.page_intersection.1.url_to_https: type: boolean description: indicates if the URL the backlink is pointing to is secured with HTTPS if true, the URL is secured with HTTPS tasks.result.page_intersection.1.tld_from: type: string description: top-level domain of the referring URL tasks.result.page_intersection.1.is_new: type: boolean description: indicates whether the backlink is new if true, the backlink was found on the page last time our crawler visited it tasks.result.page_intersection.1.is_lost: type: boolean description: indicates whether the backlink was removed if true, the backlink or the entire page was removed tasks.result.page_intersection.1.backlink_spam_score: type: integer description: spam score of the backlink learn more about how the metric is calculated on this help center page tasks.result.page_intersection.1.rank: type: integer description: backlink rank rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.page_intersection.1.page_from_rank: type: integer description: page rank of the referring page page_from_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.page_intersection.1.domain_from_rank: type: integer description: domain rank of the referring domain indicates the rank of the domain at the time our crawler last saw the backlink; domain_from_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.page_intersection.1.domain_from_platform_type: type: array items: type: string description: 'platform types of the referring domain possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.page_intersection.1.domain_from_is_ip: type: boolean description: indicates if the domain is IP if true, the domain functions as an IP address and does not have a domain name tasks.result.page_intersection.1.domain_from_ip: type: string description: IP address of the referring domain tasks.result.page_intersection.1.domain_from_country: type: string description: ISO country code of the referring domain tasks.result.page_intersection.1.page_from_external_links: type: integer description: number of external links found on the referring page tasks.result.page_intersection.1.page_from_internal_links: type: integer description: number of internal links found on the referring page tasks.result.page_intersection.1.page_from_size: type: integer description: 'size of the referring page, in bytes example: 63357' tasks.result.page_intersection.1.page_from_encoding: type: string description: 'character encoding of the referring page example: utf-8' tasks.result.page_intersection.1.page_from_language: type: string description: 'language of the referring page in ISO 639-1 format example: en' tasks.result.page_intersection.1.page_from_title: type: string description: title of the referring page tasks.result.page_intersection.1.page_from_status_code: type: integer description: 'HTTP status code returned by the referring page example: 200' tasks.result.page_intersection.1.first_seen: type: string description: 'date and time when our crawler found the backlink for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.page_intersection.1.prev_seen: type: string description: 'previous to the most recent date when our crawler visited the backlink in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.page_intersection.1.last_seen: type: string description: 'most recent date when our crawler visited the backlink in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.page_intersection.1.item_type: type: string description: 'link type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.page_intersection.1.attributes: type: array items: type: string description: 'link attributes of the referring links example: nofollow' tasks.result.page_intersection.1.dofollow: type: boolean description: indicates whether the backlink is dofollow if false, the backlink is nofollow tasks.result.page_intersection.1.original: type: boolean description: indicates whether the backlink was present on the referring page when our crawler first visited it tasks.result.page_intersection.1.alt: type: string description: alternative text of the image this field will be null if backlink type is not image tasks.result.page_intersection.1.anchor: type: string description: anchor text of the backlink tasks.result.page_intersection.1.text_pre: type: string description: text snippet before the anchor text tasks.result.page_intersection.1.text_post: type: string description: snippet after the anchor text tasks.result.page_intersection.1.semantic_location: type: string description: 'indicates semantic element in HTML where the backlink is found you can get the full list of semantic elements here examples: article, section, summary' tasks.result.page_intersection.1.links_count: type: integer description: number of identical backlinks found on the referring page tasks.result.page_intersection.1.group_count: type: integer description: indicates total number of backlinks from this domain for example, if mode is set to one_per_domain, this field will indicate the total number of backlinks coming from this domain tasks.result.page_intersection.1.is_broken: type: boolean description: indicates whether the backlink is broken if true, the backlink is pointing to a page responding with a 4xx or 5xx status code tasks.result.page_intersection.1.url_to_status_code: type: integer description: 'status code of the referenced page if the value is null, our crawler hasn’t yet visited the webpage the link is pointing to example: 200' tasks.result.page_intersection.1.url_to_spam_score: type: integer description: spam score of the referenced page if the value is null, our crawler hasn’t yet visited the webpage the link is pointing to learn more about how the metric is calculated on this help center page tasks.result.page_intersection.1.url_to_redirect_target: type: string description: target url of the redirect target page the redirect is pointing to tasks.result.page_intersection.1.is_indirect_link: type: boolean description: indicates whether the backlink is an indirect link if true, the backlink is an indirect link pointing to a page that either redirects to url_to, or points to a canonical page tasks.result.page_intersection.1.indirect_link_path: type: array items: type: string description: indirect link path indicates a URL or a sequence of URLs that lead to url_to tasks.result.page_intersection.1.indirect_link_path.type: type: string description: 'indirect link type possible values: redirect, canonical' tasks.result.page_intersection.1.indirect_link_path.status_code: type: integer description: HTTP status code of the URL tasks.result.page_intersection.1.indirect_link_path.url: type: string description: indirect link URL tasks.result.summary: type: object description: contains the page intersections summary tasks.result.summary.intersections_count: type: integer description: total number of intersections '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: object description: 'domains, subdomains or webpages to get links for required field you can set up to 20 domains, subdomains or webpages a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) example: "targets": { "1": "http://planet.postgresql.org/", "2": "http://gborg.postgresql.org/" }' additionalProperties: type: string exclude_targets: type: array items: type: string description: 'domains, subdomains or webpages you want to exclude optional field you can set up to 10 domains, subdomains or webpages if you use this array, results will contain the referring pages that link to targets but don’t link to exclude_targets example: "exclude_targets": [ "bbc.com", "https://www.apple.com/iphone/*", "https://dataforseo.com/apis/*"]' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["1.rank",">","80"] [["2.page_from_rank",">","55"], "and", ["1.original","=","true"]] [["1.first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["1.acnhor","like","%seo%"],"or",["1.text_pre","not_like","%seo%"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["rank,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["domain_from_rank,desc","page_from_rank,asc"]' offset: type: integer description: 'offset in the results array of the returned backlinks optional field default value: 0 if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks' limit: type: integer description: 'the maximum number of returned backlinks optional field default value: 100 maximum value: 1000' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: attributes domain_from_platform_type default value: 10 maximum value: 1000' include_subdomains: type: boolean description: 'indicates if the subdomains of the targets will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the targets will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates if internal backlinks from subdomains to the target will be excluded from the results optional field if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target if set to false, internal links will be included in the result default value: true' intersection_mode: type: string description: 'indicates whether to intersect backlinks optional field use this field to intersect or merge results for the specified URLs possible values: all, partial all – results are based on all backlinks; partial – results are based on the intersecting backlinks only; default value: all' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/page_intersection/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/referring_domains/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.0552 max: 0.0552 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Referring Domains description: 'The domains linking to one `target`, one row per domain with `domain`, `rank`, `backlinks`, `first_seen`, `lost_date`, `backlinks_spam_score`, `broken_backlinks` and `broken_pages`. Measured at 1.3 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Referring domains matter more than raw backlink count, since a thousand links from one domain is one relationship. For the individual links use `post_dataforseo_backlinks_backlinks_live`; to collapse further, to network operators, use `post_dataforseo_backlinks_referring_networks_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_referring_domains_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target in a POST array tasks.result.total_count: type: integer description: total number of relevant items in the database total number of main domains referring to your target; example.com and blog.example.com are counted as one referring domain tasks.result.items_count: type: integer description: number of items in the items array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_referring_domain’ tasks.result.items.domain: type: string description: referring domain tasks.result.items.rank: type: integer description: domain rank rank volume that a referring website passes to the target rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: indicates the number of backlinks pointing to the target tasks.result.items.first_seen: type: string description: 'date and time when our crawler found the backlink for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.lost_date: type: string description: 'date and time when the last backlink from this domain was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.backlinks_spam_score: type: integer description: average spam score of all backlinks pointing to the domain learn more about how the metric is calculated on this help center page tasks.result.items.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the domain tasks.result.items.broken_pages: type: integer description: number of broken pages number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to tasks.result.items.referring_domains: type: integer description: indicates the number of referring domains note that we calculate main domains (root domains, like example.com) and their subdomains (e.g. blog.example.com) separately for this metric tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.items.referring_main_domains: type: integer description: indicates the number of referring main domains the number of primary (root) domains referring to your target tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.items.referring ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.referring subnets: type: integer description: number of referring subnetworks tasks.result.items.referring_pages: type: integer description: indicates the number of pages pointing to the target specified tasks.result.items.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.items.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and the link count per each semantic location you can get the full list of semantic elements here examples: article, section, summary' tasks.result.items.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get referring domains for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) limit: type: integer description: 'the maximum number of returned domains optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned domains optional field default value: 0 if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["referring_pages",">","1"] [["referring_pages",">","2"], "and", ["backlinks",">","10"]] [["first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["domain","like","%dataforseo.com%"],"or",["referring_domains",">","10"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["backlinks,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["backlinks,desc","rank,asc"]' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": ["dofollow", "=", true]' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the target will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates whether the backlinks from subdomains of the target are excluded optional field if set to false, the backlinks from subdomains of the target will be ommited and you won’t receive the same domain in the response; default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/referring_domains/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/referring_networks/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048072 max: 0.0552 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Referring Networks description: 'Collapses referring domains to the networks behind them - one row per `network_address` with `referring_domains` plus `rank`, `backlinks`, `first_seen`, `lost_date`, `backlinks_spam_score`, `broken_backlinks` and `broken_pages`. `network_address_type` chooses IP or subnet. Measured at 1.2 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the level at which link schemes become visible: many domains on one subnet is one operator, not many endorsements. The un-collapsed view is `post_dataforseo_backlinks_referring_domains_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed - keep `limit` low and do not loop.' operationId: post_dataforseo_backlinks_referring_networks_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target in a POST array tasks.result.total_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the items array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of element = ‘backlinks_referring_network’ tasks.result.items.network_address: type: string description: address of the referring subnetwork or IP tasks.result.items.rank: type: integer description: network rank rank volume that a referring network passes to the target rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: indicates the number of backlinks pointing to the target tasks.result.items.first_seen: type: string description: 'date and time when our crawler found the backlink for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.lost_date: type: string description: 'date and time when the last backlink from this domain was lost indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the domain tasks.result.items.broken_pages: type: integer description: number of broken pages number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to tasks.result.items.referring_domains: type: integer description: indicates the number of referring domains referring domains include subdomains that are counted as separate domains for this metric tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.items.referring_main_domains: type: integer description: indicates the number of referring main domains tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.items.referring ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.items.referring subnets: type: integer description: number of referring subnetworks tasks.result.items.referring_pages: type: integer description: indicates the number of pages pointing to the target specified tasks.result.items.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.items.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.items.referring_links_attributes: type: object description: link attributes of the referring links indicates link attributes of the referring links and link count per each attribute tasks.result.items.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.items.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and the link count per each semantic location you can get the full list of semantic elements here examples: article, section, summary' tasks.result.items.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get referring networks for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) network_address_type: type: string description: 'indicates the type of network to get data for optional field possible values: ip, subnet default value: ip' limit: type: integer description: 'the maximum number of returned networks optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned networks optional field default value: 0 if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like, ilike, not_ilike, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["referring_pages",">","1"] [["referring_pages",">","2"], "and", ["backlinks",">","10"]] [["first_seen",">","2017-10-23 11:31:45 +00:00"], "and", [["network_address","like","194.1.%"],"or",["referring_ips",">","10"]]] The full list of possible filters is available here.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["backlinks,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["backlinks,desc","rank,asc"]' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": [["dofollow", "=", true]]' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the target will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates whether the backlinks from subdomains of the target are excluded optional field if set to false, the backlinks from subdomains of the target will be ommited and you won’t receive the same domain in the response; default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/referring_networks/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048072 max: 0.048072 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlinks Summary description: 'The whole backlink profile of one `target` in a single call: `first_seen`, `lost_date`, `rank`, `backlinks`, `backlinks_spam_score`, `crawled_pages`, `internal_links_count` and an `info` block, with referring-domain and anchor counts alongside. Measured at 1.4 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the hub of the family - start here, then drill into whichever part matters: `post_dataforseo_backlinks_backlinks_live` for the individual links, `post_dataforseo_backlinks_referring_domains_live` for who links, `post_dataforseo_backlinks_anchors_live` for the text they use. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_summary_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target in a POST array tasks.result.first_seen: type: string description: 'date and time when our crawler found the backlink for the target for the first time in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.lost_date: type: string description: 'date and time when the backlink was lost indicates the date and time when our crawler visited the target and it responded with a 4xx or 5xx status code or when its last backlink was removed in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.rank: type: integer description: target rank learn more about the metric and how it is calculated in this help center article tasks.result.backlinks: type: integer description: indicates the number of backlinks tasks.result.backlinks_spam_score: type: integer description: spam score of the backlinks displays the total spam score of all backlinks pointing to the target domain, subdomain, or webpage; to learn more about how the metric is calculated, refer to this Help Center page tasks.result.crawled_pages: type: integer description: number of crawled pages for the target tasks.result.info: type: object description: information about the target tasks.result.info.server: type: string description: server tasks.result.info.cms: type: string description: content management system tasks.result.info.platform_type: type: array items: type: string description: platform type tasks.result.info.ip_address: type: string description: IP address of the target tasks.result.info.country: type: string description: country code that the target domain is determined to belong to tasks.result.info.is_ip: type: boolean description: indicates if the target is IP if true, the domain, subdomain or webpage functions as an IP address and does not have a domain name tasks.result.info.target_spam_score: type: integer description: spam score of the target if the target is a domain/subdomain, this fields indicates the average spam score of all pages of that domain/subdomain; learn more about how the metric is calculated on this help center page tasks.result.internal_links_count: type: integer description: number of internal links calculated as the sum of internal links on the pages of the specified target tasks.result.external_links_count: type: integer description: number of external links on the page calculated as the sum of external links on the pages of the specified target tasks.result.broken_backlinks: type: integer description: number of broken backlinks number of broken backlinks pointing to the target tasks.result.broken_pages: type: integer description: number of broken pages number of pages on the target that respond with 4xx or 5xx status codes note that the number of broken pages includes pages on the target discovered by following external links, but it may also include pages discovered by following the target’s sitemap tasks.result.referring_domains: type: integer description: indicates the number of referring domains referring domains include subdomains that are counted as separate domains for this metric tasks.result.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target tasks.result.referring_main_domains: type: integer description: indicates the number of referring main domains tasks.result.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target tasks.result.referring_ips: type: integer description: number of referring IP addresses number of IP addresses pointing to this page tasks.result.referring_subnets: type: integer description: number of referring subnetworks tasks.result.referring_pages: type: integer description: indicates the number of pages pointing to the target tasks.result.referring_links_tld: type: object description: top-level domains of the referring links contains top level domains and referring link count per each tasks.result.referring_links_types: type: object description: 'types of referring links indicates the types of the referring links and link count per each type possible values: anchor, image, link, meta, canonical, alternate, redirect' tasks.result.referring_links_attributes: type: object description: 'link attributes of the referring links indicates link attributes of the referring links and link count per each attribute example values: nofollow, noopener, noreferrer, external, ugc, sponsored' tasks.result.referring_links_platform_types: type: object description: 'types of referring platforms indicates referring platform types and and link count per each platform possible values: cms, blogs, ecommerce, message-boards, wikis, news, organization' tasks.result.referring_links_semantic_locations: type: object description: 'semantic locations of the referring links indicates semantic elements in HTML where the referring links are located and link count per each semantic location you can get the full list of semantic elements here example values: article, section, summary, ""' tasks.result.referring_links_countries: type: object description: ISO country codes of the referring links indicates ISO country codes of the domains where the referring links are located and the link count per each country tasks.result.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: domain, subdomain or webpage to get data for required field a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://) include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' include_indirect_links: type: boolean description: 'indicates if indirect links to the target will be included in the results optional field if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page if set to false, indirect links will be ignored default value: true' exclude_internal_backlinks: type: boolean description: 'indicates if internal backlinks from subdomains to the target will be excluded from the results optional field if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target if set to false, internal links will be included in the results default value: true' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations default value: 10 maximum value: 1000' backlinks_status_type: type: string description: 'set what backlinks to return and count optional field you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target; possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted; default value: live' backlinks_filters: type: array items: {} description: 'filter the backlinks of your target optional field you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target you can filter the backlinks by all fields available in the response of this endpoint using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for example: "backlinks_filters": ["dofollow", "=", true]' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/timeseries_new_lost_summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.048936 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: New & Lost Backlinks Timeseries Summary description: 'New and lost backlinks and referring domains for one `target` per period, grouped by `group_range`. Measured at 1.4 KB for three monthly points. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the derivative of `post_dataforseo_backlinks_timeseries_summary_live`: that one gives the level, this one the change. A flat total hiding heavy churn only shows up here. For the same figures across many targets at once use `post_dataforseo_backlinks_bulk_new_lost_backlinks_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_timeseries_new_lost_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target from a POST array tasks.result.date_from: type: string description: 'starting date of the time range in the UTC format: “yyyy-mm-dd” example: 2019-01-01' tasks.result.date_to: type: string description: 'ending date of the time range in the UTC format: "yyyy-mm-dd" example: "2019-01-15"' tasks.result.group_range: type: string description: group_range from the POST array tasks.result.total_count: type: integer description: total amount of results relevant the request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant backlinks and referring domains data tasks.result.items.type: type: string description: type of element = ‘backlinks_timeseries_new_lost_summary’ tasks.result.items.date: type: string description: 'date and time when the data for the target was stored in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.new_backlinks: type: integer description: number of new backlinks number of new backlinks pointing to the target tasks.result.items.lost_backlinks: type: integer description: number of lost backlinks number of lost backlinks of the target tasks.result.items.new_referring_domains: type: integer description: number of new referring domains number of new referring domains pointing to the target tasks.result.items.lost_referring_domains: type: integer description: number of lost referring domains number of lost referring domains of the target tasks.result.items.new_referring_main_domains: type: integer description: number of new referring main domains number of new referring main domains pointing to the target tasks.result.items.lost_referring_main_domains: type: integer description: number of lost referring main domains number of lost referring main domains of the target '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com"' date_from: type: string description: 'starting date of the time range optional field this field indicates the date which will be used as a threshold for new and lost backlinks and referring domains; the backlinks and referring domains that appeared in our index after the specified date will be considered as new; the backlinks and referring domains that weren’t found after the specified date, but were present before, will be considered as lost; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15"' group_range: type: string description: 'time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/timeseries_new_lost_summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/backlinks/timeseries_summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.048864 max: 0.048936 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlinks Timeseries Summary description: 'One `target`''s core backlink metrics over time, grouped by `group_range` (day, week, month). Returns `date_from`, `date_to`, `group_range` and one item per period. Measured at 1.8 KB for three monthly points, against 4.1 KB for the same span from `post_dataforseo_backlinks_history_live` - use this one unless you need history''s fuller metric set. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, upstream charge in `tasks[0].cost`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For gains and losses rather than totals use `post_dataforseo_backlinks_timeseries_new_lost_live`. 💰 Measured at $0.024 upstream on every endpoint in this family, twice the flat rate billed. This one takes no limit parameter, so the only lever is calling it less often.' operationId: post_dataforseo_backlinks_timeseries_summary_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.target: type: string description: target from a POST array tasks.result.date_from: type: string description: 'starting date of the time range in the UTC format: “yyyy-mm-dd” example: 2019-01-01' tasks.result.date_to: type: string description: 'ending date of the time range in the UTC format: "yyyy-mm-dd" example: "2019-01-15"' tasks.result.group_range: type: object description: group_range from a POST array tasks.result.total_count: type: integer description: total amount of results relevant the request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains relevant summary data tasks.result.items.type: type: string description: type of element = ‘backlinks_timeseries_summary’ tasks.result.items.date: type: string description: 'date and time when the data for the target was stored in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.rank: type: integer description: target rank for the given date learn more about the metric and how it is calculated in this help center article tasks.result.items.backlinks: type: integer description: number of backlinks for the given date tasks.result.items.backlinks_nofollow: type: integer description: number of nofollow backlinks for the given date tasks.result.items.referring_pages: type: integer description: number of pages pointing to target for the given date tasks.result.items.referring_domains: type: integer description: number of referring domains for the given date referring domains include subdomains that are counted as separate domains for this metric tasks.result.items.referring_domains_nofollow: type: integer description: number of domains pointing at least one nofollow link to the target for the given date tasks.result.items.referring_main_domains: type: integer description: number of referring main domains for the given date tasks.result.items.referring_main_domains_nofollow: type: integer description: number of main domains pointing at least one nofollow link to the target for the given date tasks.result.items.referring_ips: type: integer description: number of referring IP addresses for the given date number of IP addresses pointing to this page tasks.result.items.referring_subnets: type: integer description: number of referring subnetworks for the given date tasks.result.items.referring_pages_nofollow: type: integer description: number of referring pages pointing at least one nofollow link to the target for the given date '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: 'domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com"' date_from: type: string description: 'starting date of the time range optional field this field indicates the date which will be used as a threshold for summary data; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15"' group_range: type: string description: 'time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0' include_subdomains: type: boolean description: 'indicates if the subdomains of the target will be included in the search optional field if set to false, the subdomains will be ignored default value: true' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works and how ranking metrics are calculated in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/backlinks/timeseries_summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/content_parsing/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0003 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live OnPage API Content Parsing description: 'Parses any `url` into structured content immediately, with no crawl needed - the only tool in this family that works standalone. `browser_preset`, `browser_screen_width`, `browser_screen_height` and `custom_user_agent` control the render, `disable_cookie_popup` removes consent overlays, `store_raw_html` keeps the source. Measured at 1.2 KB for example.com and $0.00015. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For pages already inside a crawl use `post_dataforseo_on_page_content_parsing`, which is free.' operationId: post_dataforseo_on_page_content_parsing_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of the returned item = ‘сontent_parsing_element’ tasks.result.items.fetch_time: type: string description: 'date and time when the content was fetched in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: "2022-11-01 10:02:52 +00:00"' tasks.result.items.status_code: type: integer description: status code of the page tasks.result.items.page_content: type: object description: parsed content of the page tasks.result.items.page_content.header: type: object description: parsed content of the header tasks.result.items.page_content.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.primary_content.text: type: string description: content text tasks.result.items.page_content.primary_content.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.primary_content.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.primary_content.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.primary_content.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.secondary_content: type: array items: type: string description: secondary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.secondary_content.text: type: string description: content text tasks.result.items.page_content.secondary_content.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.secondary_content.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.secondary_content.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.secondary_content.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content: type: array items: type: string description: content of the table on the page tasks.result.items.page_content.table_content.header: type: array items: type: string description: content of the header of the table tasks.result.items.page_content.table_content.header.row_cells: type: array items: type: string description: content of the row cells of the header tasks.result.items.page_content.table_content.header.row_cells.text: type: string description: text in the row cell tasks.result.items.page_content.table_content.header.row_cells.urls: type: array items: type: string description: contains other URLs and anchors found in the cell tasks.result.items.page_content.table_content.header.row_cells.urls.url: type: string description: URL found in the cell tasks.result.items.page_content.table_content.header.row_cells.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content.header.row_cells.is_header: type: boolean description: indicates if the text belongs to the header tasks.result.items.page_content.table_content.body: type: array items: type: string description: content of the body of the table tasks.result.items.page_content.table_content.body.row_cells: type: array items: type: string description: content of the row cells of the header tasks.result.items.page_content.table_content.body.row_cells.text: type: string description: text in the row cell tasks.result.items.page_content.table_content.body.row_cells.urls: type: array items: type: string description: contains other URLs and anchors found in the cell tasks.result.items.page_content.table_content.body.row_cells.urls.url: type: string description: URL found in the cell tasks.result.items.page_content.table_content.body.row_cells.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content.body.row_cells.is_header: type: boolean description: indicates if the text belongs to the header tasks.result.items.page_content.table_content.footer: type: array items: type: string description: content of the footer of the table tasks.result.items.page_content.table_content.footer.row_cells: type: array items: type: string description: content of the row cells of the header tasks.result.items.page_content.table_content.footer.row_cells.text: type: string description: text in the row cell tasks.result.items.page_content.table_content.footer.row_cells.urls: type: array items: type: string description: contains other URLs and anchors found in the cell tasks.result.items.page_content.table_content.footer.row_cells.urls.url: type: string description: URL found in the cell tasks.result.items.page_content.table_content.footer.row_cells.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content.footer.row_cells.is_header: type: boolean description: indicates if the text belongs to the header tasks.result.items.page_content.footer: type: object description: parsed content of the footer tasks.result.items.page_content.main_topic: type: array items: type: string description: main topic on the page you can find more information about topic priority calculation in this help center article tasks.result.items.page_content.main_topic.h_title: type: string description: meta title tasks.result.items.page_content.main_topic.main_title: type: string description: main title of the block tasks.result.items.page_content.main_topic.author: type: string description: content author name tasks.result.items.page_content.main_topic.language: type: string description: content language tasks.result.items.page_content.main_topic.level: type: string description: HTML level tasks.result.items.page_content.main_topic.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.main_topic.text: type: string description: content text tasks.result.items.page_content.main_topic.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.main_topic.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.main_topic.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.main_topic.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.main_topic.secondary_content: type: array items: type: string description: secondary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.secondary_topic: type: array items: type: string description: secondary topic on the page you can find more information about topic priority calculation in this help center article tasks.result.items.page_content.secondary_topic.h_title: type: string description: meta title tasks.result.items.page_content.secondary_topic.main_title: type: string description: main title of the block tasks.result.items.page_content.secondary_topic.author: type: string description: content author name tasks.result.items.page_content.secondary_topic.language: type: string description: content language tasks.result.items.page_content.secondary_topic.level: type: string description: HTML level tasks.result.items.page_content.secondary_topic.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.secondary_topic.text: type: string description: content text tasks.result.items.page_content.secondary_topic.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.secondary_topic.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.secondary_topic.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.secondary_topic.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.secondary_topic.secondary_content: type: array items: type: string description: secondary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.ratings: type: array items: type: string description: contains objects with rating information for the products displayed on the page tasks.result.items.page_content.ratings.name: type: string description: 'rating name Note: this field is not used in this particular object, and its value is always set to null' tasks.result.items.page_content.ratings.rating_value: type: integer description: the value of the rating tasks.result.items.page_content.ratings.max_rating_value: type: integer description: maximum value for the rating tasks.result.items.page_content.ratings.rating_count: type: integer description: the amount of feedback tasks.result.items.page_content.ratings.relative_rating: type: number description: relative rating can take values from 0 to 1 tasks.result.items.page_content.offers: type: array items: type: string description: array of products displayed on the page contains objects with information on products displayed on the page tasks.result.items.page_content.offers.name: type: string description: name of the product tasks.result.items.page_content.offers.price: type: integer description: price of the product tasks.result.items.page_content.offers.price_currency: type: string description: price currency tasks.result.items.page_content.offers.price_valid_until: type: integer description: 'displays the date and time until which the price is valid in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: "2022-11-01 10:02:52 +00:00"' tasks.result.items.page_content.comments: type: array items: type: string description: array of comments displayed on the page contains objects with information on comments related to displayed products tasks.result.items.page_content.comments.rating: type: object description: product’s rating contains information about the rating a customer has given to the product tasks.result.items.page_content.comments.name: type: string description: 'rating name Note: this field is not used in this particular object, and its value is always null' tasks.result.items.page_content.comments.rating_value: type: integer description: the value of the rating tasks.result.items.page_content.comments.max_rating_value: type: integer description: maximum value for the rating tasks.result.items.page_content.comments.rating_count: type: integer description: 'the amount of feedback Note: this field is not used in this particular object, and its value is always null' tasks.result.items.page_content.comments.relative rating: type: number description: relative rating can take values from 0 to 1 tasks.result.items.page_content.comments.title: type: string description: title of the customer’s comment tasks.result.items.page_content.comments.publish_date: type: string description: date when the comment was published tasks.result.items.page_content.comments.author: type: string description: author of the comment tasks.result.items.page_content.comments.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.comments.primary_content.text: type: string description: text of the comment tasks.result.items.page_content.comments.primary_content.url: type: string description: displayed in case the text is a link anchor tasks.result.items.page_content.comments.primary_content.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.contacts: type: object description: contact information contains contact information displayed on the page tasks.result.items.page_content.contacts.telephones: type: array items: type: string description: array of telephone numbers tasks.result.items.page_content.contacts.emails: type: array items: type: string description: array of emails tasks.result.items.page_as_markdown: type: string description: page content in the markdown format page content in the text-to-HTML markdown format specify markdown_view as true in the request to return the value '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: url: type: string description: 'URL of the content to parse required field URL of the page to parse example: https://www.fujielectric.com/' custom_user_agent: type: string description: 'custom user agent optional field custom user agent for crawling a website example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36 default value: Mozilla/5.0 (compatible; RSiteAuditor)' browser_preset: type: string description: 'preset for browser screen parameters optional field if you use this field, you don’t need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factor possible values: desktop, mobile, tablet desktop preset will apply the following values: browser_screen_width: 1920 browser_screen_height: 1080 browser_screen_scale_factor: 1 mobile preset will apply the following values: browser_screen_width: 390 browser_screen_height: 844 browser_screen_scale_factor: 3 tablet preset will apply the following values: browser_screen_width: 1024 browser_screen_height: 1366 browser_screen_scale_factor: 2 Note: to use this parameter, set enable_javascript or enable_browser_rendering to true' browser_screen_width: type: integer description: 'browser screen width optional field you can set a custom browser screen width to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; Note: to use this parameter, set enable_javascript or enable_browser_rendering to true minimum value, in pixels: 240 maximum value, in pixels: 9999' browser_screen_height: type: integer description: 'browser screen height optional field you can set a custom browser screen height to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; Note: to use this parameter, set enable_javascript or enable_browser_rendering to true minimum value, in pixels: 240 maximum value, in pixels: 9999' browser_screen_scale_factor: type: number description: 'browser screen scale factor optional field you can set a custom browser screen resolution ratio to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; Note: to use this parameter, set enable_javascript or enable_browser_rendering to true minimum value: 0.5 maximum value: 3' store_raw_html: type: boolean description: 'store HTML of a crawled page optional field set to true if you want to get the HTML of the page using the OnPage Raw HTML endpoint default value: false' disable_cookie_popup: type: boolean description: 'disable the cookie popup optional field set to true if you want to disable the popup requesting cookie consent from the user; default value: false' accept_language: type: string description: 'language header for accessing the website optional field all locale formats are supported (xx, xx-XX, xxx-XX, etc.) Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the "type":"broken in the response array' enable_javascript: type: boolean description: 'load javascript on a page optional field set to true if you want to load the scripts available on a page default value: false Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page' enable_browser_rendering: type: boolean description: 'emulate browser rendering to measure Core Web Vitals optional field by using this parameter you will be able to emulate a browser when loading a web page; enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page; default value: false set to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response; if you use this field, enable_javascript, and load_resources parameters must be set to true Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page' enable_xhr: type: boolean description: 'enable XMLHttpRequest on a page optional field set to true if you want our crawler to request data from a web server using the XMLHttpRequest object default value: false if you use this field, enable_javascript must be set to true;' switch_pool: type: boolean description: switch proxy pool optional field if true, additional proxy pools will be used to obtain the requested data; the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors ip_pool_for_scan: type: string description: 'proxy pool optional field you can choose a location of the proxy pool that will be used to obtain the requested data; the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errors possible values: us, de' markdown_view: type: boolean description: 'return page content as markdown optional field if set to true, the markdown-formatted content of the page will be returned in the page_as_markdown field of the response; default value: false' required: - url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/content_parsing/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/content_parsing: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Content Parsing description: Parses one crawled `url` into structured content, with `markdown_view` for a markdown rendering. Measured at 592 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. The standalone twin `post_dataforseo_on_page_content_parsing_live` parses any URL without a crawl - prefer that unless the page is already part of one. operationId: post_dataforseo_on_page_content_parsing responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of the returned item = ‘сontent_parsing_element’ tasks.result.items.fetch_time: type: string description: 'date and time when the content was fethced example: "2022-11-01 10:02:52 +00:00"' tasks.result.items.status_code: type: integer description: status code of the page tasks.result.items.page_content: type: object description: parsed content of the page tasks.result.items.page_content.header: type: object description: parsed content of the header tasks.result.items.page_content.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.primary_content.text: type: string description: content text tasks.result.items.page_content.primary_content.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.primary_content.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.primary_content.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.primary_content.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.secondary_content: type: array items: type: string description: secondary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.secondary_content.text: type: string description: content text tasks.result.items.page_content.secondary_content.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.secondary_content.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.secondary_content.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.secondary_content.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content: type: array items: type: string description: content of the table on the page tasks.result.items.page_content.table_content.header: type: array items: type: string description: content of the header of the table tasks.result.items.page_content.table_content.header.row_cells: type: array items: type: string description: content of the row cells of the header tasks.result.items.page_content.table_content.header.row_cells.text: type: string description: text in the row cell tasks.result.items.page_content.table_content.header.row_cells.urls: type: array items: type: string description: contains other URLs and anchors found in the cell tasks.result.items.page_content.table_content.header.row_cells.urls.url: type: string description: URL found in the cell tasks.result.items.page_content.table_content.header.row_cells.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content.header.row_cells.is_header: type: boolean description: indicates if the text belongs to the header tasks.result.items.page_content.table_content.body: type: array items: type: string description: content of the body of the table tasks.result.items.page_content.table_content.body.row_cells: type: array items: type: string description: content of the row cells of the header tasks.result.items.page_content.table_content.body.row_cells.text: type: string description: text in the row cell tasks.result.items.page_content.table_content.body.row_cells.urls: type: array items: type: string description: contains other URLs and anchors found in the cell tasks.result.items.page_content.table_content.body.row_cells.urls.url: type: string description: URL found in the cell tasks.result.items.page_content.table_content.body.row_cells.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content.body.row_cells.is_header: type: boolean description: indicates if the text belongs to the header tasks.result.items.page_content.table_content.footer: type: array items: type: string description: content of the footer of the table tasks.result.items.page_content.table_content.footer.row_cells: type: array items: type: string description: content of the row cells of the header tasks.result.items.page_content.table_content.footer.row_cells.text: type: string description: text in the row cell tasks.result.items.page_content.table_content.footer.row_cells.urls: type: array items: type: string description: contains other URLs and anchors found in the cell tasks.result.items.page_content.table_content.footer.row_cells.urls.url: type: string description: URL found in the cell tasks.result.items.page_content.table_content.footer.row_cells.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.table_content.footer.row_cells.is_header: type: boolean description: indicates if the text belongs to the header tasks.result.items.page_content.footer: type: object description: parsed content of the footer tasks.result.items.page_content.main_topic: type: array items: type: string description: main topic on the page you can find more information about topic priority calculation in this help center article tasks.result.items.page_content.main_topic.h_title: type: string description: meta title tasks.result.items.page_content.main_topic.main_title: type: string description: main title of the block tasks.result.items.page_content.main_topic.author: type: string description: content author name tasks.result.items.page_content.main_topic.language: type: string description: content language tasks.result.items.page_content.main_topic.level: type: string description: HTML level tasks.result.items.page_content.main_topic.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.main_topic.text: type: string description: content text tasks.result.items.page_content.main_topic.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.main_topic.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.main_topic.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.main_topic.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.main_topic.secondary_content: type: array items: type: string description: secondary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.secondary_topic: type: array items: type: string description: secondary topic on the page you can find more information about topic priority calculation in this help center article tasks.result.items.page_content.secondary_topic.h_title: type: string description: meta title tasks.result.items.page_content.secondary_topic.main_title: type: string description: main title of the block tasks.result.items.page_content.secondary_topic.author: type: string description: content author name tasks.result.items.page_content.secondary_topic.language: type: string description: content language tasks.result.items.page_content.secondary_topic.level: type: string description: HTML level tasks.result.items.page_content.secondary_topic.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.secondary_topic.text: type: string description: content text tasks.result.items.page_content.secondary_topic.url: type: string description: page URL displayed in case the text is a link anchor tasks.result.items.page_content.secondary_topic.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.secondary_topic.urls.url: type: string description: other URL found in the content element tasks.result.items.page_content.secondary_topic.urls.anchor_text: type: string description: text of the URL’s anchor tasks.result.items.page_content.secondary_topic.secondary_content: type: array items: type: string description: secondary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.ratings: type: array items: type: string description: contains objects with rating information for the products displayed on the page tasks.result.items.page_content.ratings.name: type: string description: 'rating name Note: this field is not used in this particular object, and its value is always set to null' tasks.result.items.page_content.ratings.rating_value: type: integer description: the value of the rating tasks.result.items.page_content.ratings.max_rating_value: type: integer description: maximum value for the rating tasks.result.items.page_content.ratings.rating_count: type: integer description: the amount of feedback tasks.result.items.page_content.ratings.relative_rating: type: number description: relative rating can take values from 0 to 1 tasks.result.items.page_content.offers: type: array items: type: string description: array of products displayed on the page contains objects with information on products displayed on the page tasks.result.items.page_content.offers.name: type: string description: name of the product tasks.result.items.page_content.offers.price: type: integer description: price of the product tasks.result.items.page_content.offers.price_currency: type: string description: price currency tasks.result.items.page_content.offers.price_valid_until: type: integer description: 'displays the date and time until which the price is valid in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: "2022-11-01 10:02:52 +00:00"' tasks.result.items.page_content.comments: type: array items: type: string description: array of comments displayed on the page contains objects with information on comments related to displayed products tasks.result.items.page_content.comments.rating: type: object description: product’s rating contains information about the rating a customer has given to the product tasks.result.items.page_content.comments.name: type: string description: 'rating name Note: this field is not used in this particular object, and its value is always null' tasks.result.items.page_content.comments.rating_value: type: integer description: the value of the rating tasks.result.items.page_content.comments.max_rating_value: type: integer description: maximum value for the rating tasks.result.items.page_content.comments.rating_count: type: integer description: 'the amount of feedback Note: this field is not used in this particular object, and its value is always null' tasks.result.items.page_content.comments.relative rating: type: number description: relative rating can take values from 0 to 1 tasks.result.items.page_content.comments.title: type: string description: title of the customer’s comment tasks.result.items.page_content.comments.publish_date: type: string description: date when the comment was published tasks.result.items.page_content.comments.author: type: string description: author of the comment tasks.result.items.page_content.comments.primary_content: type: array items: type: string description: primary content on the page you can find more information about content priority calculation in this help center article tasks.result.items.page_content.comments.primary_content.text: type: string description: text of the comment tasks.result.items.page_content.comments.primary_content.url: type: string description: displayed in case the text is a link anchor tasks.result.items.page_content.comments.primary_content.urls: type: array items: type: string description: contains other URLs and anchors found in the content element tasks.result.items.page_content.contacts: type: object description: contact information contains contact information displayed on the page tasks.result.items.page_content.contacts.telephones: type: array items: type: string description: array of telephone numbers tasks.result.items.page_content.contacts.emails: type: array items: type: string description: array of emails tasks.result.items.page_as_markdown: type: string description: page content in the markdown format page content in the text-to-HTML markdown format specify markdown_view as true in the request to return the value '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: url: type: string description: 'URL of the content to parse required field URL of the page to parse example: https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api' id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint note: the enable_content_parsing parameter in the POST request must be set to true example: "07131248-1535-0216-1000-17384017ad04"' markdown_view: type: boolean description: 'return page content as markdown optional field if set to true, the markdown-formatted content of the page will be returned in the page_as_markdown field of the response; default value: false' required: - url - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/content_parsing source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/duplicate_content: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Duplicate Content description: 'Pages within a crawl whose content resembles a given `url`, above a `similarity` threshold. Measured at 606 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. For duplicated titles or meta descriptions rather than body text, use `post_dataforseo_on_page_duplicate_tags`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_duplicate_content responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.url: type: string description: URL of the specified page tasks.result.items.total_count: type: integer description: total count of duplicate pages tasks.result.items.pages: type: array items: type: string description: pages with duplicate content tasks.result.items.pages.similarity: type: integer description: content similarity score by default, the content is considered duplicate if the value is greater than or equals 6 can take values from 0 to 10 tasks.result.items.pages.page: type: array items: type: string description: information about the page with duplicate content tasks.result.items.pages.page.resource_type: type: string description: type of the returned resource = ‘html’ tasks.result.items.pages.page.status_code: type: integer description: status code of the page tasks.result.items.pages.page.location: type: string description: location header indicates the URL to redirect a page to tasks.result.items.pages.page.url: type: string description: page URL tasks.result.items.pages.page.meta: type: object description: page properties the value depends on the resource_type tasks.result.items.pages.page.meta.title: type: integer description: page title tasks.result.items.pages.page.meta.charset: type: integer description: 'code page example: 65001' tasks.result.items.pages.page.meta.follow: type: boolean description: indicates whether a page’s ‘meta robots’ allows crawlers to follow the links on the page if false, the page’s ‘meta robots’ tag contains “nofollow” parameter instructing crawlers not to follow the links on the page tasks.result.items.pages.page.meta.generator: type: string description: meta tag generator tasks.result.items.pages.page.meta.htags: type: object description: HTML header tags tasks.result.items.pages.page.meta.description: type: string description: content of the meta description tag tasks.result.items.pages.page.meta.favicon: type: string description: favicon of the page tasks.result.items.pages.page.meta.meta_keywords: type: string description: content of the keywords meta tag tasks.result.items.pages.page.meta.canonical: type: string description: canonical page tasks.result.items.pages.page.meta.internal_links_count: type: integer description: number of internal links on the page tasks.result.items.pages.page.meta.external_links_count: type: integer description: number of external links on the page tasks.result.items.pages.page.meta.inbound_links_count: type: integer description: number of internal links pointing at the page tasks.result.items.pages.page.meta.images_count: type: integer description: number of images on the page tasks.result.items.pages.page.meta.images_size: type: integer description: total size of images on the page measured in bytes tasks.result.items.pages.page.meta.scripts_count: type: integer description: number of scripts on the page tasks.result.items.pages.page.meta.scripts_size: type: integer description: total size of scripts on the page measured in bytes tasks.result.items.pages.page.meta.stylesheets_count: type: integer description: number of stylesheets on the page tasks.result.items.pages.page.meta.stylesheets_size: type: integer description: total size of stylesheets on the page measured in bytes tasks.result.items.pages.page.meta.title_length: type: integer description: length of the title tag in characters tasks.result.items.pages.page.meta.description_length: type: integer description: length of the description tag in characters tasks.result.items.pages.page.meta.render_blocking_scripts_count: type: integer description: number of scripts on the page that block page rendering tasks.result.items.pages.page.meta.render_blocking_stylesheets_count: type: integer description: number of CSS styles on the page that block page rendering tasks.result.items.pages.page.meta.cumulative_layout_shift: type: number description: Core Web Vitals metric measuring the layout stability of a page measures the sum total of all individual layout shift scores for every unexpected layout shift that occurs during the entire lifespan of the page. Learn more. tasks.result.items.pages.page.meta.content: type: object description: overall information about content of the page tasks.result.items.pages.page.meta.content.plain_text_size: type: integer description: total size of the text on the page measured in bytes tasks.result.items.pages.page.meta.content.plain_text_rate: type: integer description: plaintext rate value plain_text_size to size ratio tasks.result.items.pages.page.meta.content.plain_text_word_count: type: number description: number of words on the page tasks.result.items.pages.page.meta.content.automated_readability_index: type: number description: Automated Readability Index tasks.result.items.pages.page.meta.content.coleman_liau_readability_index: type: number description: Coleman–Liau Index tasks.result.items.pages.page.meta.content.dale_chall_readability_index: type: number description: Dale–Chall Readability Index tasks.result.items.pages.page.meta.content.flesch_kincaid_readability_index: type: number description: Flesch–Kincaid Readability Index tasks.result.items.pages.page.meta.content.smog_readability_index: type: number description: SMOG Readability Index tasks.result.items.pages.page.meta.content.description_to_content_consistency: type: number description: consistency of the meta description tag with the page content measured from 0 to 1 tasks.result.items.pages.page.meta.content.title_to_content_consistency: type: number description: consistency of the meta title tag with the page content measured from 0 to 1 tasks.result.items.pages.page.meta.content.meta_keywords_to_content_consistency: type: number description: consistency of meta keywordstag with the page content measured from 0 to 1 tasks.result.items.pages.page.meta.deprecated_tags: type: array items: type: string description: deprecated tags on the page tasks.result.items.pages.page.meta.duplicate_meta_tags: type: array items: type: string description: duplicate meta tags on the page tasks.result.items.pages.page.meta.spell: type: object description: spellcheck hunspell spellcheck errors tasks.result.items.pages.page.meta.spell.hunspell_language_code: type: string description: spellcheck language code tasks.result.items.pages.page.meta.spell.misspelled: type: array items: type: string description: array of misspelled words tasks.result.items.pages.page.meta.spell.misspelled.word: type: string description: misspelled word tasks.result.items.pages.page.meta.resource_errors: type: object description: resource errors and warnings tasks.result.items.pages.page.meta.resource_errors.errors: type: array items: type: string description: resource errors tasks.result.items.pages.page.meta.resource_errors.errors.line: type: integer description: line where the error was found tasks.result.items.pages.page.meta.resource_errors.errors.message: type: string description: text message of the error the full list of possible HTML errors can be found here tasks.result.items.pages.page.meta.resource_errors.warnings: type: array items: type: string description: resource warnings tasks.result.items.pages.page.meta.resource_errors.warnings.line: type: integer description: 'line the warning relates to note that if "line": 0, the warning relates to the whole page' tasks.result.items.pages.page.meta.resource_errors.warnings.message: type: string description: 'text message of the warning possible messages: "Has node with more than 60 childs." – HTML page has at least 1 tag nesting over 60 tags of the same level "Has more that 1500 nodes." – DOM tree contains over 1,500 elements "HTML depth more than 32 tags." – DOM depth exceeds 32 nodes' tasks.result.items.pages.page.meta.social_media_tags: type: object description: array of social media tags found on the page contains social media tags and their content supported tags include but are not limited to Open Graph and Twitter card tasks.result.items.pages.page.page_timing: type: object description: object of page load metrics tasks.result.items.pages.page.page_timing.time_to_interactive: type: integer description: Time To Interactive (TTI) metric the time it takes until the user can interact with a page (in milliseconds) tasks.result.items.pages.page.page_timing.dom_complete: type: integer description: time to load resources the time it takes until the page and all of its subresources are downloaded (in milliseconds) tasks.result.items.pages.page.page_timing.largest_contentful_paint: type: number description: Core Web Vitals metric measuring how fast the largest above-the-fold content element is displayed The amount of time (in milliseconds) to render the largest content element visible in the viewport, from when the user requests the URL. Learn more. tasks.result.items.pages.page.page_timing.first_input_delay: type: number description: Core Web Vitals metric indicating the responsiveness of a page The time (in milliseconds) from when a user first interacts with your page to the time when the browser responds to that interaction. Learn more. tasks.result.items.pages.page.page_timing.connection_time: type: integer description: time to connect to a server the time it takes until the connection with a server is established (in milliseconds) tasks.result.items.pages.page.page_timing.time_to_secure_connection: type: integer description: time to establish a secure connection the time it takes until the secure connection with a server is established (in milliseconds) tasks.result.items.pages.page.page_timing.request_sent_time: type: integer description: time to send a request to a server the time it takes until the request to a server is sent (in milliseconds) tasks.result.items.pages.page.page_timing.waiting_time: type: integer description: time to first byte (TTFB) in milliseconds tasks.result.items.pages.page.page_timing.download_time: type: integer description: time it takes for a browser to receive a response (in milliseconds) tasks.result.items.pages.page.page_timing.duration_time: type: integer description: total time it takes until a browser receives a complete response from a server (in milliseconds) tasks.result.items.pages.page.page_timing.fetch_start: type: integer description: time to start downloading the HTML resource the amount of time the browser needs to start downloading a page tasks.result.items.pages.page.page_timing.fetch_end: type: integer description: time to complete downloading the HTML resource the amount of time the browser needs to complete downloading a page tasks.result.items.pages.page.onpage_score: type: number description: shows how page is optimized on a 100-point scale this field shows how page is optimized considering critical on-page issues and warnings detected; 100 is the highest possible score that means the page does not have any critical on-page issues and important warnings; learn more about how the metric is calculated in this help center article tasks.result.items.pages.page.total_dom_size: type: integer description: total DOM size of a page tasks.result.items.pages.page.custom_js_response: type: string description: 'the result of executing a specified JS script note that you should specify a custom_js field when setting a task to receive this data and the field type and its value will totally depend on the script you specified;you can also filter the results by this value specifying filters in the following way: ["custom_js_response.url", "like", "pixel"]' tasks.result.items.pages.page.custom_js_client_exception: type: string description: error when executing a custom js if the error occurred when executing the script you specified in the custom_js field, the error message would be displayed here tasks.result.items.pages.page.broken_resources: type: boolean description: indicates whether a page contains broken resources tasks.result.items.pages.page.broken_links: type: boolean description: indicates whether a page contains broken links tasks.result.items.pages.page.duplicate_title: type: boolean description: indicates whether a page has duplicate title tags tasks.result.items.pages.page.duplicate_description: type: boolean description: indicates whether a page has a duplicate description tasks.result.items.pages.page.duplicate_content: type: boolean description: indicates whether a page has duplicate content tasks.result.items.pages.page.click_depth: type: integer description: number of clicks it takes to get to the page indicates the number of clicks from the homepage needed before landing at the target page tasks.result.items.pages.page.size: type: integer description: resource size indicates the size of a given page measured in bytes tasks.result.items.pages.page.encoded_size: type: integer description: page size after encoding indicates the size of the encoded page measured in bytes tasks.result.items.pages.page.total_transfer_size: type: integer description: compressed page size indicates the compressed size of a given page tasks.result.items.pages.page.fetch_time: type: string description: 'date and time when a resource was fetched in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.items.pages.page.cache_control: type: object description: instructions for caching tasks.result.items.pages.page.cache_control.cachable: type: boolean description: indicates whether the page is cacheable tasks.result.items.pages.page.cache_control.ttl: type: integer description: time to live the amount of time the browser caches a resource tasks.result.items.pages.page.checks: type: object description: website checks on-page check-ups related to the page tasks.result.items.pages.page.checks.no_content_encoding: type: boolean description: page with no content encoding indicates whether a page has no compression algorithm of the content tasks.result.items.pages.page.checks.high_loading_time: type: boolean description: page with high loading time indicates whether a page loading time exceeds 3 seconds tasks.result.items.pages.page.checks.is_redirect: type: boolean description: page with redirects indicates whether a page has 3XX redirects to other pages tasks.result.items.pages.page.checks.is_4xx_code: type: boolean description: page with 4xx status codes indicates whether a page has 4xx response code tasks.result.items.pages.page.checks.is_5xx_code: type: boolean description: page with 5xx status codes indicates whether a page has 5xx response code tasks.result.items.pages.page.checks.is_broken: type: boolean description: broken page indicates whether a page returns a response code less than 200 or greater than 400 tasks.result.items.pages.page.checks.is_www: type: boolean description: page with www indicates whether a page is on a www subdomain tasks.result.items.pages.page.checks.is_https: type: boolean description: page with the https protocol tasks.result.items.pages.page.checks.is_http: type: boolean description: page with the http protocol tasks.result.items.pages.page.checks.high_waiting_time: type: boolean description: page with high waiting time indicates whether a page waiting time (aka Time to First Byte) exceeds 1.5 seconds tasks.result.items.pages.page.checks.no_doctype: type: boolean description: page with no doctype indicates whether a page is without the declaration tasks.result.items.pages.page.checks.canonical: type: boolean description: page is canonical tasks.result.items.pages.page.checks.no_encoding_meta_tag: type: boolean description: 'page with no meta tag encoding indicates whether a page is without Content-Type; informative only if the encoding is not explicit in the Content-Type header; for example: Content-Type: "text/html; charset=utf8"; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.no_h1_tag: type: boolean description: 'page with empty or absent h1 tags Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.https_to_http_links: type: boolean description: 'HTTPS page has links to HTTP pages if true, this HTTPS page has links to HTTP pages Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.has_html_doctype: type: boolean description: page with HTML doctype declaration if true, the page has HTML DOCTYPE declaration tasks.result.items.pages.page.checks.size_greater_than_3mb: type: boolean description: 'page with size larger than 3 MB if true, the page size is exceeding 3 MB; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.meta_charset_consistency: type: boolean description: 'consistency between charset encoding and page charset if true, the page’s charset encoding doesn’t match the actual charset of the page; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.has_meta_refresh_redirect: type: boolean description: 'pages with meta refresh redirect if true, the page has tag that instructs a browser to load another page after a specified time span; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.has_render_blocking_resources: type: boolean description: 'page with render-blocking resources if true, the page has render-blocking scripts or stylesheets; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.redirect_chain: type: boolean description: page with multiple redirects if true, there were at least two redirects before our crawler reached this page tasks.result.items.pages.page.checks.low_content_rate: type: boolean description: 'page with low content rate indicates whether a page has the plaintext size to page size ratio of less than 0.1; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.high_content_rate: type: boolean description: 'page with high content rate indicates whether a page has the plaintext size to page size ratio of more than 0.9; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.low_character_count: type: boolean description: 'indicates whether the page has less than 1024 characters Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.high_character_count: type: boolean description: 'indicates whether the page has more than 256,000 characters Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.small_page_size: type: boolean description: 'indicates whether a page is too small the value will be true if a page size is smaller than 1024 bytes; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.large_page_size: type: boolean description: 'indicates whether a page is too heavy the value will be true if a page size exceeds 1 megabyte; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.low_readability_rate: type: boolean description: 'page with a low readability rate indicates whether a page is scored less than 15 points on the Flesch–Kincaid readability test; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.irrelevant_description: type: boolean description: 'page with irrelevant description indicates whether a page description tag is irrelevant to the content of a page; the relevance threshold is 0.2; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.irrelevant_title: type: boolean description: 'page with irrelevant title indicates whether a page title tag is irrelevant to the content of the page the relevance threshold is 0.3 Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.irrelevant_meta_keywords: type: boolean description: 'page with irrelevant meta keywords indicates whether a page keywords tags are irrelevant to the content of a page the relevance threshold is 0.6 Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.title_too_long: type: boolean description: 'page with a long title indicates whether the content of the title tag exceeds 65 characters; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.title_too_short: type: boolean description: 'page with short titles indicates whether the content of title tag is shorter than 30 characters; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.deprecated_html_tags: type: boolean description: 'page with deprecated tags indicates whether a page has deprecated HTML tags; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.duplicate_meta_tags: type: boolean description: 'page with duplicate meta tags indicates whether a page has more than one meta tag of the same type; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.duplicate_title_tag: type: boolean description: 'page with more than one title tag indicates whether a page has more than one title tag; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.no_image_alt: type: boolean description: 'images without alt tags Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.no_image_title: type: boolean description: 'images without title tags Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.no_description: type: boolean description: 'pages with no description indicates whether a page has an empty or absent description meta tag; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.no_title: type: boolean description: 'page with no title indicates whether a page has an empty or absent title tag; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.no_favicon: type: boolean description: 'page with no favicon Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.seo_friendly_url: type: boolean description: 'page with seo-frienldy URL the ‘SEO-friendliness’ of a page URL is checked by four parameters: – the length of the relative path is less than 120 characters – no special characters – no dynamic parameters – relevance of the URL to the page if at least one of them is failed then such URL is considered as not ‘SEO-friendly’; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.flash: type: boolean description: page with flash indicates whether a page has flash elements tasks.result.items.pages.page.checks.frame: type: boolean description: page with frames indicates whether a page contains frame, iframe, frameset tags tasks.result.items.pages.page.checks.lorem_ipsum: type: boolean description: 'page with lorem ipsum indicates whether a page has lorem ipsum content; Note: available for pages with canonical check set to true' tasks.result.items.pages.page.checks.has_misspelling: type: boolean description: page with misspelled content tasks.result.items.pages.page.checks.seo_friendly_url_characters_check: type: boolean description: URL characters check-up indicates whether a page URL containing only uppercase and lowercase Latin characters, digits and dashes tasks.result.items.pages.page.checks.seo_friendly_url_dynamic_check: type: boolean description: URL dynamic check-up the value will be true if a page has no dynamic parameters in the url tasks.result.items.pages.page.checks.seo_friendly_url_keywords_check: type: boolean description: URL keyword check-up indicates whether a page URL is consistent with the title meta tag tasks.result.items.pages.page.checks.seo_friendly_url_relative_length_check: type: boolean description: URL length check-up the value will be true if a page URL no longer than 120 characters tasks.result.items.pages.page.checks.is_orphan_page: type: boolean description: page with no internal links pointing to it true if the page has no reference from other pages of the domain tasks.result.items.pages.page.checks.is_link_relation_conflict: type: boolean description: mix of both followed and nofollowed incoming internal links true if the page receives at least one link with the rel="nofollow" attribute and at least one dofollow link tasks.result.items.pages.page.checks.has_links_to_redirects: type: boolean description: page is pointing to a page that redirect elsewhere true if the page is pointing to a page that responds with a 3XX redirect tasks.result.items.pages.page.checks.recursive_canonical: type: boolean description: recursive canonical error true if the page contains rel="canonical" tag to another page, which in turn, refers back to the initial page tasks.result.items.pages.page.checks.canonical_chain: type: boolean description: pages with canonical pointing to a page that has a canonical pointing elsewhere true if the page has a canonical link element pointing to a page that has a canonical pointing to a different page e.g. page a is canonicalized to page b, which is canonicalized to page c tasks.result.items.pages.page.checks.canonical_to_redirect: type: boolean description: canonical page pointing to a page that redirect elsewhere true if the page has a canonical link element pointing to a page that responds with a 3XX redirect tasks.result.items.pages.page.checks.canonical_to_broken: type: boolean description: canonical link pointing to a broken page true if the page has a a canonical link pointing to a page that responds with a 4xx or 5xx response codes tasks.result.items.pages.page.content_encoding: type: string description: type of encoding tasks.result.items.pages.page.media_type: type: string description: types of media used to display a page tasks.result.items.pages.page.server: type: string description: server version tasks.result.items.pages.page.is_resource: type: boolean description: indicates whether a page is a single resource tasks.result.items.pages.page.last_modified: type: object description: contains data on changes related to the resource if there is no data, the value will be null tasks.result.items.pages.page.header: type: string description: 'date and time when the header was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' tasks.result.items.pages.page.sitemap: type: string description: 'date and time when the sitemap was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' tasks.result.items.pages.page.meta_tag: type: string description: 'date and time when the meta tag was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' url: type: string description: page URL required field specify the initial page you want to receive duplicate content for similarity: type: integer description: content similarity score by default, the content is considered duplicate if the value is greater than or equals 6 you can specify any similarity score in the 0-to-10 range limit: type: integer description: 'the maximum number of returned pages optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned pages optional field default value: 0 if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id - url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/duplicate_content source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/duplicate_tags: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Duplicate Tags description: 'Pages within a crawl sharing a title or meta description. ⚠️ **`type` accepts exactly `duplicate_title` or `duplicate_description`** - anything else, including the obvious ''title'', is rejected with `status_code` 40501 inside an HTTP 200. `accumulator` narrows the result to pages carrying one specific tag value. Returns `total_pages_count`, `pages_count`, `items_count` and `items`. Measured at 850 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. For duplicated body content instead, use `post_dataforseo_on_page_duplicate_content`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_duplicate_tags responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.total_pages_count: type: integer description: total number of pages with duplicate tags displays the total number of pages with duplicate tags of the target website tasks.result.pages_count: type: integer description: number of pages with duplicate tags in the response displays the number of pages with duplicate tags returned in the response tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.accumulator: type: string description: contains the value of duplicated tag tasks.result.total_count: type: integer description: total count of duplicate pages tasks.result.pages: type: array items: type: string description: pages with duplicate tags tasks.result.pages.resource_type: type: string description: type of the returned resource = ‘html’ tasks.result.pages.status_code: type: integer description: status code of the page tasks.result.pages.location: type: string description: location header indicates the URL to redirect a page to tasks.result.pages.url: type: string description: page URL tasks.result.pages.meta: type: object description: page properties the value depends on the resource_type tasks.result.pages.meta.title: type: integer description: page title tasks.result.pages.meta.charset: type: integer description: 'code page example: 65001' tasks.result.pages.meta.follow: type: boolean description: indicates whether a page’s ‘meta robots’ allows crawlers to follow the links on the page if false, the page’s ‘meta robots’ tag contains “nofollow” parameter instructing crawlers not to follow the links on the page tasks.result.pages.meta.generator: type: string description: meta tag generator tasks.result.pages.meta.htags: type: object description: HTML header tags tasks.result.pages.meta.description: type: string description: content of the meta description tag tasks.result.pages.meta.favicon: type: string description: favicon of the page tasks.result.pages.meta.meta_keywords: type: string description: content of the keywords meta tag tasks.result.pages.meta.canonical: type: string description: canonical page tasks.result.pages.meta.internal_links_count: type: integer description: number of internal links on the page tasks.result.pages.meta.external_links_count: type: integer description: number of external links on the page tasks.result.pages.meta.inbound_links_count: type: integer description: number of internal links pointing at the page tasks.result.pages.meta.images_count: type: integer description: number of images on the page tasks.result.pages.meta.images_size: type: integer description: total size of images on the page measured in bytes tasks.result.pages.meta.scripts_count: type: integer description: number of scripts on the page tasks.result.pages.meta.scripts_size: type: integer description: total size of scripts on the page measured in bytes tasks.result.pages.meta.stylesheets_count: type: integer description: number of stylesheets on the page tasks.result.pages.meta.stylesheets_size: type: integer description: total size of stylesheets on the page measured in bytes tasks.result.pages.meta.title_length: type: integer description: length of the title tag in characters tasks.result.pages.meta.description_length: type: integer description: length of the description tag in characters tasks.result.pages.meta.render_blocking_scripts_count: type: integer description: number of scripts on the page that block page rendering tasks.result.pages.meta.render_blocking_stylesheets_count: type: integer description: number of CSS styles on the page that block page rendering tasks.result.pages.meta.cumulative_layout_shift: type: number description: Core Web Vitals metric measuring the layout stability of a page measures the sum total of all individual layout shift scores for every unexpected layout shift that occurs during the entire lifespan of the page. Learn more. tasks.result.pages.meta.content: type: object description: overall information about content of the page tasks.result.pages.meta.content.plain_text_size: type: integer description: total size of the text on the page measured in bytes tasks.result.pages.meta.content.plain_text_rate: type: integer description: plaintext rate value plain_text_size to size ratio tasks.result.pages.meta.content.plain_text_word_count: type: number description: number of words on the page tasks.result.pages.meta.content.automated_readability_index: type: number description: Automated Readability Index tasks.result.pages.meta.content.coleman_liau_readability_index: type: number description: Coleman–Liau Index tasks.result.pages.meta.content.dale_chall_readability_index: type: number description: Dale–Chall Readability Index tasks.result.pages.meta.content.flesch_kincaid_readability_index: type: number description: Flesch–Kincaid Readability Index tasks.result.pages.meta.content.smog_readability_index: type: number description: SMOG Readability Index tasks.result.pages.meta.content.description_to_content_consistency: type: number description: consistency of the meta description tag with the page content measured from 0 to 1 tasks.result.pages.meta.content.title_to_content_consistency: type: number description: consistency of the meta title tag with the page content measured from 0 to 1 tasks.result.pages.meta.content.meta_keywords_to_content_consistency: type: number description: consistency of meta keywordstag with the page content measured from 0 to 1 tasks.result.pages.meta.deprecated_tags: type: array items: type: string description: deprecated tags on the page tasks.result.pages.meta.duplicate_meta_tags: type: array items: type: string description: duplicate meta tags on the page tasks.result.pages.meta.spell: type: object description: spellcheck hunspell spellcheck errors tasks.result.pages.meta.spell.hunspell_language_code: type: string description: spellcheck language code tasks.result.pages.meta.spell.misspelled: type: array items: type: string description: array of misspelled words tasks.result.pages.meta.spell.misspelled.word: type: string description: misspelled word tasks.result.pages.meta.resource_errors: type: object description: resource errors and warnings tasks.result.pages.meta.resource_errors.errors: type: array items: type: string description: resource errors tasks.result.pages.meta.resource_errors.errors.line: type: integer description: line where the error was found tasks.result.pages.meta.resource_errors.errors.message: type: string description: text message of the error the full list of possible HTML errors can be found here tasks.result.pages.meta.resource_errors.warnings: type: array items: type: string description: resource warnings tasks.result.pages.meta.resource_errors.warnings.line: type: integer description: 'line the warning relates to note that if "line": 0, the warning relates to the whole page' tasks.result.pages.meta.resource_errors.warnings.message: type: string description: 'text message of the warning possible messages: "Has node with more than 60 childs." – HTML page has at least 1 tag nesting over 60 tags of the same level "Has more that 1500 nodes." – DOM tree contains over 1,500 elements "HTML depth more than 32 tags." – DOM depth exceeds 32 nodes' tasks.result.pages.meta.social_media_tags: type: object description: object of social media tags found on the page contains social media tags and their content supported tags include but are not limited to Open Graph and Twitter card tasks.result.pages.page_timing: type: object description: array of page load metrics tasks.result.pages.page_timing.time_to_interactive: type: integer description: Time To Interactive (TTI) metric the time it takes until the user can interact with a page (in milliseconds) tasks.result.pages.page_timing.dom_complete: type: integer description: time to load resources the time it takes until the page and all of its subresources are downloaded (in milliseconds) tasks.result.pages.page_timing.largest_contentful_paint: type: number description: Core Web Vitals metric measuring how fast the largest above-the-fold content element is displayed The amount of time (in milliseconds) to render the largest content element visible in the viewport, from when the user requests the URL. Learn more. tasks.result.pages.page_timing.first_input_delay: type: number description: Core Web Vitals metric indicating the responsiveness of a page The time (in milliseconds) from when a user first interacts with your page to the time when the browser responds to that interaction. Learn more. tasks.result.pages.page_timing.connection_time: type: integer description: time to connect to a server the time it takes until the connection with a server is established (in milliseconds) tasks.result.pages.page_timing.time_to_secure_connection: type: integer description: time to establish a secure connection the time it takes until the secure connection with a server is established (in milliseconds) tasks.result.pages.page_timing.request_sent_time: type: integer description: time to send a request to a server the time it takes until the request to a server is sent (in milliseconds) tasks.result.pages.page_timing.waiting_time: type: integer description: time to first byte (TTFB) in milliseconds tasks.result.pages.page_timing.download_time: type: integer description: time it takes for a browser to receive a response (in milliseconds) tasks.result.pages.page_timing.duration_time: type: integer description: total time it takes until a browser receives a complete response from a server (in milliseconds) tasks.result.pages.page_timing.fetch_start: type: integer description: time to start downloading the HTML resource the amount of time the browser needs to start downloading a page tasks.result.pages.page_timing.fetch_end: type: integer description: time to complete downloading the HTML resource the amount of time the browser needs to complete downloading a page tasks.result.pages.onpage_score: type: number description: shows how page is optimized on a 100-point scale this field shows how page is optimized considering critical on-page issues and warnings detected; 100 is the highest possible score that means the page does not have any critical on-page issues and important warnings; learn more about how the metric is calculated in this help center article tasks.result.pages.total_dom_size: type: integer description: total DOM size of a page tasks.result.pages.custom_js_response: type: string description: the result of executing a specified JS script note that you should specify a custom_js field when setting a task to receive this data and the field type and its value will totally depend on the script you specified; tasks.result.pages.custom_js_client_exception: type: string description: error when executing a custom js if the error occurred when executing the script you specified in the custom_js field, the error message would be displayed here tasks.result.pages.broken_resources: type: boolean description: indicates whether a page contains broken resources tasks.result.pages.broken_links: type: boolean description: indicates whether a page contains broken links tasks.result.pages.duplicate_title: type: boolean description: indicates whether a page has duplicate title tags tasks.result.pages.duplicate_description: type: boolean description: indicates whether a page has a duplicate description tasks.result.pages.duplicate_content: type: boolean description: indicates whether a page has duplicate content tasks.result.pages.click_depth: type: integer description: number of clicks it takes to get to the page indicates the number of clicks from the homepage needed before landing at the target page tasks.result.pages.size: type: integer description: resource size indicates the size of a given page measured in bytes tasks.result.pages.encoded_size: type: integer description: page size after encoding indicates the size of the encoded page measured in bytes tasks.result.pages.total_transfer_size: type: integer description: compressed page size indicates the compressed size of a given page tasks.result.pages.fetch_time: type: string description: 'date and time when a resource was fetched in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' tasks.result.pages.cache_control: type: object description: instructions for caching tasks.result.pages.cache_control.cachable: type: boolean description: indicates whether the page is cacheable tasks.result.pages.cache_control.ttl: type: integer description: time to live the amount of time the browser caches a resource tasks.result.pages.checks: type: object description: website checks on-page check-ups related to the page tasks.result.pages.checks.no_content_encoding: type: boolean description: page with no content encoding indicates whether a page has no compression algorithm of the content tasks.result.pages.checks.high_loading_time: type: boolean description: page with high loading time indicates whether a page loading time exceeds 3 seconds tasks.result.pages.checks.is_redirect: type: boolean description: page with redirects indicates whether a page has 3XX redirects to other pages tasks.result.pages.checks.is_4xx_code: type: boolean description: page with 4xx status codes indicates whether a page has 4xx response code tasks.result.pages.checks.is_5xx_code: type: boolean description: page with 5xx status codes indicates whether a page has 5xx response code tasks.result.pages.checks.is_broken: type: boolean description: broken page indicates whether a page returns a response code less than 200 or greater than 400 tasks.result.pages.checks.is_www: type: boolean description: page with www indicates whether a page is on a www subdomain tasks.result.pages.checks.is_https: type: boolean description: page with the https protocol tasks.result.pages.checks.is_http: type: boolean description: page with the http protocol tasks.result.pages.checks.high_waiting_time: type: boolean description: page with high waiting time indicates whether a page waiting time (aka Time to First Byte) exceeds 1.5 seconds tasks.result.pages.checks.no_doctype: type: boolean description: page with no doctype indicates whether a page is without the declaration tasks.result.pages.checks.canonical: type: boolean description: page is canonical tasks.result.pages.checks.no_encoding_meta_tag: type: boolean description: 'page with no meta tag encoding indicates whether a page is without Content-Type informative only if the encoding is not explicit in the Content-Type header for example: Content-Type: "text/html; charset=utf8"; Note: available for pages with canonical check set to true' tasks.result.pages.checks.no_h1_tag: type: boolean description: 'page with empty or absent h1 tags Note: available for pages with canonical check set to true' tasks.result.pages.checks.https_to_http_links: type: boolean description: 'HTTPS page has links to HTTP pages if true, this HTTPS page has links to HTTP pages Note: available for pages with canonical check set to true' tasks.result.pages.checks.has_html_doctype: type: boolean description: page with HTML doctype declaration if true, the page has HTML DOCTYPE declaration tasks.result.pages.checks.size_greater_than_3mb: type: boolean description: 'page with size larger than 3 MB if true, the page size is exceeding 3 MB; Note: available for pages with canonical check set to true' tasks.result.pages.checks.meta_charset_consistency: type: boolean description: 'consistency between charset encoding and page charset if true, the page’s charset encoding doesn’t match the actual charset of the page; Note: available for pages with canonical check set to true' tasks.result.pages.checks.has_meta_refresh_redirect: type: boolean description: 'pages with meta refresh redirect if true, the page has tag that instructs a browser to load another page after a specified time span; Note: available for pages with canonical check set to true' tasks.result.pages.checks.has_render_blocking_resources: type: boolean description: 'page with render-blocking resources if true, the page has render-blocking scripts or stylesheets; Note: available for pages with canonical check set to true' tasks.result.pages.checks.redirect_chain: type: boolean description: page with multiple redirects if true, there were at least two redirects before our crawler reached this page tasks.result.pages.checks.low_content_rate: type: boolean description: 'page with low content rate indicates whether a page has the plaintext size to page size ratio of less than 0.1; Note: available for pages with canonical check set to true' tasks.result.pages.checks.high_content_rate: type: boolean description: 'page with high content rate indicates whether a page has the plaintext size to page size ratio of more than 0.9; Note: available for pages with canonical check set to true' tasks.result.pages.checks.low_character_count: type: boolean description: 'indicates whether the page has less than 1024 characters Note: available for pages with canonical check set to true' tasks.result.pages.checks.high_character_count: type: boolean description: 'indicates whether the page has more than 256,000 characters Note: available for pages with canonical check set to true' tasks.result.pages.checks.small_page_size: type: boolean description: 'indicates whether a page is too small the value will be true if a page size is smaller than 1024 bytes; Note: available for pages with canonical check set to true' tasks.result.pages.checks.large_page_size: type: boolean description: 'indicates whether a page is too heavy the value will be true if a page size exceeds 1 megabyte; Note: available for pages with canonical check set to true' tasks.result.pages.checks.low_readability_rate: type: boolean description: 'page with a low readability rate indicates whether a page is scored less than 15 points on the Flesch–Kincaid readability test; Note: available for pages with canonical check set to true' tasks.result.pages.checks.irrelevant_description: type: boolean description: 'page with irrelevant description indicates whether a page description tag is irrelevant to the content of a page; the relevance threshold is 0.2; Note: available for pages with canonical check set to true' tasks.result.pages.checks.irrelevant_title: type: boolean description: 'page with irrelevant title indicates whether a page title tag is irrelevant to the content of the page; the relevance threshold is 0.3; Note: available for pages with canonical check set to true' tasks.result.pages.checks.irrelevant_meta_keywords: type: boolean description: 'page with irrelevant meta keywords indicates whether a page keywords tags are irrelevant to the content of a page; the relevance threshold is 0.6; Note: available for pages with canonical check set to true' tasks.result.pages.checks.title_too_long: type: boolean description: 'page with a long title indicates whether the content of the title tag exceeds 65 characters; Note: available for pages with canonical check set to true' tasks.result.pages.checks.title_too_short: type: boolean description: 'page with short titles indicates whether the content of title tag is shorter than 30 characters; Note: available for pages with canonical check set to true' tasks.result.pages.checks.deprecated_html_tags: type: boolean description: 'page with deprecated tags indicates whether a page has deprecated HTML tags; Note: available for pages with canonical check set to true' tasks.result.pages.checks.duplicate_meta_tags: type: boolean description: 'page with duplicate meta tags indicates whether a page has more than one meta tag of the same type; Note: available for pages with canonical check set to true' tasks.result.pages.checks.duplicate_title_tag: type: boolean description: 'page with more than one title tag indicates whether a page has more than one title tag; Note: available for pages with canonical check set to true' tasks.result.pages.checks.no_image_alt: type: boolean description: 'images without alt tags Note: available for pages with canonical check set to true' tasks.result.pages.checks.no_image_title: type: boolean description: 'images without title tags Note: available for pages with canonical check set to true' tasks.result.pages.checks.no_description: type: boolean description: 'pages with no description indicates whether a page has an empty or absent description meta tag; Note: available for pages with canonical check set to true' tasks.result.pages.checks.no_title: type: boolean description: 'page with no title indicates whether a page has an empty or absent title tag; Note: available for pages with canonical check set to true' tasks.result.pages.checks.no_favicon: type: boolean description: 'page with no favicon Note: available for pages with canonical check set to true' tasks.result.pages.checks.seo_friendly_url: type: boolean description: 'page with seo-frienldy URL the ‘SEO-friendliness’ of a page URL is checked by four parameters: – the length of the relative path is less than 120 characters – no special characters – no dynamic parameters – relevance of the URL to the page if at least one of them is failed then such URL is considered as not ‘SEO-friendly’ Note: available for pages with canonical check set to true' tasks.result.pages.checks.flash: type: boolean description: page with flash indicates whether a page has flash elements tasks.result.pages.checks.frame: type: boolean description: page with frames indicates whether a page contains frame, iframe, frameset tags tasks.result.pages.checks.lorem_ipsum: type: boolean description: 'page with lorem ipsum indicates whether a page has lorem ipsum content; Note: available for pages with canonical check set to true' tasks.result.pages.checks.has_misspelling: type: boolean description: page with misspelled content tasks.result.pages.checks.seo_friendly_url_characters_check: type: boolean description: URL characters check-up indicates whether a page URL containing only uppercase and lowercase Latin characters, digits and dashes tasks.result.pages.checks.seo_friendly_url_dynamic_check: type: boolean description: URL dynamic check-up the value will be true if a page has no dynamic parameters in the url tasks.result.pages.checks.seo_friendly_url_keywords_check: type: boolean description: URL keyword check-up indicates whether a page URL is consistent with the title meta tag tasks.result.pages.checks.seo_friendly_url_relative_length_check: type: boolean description: URL length check-up the value will be true if a page URL no longer than 120 characters tasks.result.pages.checks.is_orphan_page: type: boolean description: page with no internal links pointing to it true if the page has no reference from other pages of the domain tasks.result.pages.checks.is_link_relation_conflict: type: boolean description: mix of both followed and nofollowed incoming internal links true if the page receives at least one link with the rel="nofollow" attribute and at least one dofollow link tasks.result.pages.checks.has_links_to_redirects: type: boolean description: page is pointing to a page that redirect elsewhere true if the page is pointing to a page that responds with a 3XX redirect tasks.result.pages.checks.recursive_canonical: type: boolean description: recursive canonical error true if the page contains rel="canonical" tag to another page, which in turn, refers back to the initial page tasks.result.pages.checks.canonical_chain: type: boolean description: pages with canonical pointing to a page that has a canonical pointing elsewhere true if the page has a canonical link element pointing to a page that has a canonical pointing to a different page e.g. page a is canonicalized to page b, which is canonicalized to page c tasks.result.pages.checks.canonical_to_redirect: type: boolean description: canonical page pointing to a page that redirect elsewhere true if the page has a canonical link element pointing to a page that responds with a 3XX redirect tasks.result.pages.checks.canonical_to_broken: type: boolean description: canonical link pointing to a broken page true if the page has a a canonical link pointing to a page that responds with a 4xx or 5xx response codes tasks.result.pages.content_encoding: type: string description: type of encoding tasks.result.pages.media_type: type: string description: types of media used to display a page tasks.result.pages.server: type: string description: server version tasks.result.pages.is_resource: type: boolean description: indicates whether a page is a single resource tasks.result.pages.last_modified: type: object description: contains data on changes related to the resource if there is no data, the value will be null tasks.result.pages.header: type: string description: 'date and time when the header was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' tasks.result.pages.sitemap: type: string description: 'date and time when the sitemap was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' tasks.result.pages.meta_tag: type: string description: 'date and time when the meta tag was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' type: type: string description: 'duplicate tags type required field indicates the type of duplicate elements found on the pages. The results will depend on the type you specify possible values: duplicate_title, duplicate_description' enum: - duplicate_title - duplicate_description accumulator: type: string description: tag value optional field specify a title or description here if you want to receive a list of duplicate pages that contains this tag limit: type: integer description: 'the maximum number of returned pages optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned pages optional field default value: 0 if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id - type tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/duplicate_tags source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/available_filters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Filters and customizable thresholds at DataForSEO OnPage API description: 'The filterable fields for each endpoint in this family, keyed by endpoint: `resources`, `pages`, `non_indexable`, `links`, `pages_by_resource`, `redirect_chains`, `keyword_density` and `uncrawlable_resources`. Fields are dotted paths such as `meta.title` and `meta.description`. Measured at 10.5 KB, the largest reference response here. Free: upstream cost is 0. Read it before building a `filters` argument - an unknown field is rejected, not ignored.' operationId: get_dataforseo_on_page_available_filters responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: array items: type: string description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results contains the full list of available parameters that can be used for data filtration the parameters are grouped by the endpoint they can be used with '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/available_filters source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/force_stop: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Force Stop description: 'Stops a running crawl by `id`. Returns no results of its own. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Use it when a crawl was submitted with too high a `max_crawl_pages` and is still consuming budget; what has already been crawled stays queryable through `get_dataforseo_on_page_summary` and the rest of this family.' operationId: post_dataforseo_on_page_force_stop responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04” note: you can set up to 1000 id values as separate objects in the POST array' required: - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/force_stop source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/keyword_density: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keyword Density description: 'Word and phrase frequency across a crawl, with `keyword_length` choosing n-gram size. Returns `total_items_count`, `items_count` and `items`. Measured at 611 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. This describes what a site says about itself; for what the web says about it use `post_dataforseo_backlinks_anchors_live`, and for what people search use `post_dataforseo_keywords_gads_search_volume_live`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_keyword_density responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.total_items_count: type: integer description: total number of relevant items total number of keywords on the specified website or web page matching the set keyword_length and filters tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.keyword: type: string description: returned keyword tasks.result.items.frequency: type: integer description: keyword frequency number of times the keyword appears on the website (or webpage if you specified a url) tasks.result.items.density: type: integer description: keyword density calculated as a ratio of frequency to the total count of keywords with the set keyword_length on the web page or website '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' keyword_length: type: integer description: 'number of words for a keyword required field possible values: 1, 2, 3, 4, 5' url: type: string description: page URL optional field if you do not specify a page here, the results will be provided for the whole website if you use this field, the API response will contain only keywords from the specified page a page should be specified with absolute URL (including http:// or https://) limit: type: integer description: 'the maximum number of returned keywords optional field default value: 100 maximum value: 1000' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["keyword","=","%seo%"] [["keyword","=","%seo%"], "and", ["frequency"," [["keyword","not_like","%seo%"], "and", [["frequency",">","6"],"or",["density",">","0.02"]]] The full list of possible filters is available by this link.' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["frequency,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword,asc","frequency,desc"]' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id - keyword_length tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/keyword_density source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/audits: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Audits in OnPage Lighthouse API description: 'The audit identifiers a Lighthouse run can be narrowed to, under an `audits` key. Measured at 5.3 KB. Free: upstream cost is 0. **Read this before running an audit, not after** - passing `audits` to `post_dataforseo_on_page_lighthouse_live_json` is the difference between a 245 KB report and a targeted one.' operationId: get_dataforseo_on_page_lighthouse_audits responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.audits: type: array items: type: string description: 'the list of available lighthouse audits an array containing the titles of available audits; Note: the titles can change depending on if the audit passed or failed and may contain markdown code; Note #2: if you’re using the audit that contains a slash (/) in its name, search by the last word after the slash' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/audits source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Languages for OnPage Lighthouse API description: 'The languages a Lighthouse report can be returned in, as `language_name` and `language_code`. Measured at 2.5 KB. Free: upstream cost is 0. Pass one as `language_name` or `language_code` on the audit endpoints - it changes the wording of the findings, not what is measured.' operationId: get_dataforseo_on_page_lighthouse_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/live/json: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.01 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live OnPage Lighthouse JSON description: 'Runs a Google Lighthouse audit on one `url` and returns the full report: `lighthouseVersion`, `requestedUrl`, `finalUrl`, `fetchTime`, `gatherMode`, `runWarnings` and every audit and category score. `for_mobile` switches the emulated device, `categories` and `audits` narrow the run. Measured at $0.005. 🔴 **Measured at 245 KB for a single audit of example.com, the largest response in this provider** - a full Lighthouse report is a JSON document, not a metric, and it will dominate an agent''s context. Pass `categories` or `audits` to cut it down, and prefer `post_dataforseo_on_page_waterfall` when the question is simply why a page is slow. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_on_page_lighthouse_live_json responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified when setting a task tasks.result: type: array items: type: string description: results of Lighthouse audit this array will include data according to the parameters you specified when setting a task; all fields and their descriptions are available in the official documentation by this link. '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: url: type: string description: 'target URL required field target page should be specified with its absolute URL (including http:// or https://) example: https://dataforseo.com/' for_mobile: type: boolean description: 'applies mobile emulation optional field if set to true, Lighthouse will use mobile device and screen emulation to test the page against mobile environment if set to false, the results will be provided for desktop default value: false' categories: type: array items: type: string description: 'categories of Lighthouse audits optional field each category is a collection of audits and audit groups that applies weighting and scoring to the section (see official definition) if you ignore this field, we will return data for all categories unless you specify audits use this field to get data for specific categories you indicate here possible values: seo, performance, best_practices, accessibility' audits: type: array items: type: string description: 'Lighthouse audits optional field audits are individual tests Lighthouse runs for each specific feature/optimization/metric to produce a numeric score (see official definition); if you ignore this field, we will return data for all audits; use this field to get data for specific audits you indicate here; Note: that some audits do not belong to a specific category and are stand-alone page quality measurements; in general, there can be several use cases: 1. if you ignore categories, you can use this field to get data for the specified audits only for example, if you ignore "categories" and specify "audits": ["metrics/cumulative-layout-shift","metrics/largest-contentful-paint","metrics/total-blocking-time"], you will get data only for these audits 2. if you specify a category, you can use this field to additionally receive audits that do not belong to the category(-ies) you specified for example, if you specify "categories": ["seo"] and "audits": ["metrics/cumulative-layout-shift","metrics/largest-contentful-paint","metrics/total-blocking-time"], you will get only these audits under “performance” and all audits under “seo” you can get the full list of possible audits here' version: type: string description: lighthouse version optional field you can obtain the results specific to a certain Lighthouse version by specifying its number the list of available versions is available through the Lighthouse Versions endpoint language_name: type: string description: 'lighthouse language name optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages default value: English' language_code: type: string description: 'lighthouse language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages default value: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - url example: - url: https://example.com categories: - seo tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/live/json source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/task_get/json/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Lighthouse Results by ID description: 'Retrieves a finished Lighthouse audit by the `id` from `post_dataforseo_on_page_lighthouse_submit`. Same report as the live endpoint, and the same 🔴 245 KB of it. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. If the audit is not finished this returns nothing useful; check `get_dataforseo_on_page_lighthouse_ready` first.' operationId: get_dataforseo_on_page_lighthouse_task_get_json responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: 'task identifier required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/task_get/json/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.01 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Lighthouse Tasks description: 'Queues a Lighthouse audit instead of waiting for one, returning a task `id`. Use it when the audit would outlast a tool call''s patience; retrieve with `get_dataforseo_on_page_lighthouse_task_get_json`, and see what is ready with `get_dataforseo_on_page_lighthouse_ready`. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Same 245 KB report at the end, so the context cost is deferred, not avoided - narrow it with `categories` or `audits` here, not later.' operationId: post_dataforseo_on_page_lighthouse_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: url: type: string description: 'target URL required field target page should be specified with its absolute URL (including http:// or https://) example: https://dataforseo.com/' for_mobile: type: boolean description: 'applies mobile emulation optional field if set to true, Lighthouse will use mobile device and screen emulation to test the page against mobile environment if set to false, the results will be provided for desktop default value: false' categories: type: array items: type: string description: 'categories of Lighthouse audits optional field each category is a collection of audits and audit groups that applies weighting and scoring to the section (see official definition)if you ignore this field, we will return data for all categories unless you specify audits use this field to get data for specific categories you indicate herepossible values: seo, performance, best_practices, accessibility' audits: type: array items: type: string description: 'Lighthouse audits optional field audits are individual tests Lighthouse runs for each specific feature/optimization/metric to produce a numeric score (see official definition)if you ignore this field, we will return data for all audits use this field to get data for specific audits you indicate herenote that some audits do not belong to a specific category and are stand-alone page quality measurementsin general, there can be several use cases:1. if you ignore categories, you can use this field to get data for the specified audits only for example, if you ignore "categories" and specify "audits": ["metrics/cumulative-layout-shift","metrics/largest-contentful-paint","metrics/total-blocking-time"], you will get data only for these audits2. if you specify a category, you can use this field to additionally receive audits that do not belong to the category(-ies) you specified for example, if you specify "categories": ["seo"] and "audits": ["metrics/cumulative-layout-shift","metrics/largest-contentful-paint","metrics/total-blocking-time"], you will get only these audits under "performance" and all audits under "seo"you can get the full list of possible audits here' version: type: string description: lighthouse version optional field you can obtain the results specific to a certain Lighthouse version by specifying its number the list of available versions is available through the Lighthouse Versions endpoint language_name: type: string description: 'lighthouse language name optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages default value: English' language_code: type: string description: 'lighthouse language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages default value: en' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center' required: - url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get OnPage Lighthouse Completed Tasks description: 'Lists the Lighthouse audits that have finished and are waiting to be collected. Returns `null` with `status_code` 20000 and `Ok.` when nothing is ready - an empty queue, not an error. Measured at 391 bytes. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve what it names with `get_dataforseo_on_page_lighthouse_task_get_json`.' operationId: get_dataforseo_on_page_lighthouse_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.tag: type: string description: user-defined task identifier tasks.result.endpoint_json: type: string description: URL for collecting the results of the OnPage Lighthouse JSON task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/lighthouse/versions: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Lighthouse versions supported in OnPage API description: 'The Lighthouse versions available, as `availible_versions` with `version` and `default` - note upstream''s spelling of that key. Measured at 1.4 KB. Free: upstream cost is 0. Pass one to `version` on the audit endpoints when a run has to be reproducible; otherwise the default moves as Lighthouse releases.' operationId: get_dataforseo_on_page_lighthouse_versions responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.available_versions: type: array items: type: string description: 'the list of supported lighthouse versions an array contains objects with the version number and a boolean indicating whether the version is used by default Note: you can specify the version in the POST request to the OnPage Lighthouse API' tasks.result.version: type: string description: lighthouse version tasks.result.default: type: boolean description: the version is used by default if false, the version is not used by default and should be specified in the corresponding field of the POST request if necessary '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/lighthouse/versions source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/links: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Links description: 'Every link found during a crawl, by `id`. Filter with `page_from` and `page_to` to get the links out of or into one page. Returns `total_items_count`, `items_count`, `items`, and a `search_after_token` for paging - use that rather than `offset` past the first pages. Measured at 1.0 KB for one link. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_links responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.total_items_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.type: type: string description: type of the link = ‘redirect’ HTTP redirect with 3xx status code tasks.result.items.domain_from: type: string description: referring domain the link was found on this domain tasks.result.items.domain_to: type: string description: referenced domain the link is pointing to this domain tasks.result.items.page_from: type: string description: referring page relative URL of the page on which the link was found tasks.result.items.page_to: type: string description: referenced page relative URL of the page to which the link is pointing tasks.result.items.link_from: type: string description: referring page absolute URL of the page on which the link was found tasks.result.items.link_to: type: string description: referenced page absolute URL of the page to which the link is pointing tasks.result.items.link_attribute: type: array items: type: string description: link attribute added to external link indicates link attributes added to the link_to on the page_from ["ugc","noopener"] tasks.result.items.dofollow: type: boolean description: indicates whether the link is dofollow if the value is true, the link doesn’t have a rel="nofollow" attribute tasks.result.items.page_from_scheme: type: string description: url scheme of the referring page tasks.result.items.page_to_scheme: type: string description: url scheme of the referenced page tasks.result.items.direction: type: string description: 'direction of the link possible values: internal, external' tasks.result.items.is_broken: type: boolean description: link is broken indicates whether a link is directing to a broken page or resource tasks.result.items.text: type: string description: image text tasks.result.items.is_link_relation_conflict: type: boolean description: indicates that the link may have a conflict with another link if true, at least one link pointing to link_to has a rel="nofollow" attribute and at least one is dofollow tasks.result.items.page_to_status_code: type: integer description: status code of the referenced page status code of the page to which the link is pointing tasks.result.items.image_alt: type: string description: alternative text for the image tasks.result.items.image_src: type: string description: url of the image tasks.result.items.is_valid_hreflang: type: boolean description: hreflang validity status indicates whether the hreflang attribute is correctly implemented tasks.result.items.hreflang: type: string description: 'hreflang attribute value language and optional country code specified in the hreflang attribute example: "en-US", "fr"' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' page_from: type: string description: relative page URL optional field if you use this field, the API response will contain only links from the specified page note that in this field you can specify relative URLs only page_to: type: string description: relative page URL optional field if you use this field, the API response will contain only internal links pointing to the specified page note that in this field you can specify relative URLs only limit: type: integer description: 'the maximum number of returned links optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned links optional field default value: 0 if you specify the 10 value, the first ten links in the results array will be omitted and the data will be provided for the successive links' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["direction","=","external"] [["domain_to","","example.com"], "and", ["link_from","not_like","%example.com/blog%"]] [["direction","=","external"], "and", [["link_from","like","%example.com/blog%"],"or",["link_from","like","%example.com/help%"]]] The full list of possible filters is available by this link.' search_after_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request; by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task ; Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/links source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/microdata: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Microdata description: 'Validates the structured data on one crawled `url`. Measured at 493 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. ⚠️ The page must have been part of the crawl: asking for a URL that was not returns `status_code` 40406, `Requested page was not submitted for crawling`, inside an HTTP 200. Widen `max_crawl_pages` or set `start_url` on the submit call if the page you want is missing. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_microdata responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.test_summary: type: object description: microdata validation test results tasks.result.test_summary.fatal: type: integer description: number of fatal microdata errors tasks.result.test_summary.error: type: integer description: number of serious microdata errors tasks.result.test_summary.warning: type: integer description: number of microdata warnings tasks.result.test_summary.info: type: integer description: number of microdata information flags tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.type: type: string description: type of the item = ‘json_ld’ tasks.result.inspection_info: type: object description: information related to microdata validation tasks.result.inspection_info.types: type: array items: type: string description: parent microdata types for a full list of available types, please visit schema.org tasks.result.inspection_info.fields: type: array items: type: string description: microdata fields an array of objects containing data fields related to the certain microdata type tasks.result.inspection_info.fields.name: type: string description: field name name of the data field tasks.result.inspection_info.fields.types: type: array items: type: string description: list of microdata sub-types tasks.result.inspection_info.fields.value: type: array items: type: string description: microdata value microdata value specified on a target web page tasks.result.inspection_info.fields.test_results: type: object description: microdata validation test results sub-type microdata test results that contain detected errors and related messages tasks.result.inspection_info.fields.test_results.level: type: string description: 'level of microdata error can take the following values: fatal, error, warning, info' tasks.result.inspection_info.fields.test_results.message: type: string description: message associated with an error message providing the details of the detected error tasks.result.inspection_info.fields.fields: type: array items: type: string description: microdata fields an array of objects containing data fields related to the certain microdata type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: "07131248-1535-0216-1000-17384017ad04"' url: type: string description: 'resource URL required field you can get this URL in the response of the Pages endpoint example: https://dataforseo.com/apis' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id - url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/microdata source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/non_indexable: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Non-indexable Pages description: 'The crawled pages search engines will not index, each with a `reason` and `url`. Measured at 588 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. The reason field is the whole value here - noindex, canonical elsewhere, robots-blocked are very different problems with the same symptom. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_non_indexable responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.total_items_count: type: integer description: total number of relevant items in the database tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.reason: type: string description: 'the reason why the page is non-indexable can take the following values: robots_txt, meta_tag, http_header, attribute, too_many_redirects' tasks.result.url: type: string description: url of the non-indexable page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' limit: type: integer description: 'the maximum number of returned pages optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned pages optional field default value: 0 if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["reason","=","robots_txt"][["reason","","robots_txt"], "and", ["url","not_like","%/wp-admin/%"]] [["url","not_like","%/wp-admin/%"], "and", [["reason","","meta_tag"],"or",["reason","","http_header"]]] The full list of possible filters is available by this link.' required: - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/non_indexable source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/page_screenshot: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0096 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Page Screenshot description: 'Renders any `url` and returns a screenshot, with `full_page_screenshot` for the whole scroll height and `browser_screen_width` and `browser_screen_height` setting the viewport. Standalone - no crawl needed. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ An image is a large tool result even before an agent can do anything with it; ask for a screenshot only when the visual is the point, and use `post_dataforseo_on_page_content_parsing_live` when the text is.' operationId: post_dataforseo_on_page_page_screenshot responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.error_message: type: string description: error message if the url you indicated returns a 404 status code or is not a valid URL, you will obtain "error_message":"Screenshot is empty" if no error is encountered, the value will be null tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.image: type: string description: screenshot of the requested page URL of the page screenshot on the DataForSEO storage '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: url: type: string description: 'page url required field absolute URL of the page to snap note: if the URL you indicate here returns a 404 status code or the indicated value is not a valid URL, you will obtain "error_message":"Screenshot is empty" in the response array' accept_language: type: string description: 'language header for accessing the website optional field all locale formats are supported (xx, xx-XX, xxx-XX, etc.) note: if you do not specify this parameter, some websites may deny access; in this case, you will obtain "error_message":"Screenshot is empty" in the response array' custom_user_agent: type: string description: 'custom user agent optional field custom user agent for crawling a website example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36 default value: Mozilla/5.0 (compatible; RSiteAuditor)' browser_preset: type: string description: 'preset for browser screen parameters optional field if you use this field, you don’t need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factor possible values: desktop, mobile, tablet desktop preset will apply the following values: browser_screen_width: 1920 browser_screen_height: 1080 browser_screen_scale_factor: 1 mobile preset will apply the following values: browser_screen_width: 390 browser_screen_height: 844 browser_screen_scale_factor: 3 tablet preset will apply the following values: browser_screen_width: 1024 browser_screen_height: 1366 browser_screen_scale_factor: 2 Note: in this endpoint, the enable_browser_rendering, enable_javascript, load_resources, and enable_xhr parameters are always enabled.' browser_screen_width: type: integer description: 'browser screen width optional field you can set a custom browser screen width to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; minimum value, in pixels: 240 maximum value, in pixels: 9999' browser_screen_height: type: integer description: 'browser screen height optional field you can set a custom browser screen height to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; minimum value, in pixels: 240 maximum value, in pixels: 9999' browser_screen_scale_factor: type: number description: 'browser screen scale factor optional field you can set a custom browser screen resolution ratio to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; minimum value: 0.5 maximum value: 3' full_page_screenshot: type: boolean description: 'take a screenshot of the full page optional field set to false if you want to capture only the part of the page displayed before scrolling default value: true' disable_cookie_popup: type: boolean description: 'disable the cookie popup optional field set to true if you want to disable the popup requesting cookie consent from the user; default value: false' switch_pool: type: boolean description: switch proxy pool optional field if true, additional proxy pools will be used to obtain the requested data; the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors ip_pool_for_scan: type: string description: 'proxy pool optional field you can choose a location of the proxy pool that will be used to obtain the requested data; the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errors possible values: us, de' required: - url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/page_screenshot source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/raw_html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Raw HTML description: 'The stored HTML of one crawled `url`. Measured at 578 bytes for a small page. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. ⚠️ Only available if the crawl was submitted with `store_raw_html` set - otherwise there is nothing to return, and the crawl cannot be amended after the fact. For parsed content rather than source use `post_dataforseo_on_page_content_parsing`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_raw_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: object description: items object tasks.result.items.html: type: string description: HTML page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' url: type: string description: 'page url required field the absolute URL of a page to request HTML Note: this field is optional if the task was set using the Instant Pages endpoint' required: - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/raw_html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/resources: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Resources description: 'The non-page assets a crawl found - images, scripts, stylesheets - with their status codes and sizes. Pages with `search_after_token`. Measured at 625 bytes for one resource. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. For the assets the crawler could not reach at all use `post_dataforseo_on_page_uncrawlable_resources`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_resources responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.total_items_count: type: integer description: total number of relevant items crawled tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.resource_type: type: string description: 'type of the returned resource possible types: script, image, stylesheet, broken' tasks.result.items.meta: type: object description: resource properties the value depends on the resource_type note that if you do not indicate a url when setting a task, resource’s meta is returned based on the data from the page where our crawler first saw the resource; to obtain resource’s meta from a particular url, specify that URL when setting a task tasks.result.items.meta.alternative_text: type: string description: content of the image alt attribute the value depends on the resource_type tasks.result.items.meta.title: type: string description: title tasks.result.items.meta.original_width: type: integer description: original image width in px tasks.result.items.meta.original_height: type: integer description: original image height in px tasks.result.items.meta.width: type: integer description: image width in px tasks.result.items.meta.height: type: integer description: image height in px tasks.result.items.status_code: type: integer description: status code of the page where a given resource is located tasks.result.items.location: type: string description: location header indicates the URL to redirect a page to tasks.result.items.url: type: string description: resource URL tasks.result.items.size: type: integer description: resource size indicates the size of a given resource measured in bytes tasks.result.items.encoded_size: type: integer description: resource size after encoding indicates the size of the encoded resource measured in bytes tasks.result.items.total_transfer_size: type: integer description: compressed resource size indicates the compressed size of a given resource in bytes tasks.result.items.fetch_time: type: string description: 'date and time when a resource was fetched in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2021-02-17 13:54:15 +00:00' tasks.result.items.fetch_timing: type: object description: resource fething time range tasks.result.items.fetch_timing.duration_time: type: integer description: indicates how many milliseconds it took to fetch a resource tasks.result.items.fetch_timing.fetch_start: type: integer description: time to start downloading the resource the amount of time a browser needs to start downloading a resource tasks.result.items.fetch_timing.fetch_end: type: integer description: time to complete downloading the resource the amount of time a browser needs to complete downloading a resource tasks.result.items.cache_control: type: object description: instructions for caching tasks.result.items.cache_control.cachable: type: boolean description: indicates whether the resource is cacheable tasks.result.items.cache_control.ttl: type: integer description: time to live the amount of time it takes for the browser to cache a resource; measured in milliseconds tasks.result.items.checks: type: object description: resource check-ups contents of the array depend on the resource_type tasks.result.items.checks.no_content_encoding: type: boolean description: 'resource with no content encoding indicates whether a page has no compression algorithm of the content; available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.high_loading_time: type: boolean description: 'resource with high loading time indicates whether a resource loading time exceeds 3 seconds; available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.is_redirect: type: boolean description: 'resource with redirects indicates whether a page with this resource has 3XX redirects to other pages; available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.is_4xx_code: type: boolean description: resource with with 4xx status code indicates whether a page with this resource has 4XX response code tasks.result.items.checks.is_5xx_code: type: boolean description: resource with 5xx status code indicates whethera page with this resource has 5XX response code tasks.result.items.checks.is_broken: type: boolean description: 'broken resource indicates whether a page with this resource returns 4xx, 5xx response codes or has broken elements inside the resource; available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.is_www: type: boolean description: 'page with www indicates whether a page with this resource is on a www subdomain; available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.is_https: type: boolean description: 'page with the https protocol available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.is_http: type: boolean description: 'page with the http protocol available for items with the following resource_type: script, image, stylesheet, broken' tasks.result.items.checks.original_size_displayed: type: boolean description: 'image desplayes in its original size indicates whether the image is displayed in its original size; available for items with the following resource_type: image' tasks.result.items.checks.is_minified: type: boolean description: 'resource is minified indicates whether the content of a stylesheet or script is minified; available for items with the following resource_type: stylesheet, script' tasks.result.items.checks.has_redirect: type: boolean description: 'resource has a redirect available for items with the following resource_type: script, image; if the resource_type is image, this field will indicate whether other pages and/or resources have redirects pointing at the image; if the resource_type is script, this field will indicate whether the script contains a redirect' tasks.result.items.checks.has_subrequests: type: boolean description: 'resource contains subrequests indicates whether the content of a stylesheet or script contain additional requests; available for items with the following resource_type: stylesheet, script' tasks.result.items.checks.from_sitemap: type: boolean description: resource was found on website’s sitemap if true, the resource was found on the sitemap of the website tasks.result.resource_errors: type: object description: resource errors and warnings tasks.result.resource_errors.errors: type: array items: type: string description: resource errors tasks.result.resource_errors.errors.line: type: integer description: line where the error was found tasks.result.resource_errors.errors.column: type: integer description: column where the error was found tasks.result.resource_errors.errors.message: type: string description: text message of the error the full list of possible HTML errors can be found here tasks.result.resource_errors.errors.status_code: type: integer description: 'status code of the error possible values: 0 — Unidentified Error; 501 — Html Parse Error; 1501 — JS Parse Error; 2501 — CSS Parse Error; 3501 — Image Parse Error; 3502 — Image Scale Is Zero; 3503 — Image Size Is Zero; 3504 — Image Format Invalid' tasks.result.resource_errors.warnings: type: array items: type: string description: resource warnings tasks.result.resource_errors.warnings.line: type: integer description: 'line the warning relates to note that if "line": 0, the warning relates to the whole page' tasks.result.resource_errors.warnings.column: type: integer description: 'column the warning relates to note that if "column": 0, the warning relates to the whole page' tasks.result.resource_errors.warnings.message: type: string description: 'text message of the warning possible messages: "Has node with more than 60 childs." – HTML page has at least 1 tag nesting over 60 tags of the same level "Has more that 1500 nodes." – DOM tree contains over 1,500 elements "HTML depth more than 32 tags." – DOM depth exceeds 32 nodes' tasks.result.resource_errors.warnings.status_code: type: integer description: 'status code of the warning possible values: 0 — Unidentified Warning; 1 — Has node with more than 60 childs; 2 — Has more that 1500 nodes; 3 — HTML depth more than 32 tags' tasks.result.resource_errors.content_encoding: type: string description: type of encoding tasks.result.resource_errors.media_type: type: string description: types of media used to display a resource tasks.result.resource_errors.accept_type: type: string description: 'indicates the expected type of resource for example, if "resource_type": "broken", accept_type will indicate the type of the broken resource possible values: any, none, image, sitemap, robots, script, stylesheet, redirect, html, text, other, font' tasks.result.resource_errors.server: type: string description: server version tasks.result.resource_errors.last_modified: type: object description: contains data on changes related to the resource if there is no data, the value will be null tasks.result.resource_errors.last_modified.header: type: string description: 'date and time when the header was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' tasks.result.resource_errors.last_modified.sitemap: type: string description: 'date and time when the sitemap was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' tasks.result.resource_errors.last_modified.meta_tag: type: string description: 'date and time when the meta tag was last modified in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 if there is no data, the value will be null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' url: type: string description: page URL optional field specify this field if you want to get the resources for a specific page note that to obtain resource’s meta from a particular URL, you should specify the URL in this field; if you do not indicate a url when setting a task, resource’s meta in the results will be returned based on the data from the page where our crawler first saw the resource limit: type: integer description: 'the maximum number of returned resources optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned resources optional field default value: 0 if you specify the 10 value, the first ten resources in the results array will be omitted and the data will be provided for the successive resources' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["resource_type","=","stylesheet"] [["resource_type","=","image"], "and",["checks.is_https","=",false]] [["fetch_timing.duration_time",">",1],"and",[["total_transfer_size",">",100],"or",["checks.high_loading_time","=",true]]] The full list of possible filters is available by this link.' relevant_pages_filters: type: array items: {} description: 'filter the resources by relevant pages optional field you can use this field to obtain resources from pages matching to the defined parameters you can apply the same filters here as available for the pages endpoint you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["checks.no_image_title","=",true]' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["size,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["size,desc","fetch_timing.fetch_end,desc"]' search_after_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request; by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task; search_after_token values are unique for each subsequent task ; Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/resources source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/summary/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Summary description: 'The state and headline metrics of one crawl, by `id`. Returns `crawl_progress`, `crawl_status`, `crawl_gateway_address`, `crawl_stop_reason`, `domain_info` and `page_metrics`. Measured at 3.1 KB. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. **This is also the way to know a crawl has finished** - poll it until `crawl_progress` is `finished` before reading any other endpoint here, or you will read partial results that look like real ones. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: get_dataforseo_on_page_summary responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: 'task identifier required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/summary/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0003 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting OnPage Tasks description: 'Starts a crawl of `target` and returns a task `id` in `tasks[0].id` - **that id is the handle every other tool in this family needs**, so keep it. `max_crawl_pages` caps the crawl, `start_url`, `max_crawl_depth`, `priority_urls` and `crawl_delay` shape it, and `store_raw_html` decides whether `post_dataforseo_on_page_raw_html` will have anything to serve later. Measured at $0.00015 to submit a one-page crawl. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ This is not the usual submit/fetch pair: the crawl is a session that a dozen other tools then query by id. Poll `get_dataforseo_on_page_summary` until `crawl_progress` reads `finished`; a one-page crawl of example.com took well under a minute.' operationId: post_dataforseo_on_page_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: target: type: string description: target domain required field domain name should be specified without https:// and www. if you specify the page URL, the results will be returned for the domain included in the URL max_crawl_pages: type: integer description: 'crawled pages limit required field the number of pages to crawl on the specified domain Note: if you set max_crawl_pages to 1 and do not specify start_url or set a homepage in it, the following sitewide checks will be disabled: test_canonicalization, enable_www_redirect_check, test_hidden_server_signature, test_page_not_found, test_directory_browsing, test_https_redirect to enable them anyway, set force_sitewide_checks to trueif you set max_crawl_pages to 1 and specify start_url other than a homepage, all sitewide checks will be disabled; to enable them anyway, set force_sitewide_checks to true' start_url: type: string description: 'the first url to crawl optional field Note: you should specify an absolute URL if you want to crawl a single page, specify its URL in this field and additionally set the max_crawl_pages parameter to 1 you can also use the live Instant Pages endpoint to get page-specific data' force_sitewide_checks: type: boolean description: 'enable sitewide checks when crawling a single page optional field set to true to get data on sitewide checks when crawling a single page; default value: false' priority_urls: type: array items: type: string description: 'urls to be crawled bypassing the queue optional field URLs specified in this array will be crawled in the first instance, bypassing the crawling queue; Note: you should specify the absolute URL; you can specify up to 20 URLs; all URLs in the array must belong to the target domain; subdomains will be ignored unless the allow_subdomains parameter is set to trueexample: "priority_urls": [ "https://dataforseo.com/apis/serp-api", "https://dataforseo.com/contact" ]' max_crawl_depth: type: integer description: crawl depth optional field the linking depth of the pages to crawl; for example, starting page of the crawl is level 0, pages that have links from that page are level 1, etc. crawl_delay: type: integer description: 'delay between hits, ms optional field the custom delay between crawler hits to the server default value: 2000' store_raw_html: type: boolean description: 'store HTML of crawled pages optional field set to true if you want to get the HTML of the page using the OnPage Raw HTML endpoint default value: false' enable_content_parsing: type: boolean description: 'parse content on crawled pages optional field set to true to use the OnPage Content Parsing endpoint default value: false' support_cookies: type: boolean description: 'support cookies on crawled pages optional field set to true to support cookies when crawling the pages default value: false' accept_language: type: string description: 'language header for accessing the website optional field all locale formats are supported (xx, xx-XX, xxx-XX, etc.) Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the "type":"broken in the response array' custom_robots_txt: type: string description: 'custom robots.txt settings optional field example: Disallow: /directory1/' robots_txt_merge_mode: type: string description: 'merge with or override robots.txt settings optional field possible values: merge, override; set to override if you want to ignore website crawling restrictions and other robots.txt settings default value: merge; Note: if set to override, specify the custom_robots_txt parameter' custom_user_agent: type: string description: 'custom user agent optional field custom user agent for crawling a website example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36 default value: Mozilla/5.0 (compatible; RSiteAuditor)' browser_preset: type: string description: 'preset for browser screen parameters optional field if you use this field, you don’t need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factorpossible values: desktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920 browser_screen_height: 1080 browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390 browser_screen_height: 844 browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024 browser_screen_height: 1366 browser_screen_scale_factor: 2 Note: to use this parameter, set enable_javascript or enable_browser_rendering to true' browser_screen_width: type: integer description: 'browser screen width optional field you can set a custom browser screen width to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240 maximum value, in pixels: 9999' browser_screen_height: type: integer description: 'browser screen height optional field you can set a custom browser screen height to perform an audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240 maximum value, in pixels: 9999' browser_screen_scale_factor: type: number description: 'browser screen scale factor optional field you can set a custom browser screen resolution ratio to perform audit for a particular device; if you use this field, you don’t need to indicate browser_preset as it will be ignored; Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value: 0.5 maximum value: 3' respect_sitemap: type: boolean description: 'respect sitemap when crawling optional field set to true if you want to follow the order of pages indicated in the primary sitemap when crawling; default value: false Note: if set to true, the click_depth value in the API response will equal 0; the max_crawl_depth field of the request will be ignored, you can specify the number of pages to crawl using the max_crawl_pages parameter' custom_sitemap: type: string description: 'custom sitemap url optional field the URL of the page where the alternative sitemap is located Note: if you want to use this parameter, respect_sitemap should be true' crawl_sitemap_only: type: boolean description: 'crawl only pages indicated in the sitemap optional field set to true if you want to crawl only the pages indicated in the sitemap if you set this parameter to true and do not specify custom_sitemap, we will crawl the default sitemap default value: false Note: if you want to use this parameter, respect_sitemap should be true' load_resources: type: boolean description: 'load resources optional field set to true if you want to load image, stylesheets, scripts, and broken resources default value: false Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page' enable_www_redirect_check: type: boolean description: 'check if the domain implemented the www redirection optional field set to true if you want to check if the requested domain implemented the www to non-www or non-www to www redirect; default value: false' enable_javascript: type: boolean description: 'load javascript on a page optional field set to true if you want to load the scripts available on a page default value: false Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page' enable_xhr: type: boolean description: 'enable XMLHttpRequest on a page optional field set to true if you want our crawler to request data from a web server using the XMLHttpRequest object default value: false;if you use this field, enable_javascript must be set to true;' enable_browser_rendering: type: boolean description: 'emulate browser rendering to measure Core Web Vitals optional field by using this parameter you will be able to emulate a browser when loading a web page; enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page; default value: false set to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response; if you use this field, enable_javascript, and load_resources parameters must be set to true Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page' disable_cookie_popup: type: boolean description: 'disable the cookie popup optional field set to true if you want to disable the popup requesting cookie consent from the user; default value: false' custom_js: type: string description: 'custom javascript optional field Note that the execution time for the script you enter here should be 700 ms maximum, for example, you can use the following JS snippet to check if the website contains Google Tag Manager as a scr attribute: let meta = { haveGoogleAnalytics: false, haveTagManager: false };\r\nfor (var i = 0; i = 0)\r\n meta.haveGoogleAnalytics = true;\r\n\tif (src.indexOf(\"gtm.js\") >= 0)\r\n meta.haveTagManager = true;\r\n }\r\n}\r\nmeta;the returned value depends on what you specified in this field. For instance, if you specify the following script: meta = {}; meta.url = document.URL; meta.test = ''test''; meta; as a response you will receive the following data: "custom_js_response": { "url": "https://dataforseo.com/", "test": "test" } Note: the length of the script you enter must be no more than 2000 characters Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page' validate_micromarkup: type: boolean description: 'enable microdata validation optional field set to true if you want to use the OnPage API Microdata endpoint default value: false' allow_subdomains: type: boolean description: 'include pages on subdomains optional field set to true if you want to crawl all subdomains of a target website default value: false' allowed_subdomains: type: array items: type: string description: 'subdomains to crawl optional field specify subdomains that you want to crawl example: ["blog.site.com", "my.site.com", "shop.site.com"] Note: to use this parameter, the allow_subdomains parameter should be set to false; otherwise, the content of allowed_subdomains field will be ignored and the results will be returned for all subdomains' disallowed_subdomains: type: array items: type: string description: 'subdomains not to crawl optional field specify subdomains that you don’t want to crawl example: ["status.site.com", "docs.site.com"] Note: to use this parameter, the allow_subdomains parameter should be set to true' check_spell: type: boolean description: 'check spelling optional field set to true to check spelling on a website using Hunspell library default value: false' check_spell_language: type: string description: 'language of the spell check optional field supported languages: ‘hy’, ‘eu’, ‘bg’, ‘ca’, ‘hr’, ‘cs’, ‘da’, ‘nl’, ‘en’, ‘eo’, ‘et’, ‘fo’, ‘fa’, ‘fr’, ‘fy’, ‘gl’, ‘ka’, ‘de’, ‘el’, ‘he’, ‘hu’, ‘is’, ‘ia’, ‘ga’, ‘it’, ‘rw’, ‘la’, ‘lv’, ‘lt’, ‘mk’, ‘mn’, ‘ne’, ‘nb’, ‘nn’, ‘pl’, ‘pt’, ‘ro’, ‘gd’, ‘sr’, ‘sk’, ‘sl’, ‘es’, ‘sv’, ‘tr’, ‘tk’, ‘uk’, ‘vi’ Note: if no language is specified, it will be set automatically based on page content' check_spell_exceptions: type: array items: type: string description: 'words excluded from spell check optional field specify the words that you want to exclude from spell check maximum word length: 100 characters maximum amount of words: 1000 example: "SERP", "minifiers", "JavaScript"' calculate_keyword_density: type: boolean description: 'calculate keyword density for the target domain optional field set to true if you want to calculate keyword density for website pages default value: false Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article once the crawl is completed, you can obtain keyword density values with the Keyword Density endpoint' checks_threshold: type: object description: 'custom threshold values for checks optional field you can specify custom threshold values for the parameters included in the checks object of OnPage API responses; Note: only integer threshold values can be modified; for example, the high_loading_time and large_page_size parameters are set to 3 seconds and 1 megabyte respectively by default; if you want to change these thresholds to 1 second and 1000 kbytes, use the following snippet: "checks_threshold": { "high_loading_time": 1, "large_page_size": 1000 }available customizable parameters with default values: "title_too_short", default value: 30, type: "int" "title_too_long", default value: 65, type: "int" "small_page_size", default value: 1024, type: "int" "large_page_size", default value: 1048576 (1024 * 1024), type: "int" "low_character_count", default value: 1024, type: "int" "high_character_count", default value: 256000 (250 * 1024), type: "int" "low_content_rate", default value: 0.1, type: "float" "high_content_rate", default value: 0.9, type: "float" "high_loading_time", default value: 3000, type: "int" "high_waiting_time", default value: 1500, type: "int" "low_readability_rate", default value: 15.0, type: "float" "irrelevant_description", default value: 0.2, type: "float" "irrelevant_title", default value: 0.3, type: "float" "irrelevant_meta_keywords", default value: 0.6, type: "float"' disable_sitewide_checks: type: array items: type: string description: 'prevent certain sitewide checks from running optional field specify the following checks to prevent them from running on the target website: "test_page_not_found" "test_canonicalization" "test_https_redirect" "test_directory_browsing"example: "disable_sitewide_checks": ["test_directory_browsing", "test_page_not_found"]learn more on our help center' disable_page_checks: type: array items: type: string description: 'prevent certain page checks from running optional field specify certain checks to prevent them from running and impacting the onpage_scoreexample: "disable_page_checks": ["is_5xx_code", "is_4xx_code"]' switch_pool: type: boolean description: switch proxy pool optional field if true, additional proxy pools will be used to obtain the requested data; the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors return_despite_timeout: type: boolean description: 'return data on pages despite the timeout error optional field if true, the data will be provided on pages that failed to load within 120 seconds and responded with a timeout error; default value: false' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - target - max_crawl_pages tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: On-Page Tasks Ready description: 'Lists the crawls that have finished. Returns `null` with `status_code` 20000 and `Ok.` when none are - an empty queue, not an error. Measured at 690 bytes. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely the tool you want: a caller holds the `id` its own `post_dataforseo_on_page_submit` returned, and `get_dataforseo_on_page_summary` answers whether that particular crawl is done.' operationId: get_dataforseo_on_page_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: array items: type: string description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.target: type: string description: target website specified when setting a task tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.tag: type: string description: user-defined task identifier '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/uncrawlable_resources: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Uncrawlable Resources description: 'The resources a crawl could not fetch, and why. Returns `total_items_count`, `items_count` and `items`. Measured at 621 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. These are the broken references a site owner would want first; the ones that did load are in `post_dataforseo_on_page_resources`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_uncrawlable_resources responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.total_items_count: type: integer description: total number of uncrawlable resources found total number of uncrawlable resources found during the crawl of the target domain tasks.result.items_count: type: integer description: number of uncrawlable resources in the items array tasks.result.items: type: array items: type: string description: array of uncrawlable resources tasks.result.items.url: type: string description: URL of the uncrawlable resource tasks.result.items.reason: type: string description: 'reason the resource is uncrawlable can take the following values: content_type_inconsistency' tasks.result.items.status_code: type: integer description: 'HTTP response code returned by the uncrawlable resource possible values: 200' tasks.result.items.fetch_time: type: string description: 'date and time when the resource was fetched in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2026-03-09 18:20:32 +00:00' tasks.result.items.meta: type: object description: metadata of the uncrawlable resource tasks.result.items.meta.content_type: type: string description: actual content type of the resource tasks.result.items.meta.expected_content_types: type: array items: type: string description: expected content types for the resource list of content types that were expected by the crawler based on how the resource is referenced on the page '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: "07131248-1535-0216-1000-17384017ad04"' limit: type: integer description: 'the maximum number of returned uncrawlable resources optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned uncrawlable resources optional field default value: 0 if you specify the 10 value, the first ten invalid resources in the results array will be omitted and the data will be provided for the successive invalid resources' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc - results will be sorted in the ascending order desc - results will be sorted in the descending order you should use a comma to set up a sorting type example: ["meta.content_type,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["meta.content_type,asc","fetch_time,desc"]' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: [["meta.content_type","=","image/jpeg"], "and", ["url","not_like","%/help-center/%"]]The full list of possible filters is available by this link.' required: - id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/uncrawlable_resources source: https://github.com/AIsa-team/aisa-proxy /dataforseo/on_page/waterfall: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: OnPage API Waterfall description: 'The load timeline of one crawled `url` - what was requested, in what order, and how long each took. Measured at 835 bytes. Reads a finished crawl, so it needs the `id` from `post_dataforseo_on_page_submit` and returns `crawl_progress` plus a `crawl_status` of `max_crawl_pages`, `pages_in_queue` and `pages_crawled` - check those before trusting a small result, because a crawl still running simply has less to report. Use it to explain a slow page; for a scored performance audit instead use `post_dataforseo_on_page_lighthouse_live_json`. 💰 Free upstream: querying a finished crawl costs nothing, only the crawl itself does. This family is the cheapest in the provider.' operationId: post_dataforseo_on_page_waterfall responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.crawl_progress: type: string description: 'status of the crawling session possible values: in_progress, finished' tasks.result.crawl_status: type: object description: details of the crawling session tasks.result.crawl_status.max_crawl_pages: type: integer description: maximum number of pages to crawl indicates the max_crawl_pages limit you specified when setting a task tasks.result.crawl_status.pages_in_queue: type: integer description: number of pages that are currently in the crawling queue tasks.result.crawl_status.pages_crawled: type: integer description: number of crawled pages tasks.result.items_count: type: integer description: number of items in the results array tasks.result.items: type: array items: type: string description: items array tasks.result.items.page_url: type: string description: URL of the page tasks.result.items.time_to_interactive: type: integer description: Time To Interactive (TTI) metric the time it takes until the user can interact with a page (in milliseconds) tasks.result.items.dom_complete: type: integer description: time to load resources the time it takes until the page and all of its subresources are downloaded (in milliseconds) tasks.result.items.connection_time: type: integer description: time to connect to a server the time it takes until the connection with a server is established (in milliseconds) tasks.result.items.time_to_secure_connection: type: integer description: time to establish a secure connection the time it takes until the secure connection with a server is established (in milliseconds) tasks.result.items.request_sent_time: type: integer description: time to send a request to a server the time it takes until the request to a server is sent (in milliseconds) tasks.result.items.waiting_time: type: integer description: time to first byte (TTFB) in milliseconds tasks.result.items.download_time: type: integer description: time it takes for a browser to receive a response (in milliseconds) tasks.result.items.duration_time: type: integer description: total time it takes until a browser receives a complete response from a server (in milliseconds) tasks.result.items.fetch_start: type: integer description: time to start downloading the HTML resource the amount of time the browser needs to start downloading a page tasks.result.items.fetch_end: type: integer description: time to complete downloading the HTML resource the amount of time the browser needs to complete downloading a page tasks.result.items.resources: type: array items: type: string description: resource-specific timing contains separate arrays with timing for each resource found on the page tasks.result.items.resources.resource_type: type: string description: type of the returned resource tasks.result.items.resources.url: type: string description: resource URL tasks.result.items.resources.initiator: type: string description: resource initiator tasks.result.items.resources.duration_time: type: integer description: total time it takes until a browser receives a complete response from a server (in milliseconds) tasks.result.items.resources.fetch_start: type: integer description: time to start downloading the resource the amount of time the browser needs to start downloading a resource tasks.result.items.resources.fetch_end: type: integer description: time to complete downloading the resource the amount of time the browser needs to complete downloading a resource tasks.result.items.resources.location: type: object description: location of the resource in the document parameters defining the location of the specific resource within the document’s HTML tasks.result.items.resources.location.line: type: integer description: line number the number of the line on which the resource is located tasks.result.items.resources.location.offset_left: type: integer description: 'position in line the number of line characters before the resource; sometimes referred to as column Note: counts from 1, i.e. if the resource doesn’t have any characters to the left, the value will be 1' tasks.result.items.resources.location.offset_top: type: integer description: position in the document the total number of characters between the resource and the top of HTML tasks.result.items.resources.is_render_blocking: type: boolean description: indicates whether the resource blocks rendering '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: id: type: string description: 'ID of the task required field you can get this ID in the response of the Task POST endpoint example: “07131248-1535-0216-1000-17384017ad04”' url: type: string description: page URL required field specify the pages you want to receive timing for tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - id - url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/on_page/waterfall source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/categories: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Categories for Content Analysis API description: 'The Google product and service category tree used by `post_dataforseo_content_category_trends_live`. Each row carries `category_code`, `category_name` and `category_code_parent`, which is what makes it a tree. 🔴 **Measured at 290 KB and 3,182 rows, and this endpoint takes no limit or filter parameter** - it is the largest response in the content family by two orders of magnitude and will consume a large part of an agent''s context. Fetch it once and keep the code you need rather than calling it per request. Free: upstream cost is 0.' operationId: get_dataforseo_content_categories responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.category_code: type: integer description: category code tasks.result.category_name: type: string description: full name of the category tasks.result.category_code_parent: type: integer description: 'the code of the superordinate category example: "category_code": 10178, "category_name": "Apparel Accessories", "category_code_parent": 10021 where category_code_parent corresponds to: "category_code": 10178, "category_name": "Apparel Accessories"' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/categories source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/category_trends/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048504 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Content Analysis – Category Trends API description: The same per-period metrics as `post_dataforseo_content_phrase_trends_live`, but for an entire product category instead of one keyword. Takes `category_code` from `get_dataforseo_content_categories`, with `date_from`, `date_to` and `date_group` setting range and granularity, and returns a `date` plus `total_count`, `rank`, `top_domains` (each `domain` and `count`), `sentiment_connotations` (anger, happiness, love, sadness, share, fun), `connotation_types` (positive, negative, neutral), `text_categories`, `page_categories`, `page_types`, `countries` and `languages` per period. Every response wraps its payload in DataForSEO's envelope - `tasks[0].result` holds the data and `tasks[0].cost` the upstream charge. Use it to see how a market moves rather than a single phrase; swap to the phrase endpoint when you already know the exact wording you care about. operationId: post_dataforseo_content_category_trends_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.type: type: string description: type of element = ‘content_analysis_trends’ tasks.result.date: type: string description: date for which the data is provided tasks.result.total_count: type: integer description: total number of results in our database relevant to your request tasks.result.rank: type: integer description: rank of all URLs citing the keyword normalized sum of ranks of all URLs citing the target keyword for the given date tasks.result.top_domains: type: array items: type: string description: top domains citing the target keyword contains objects with top domains citing the target category and citation count per each domain tasks.result.sentiment_connotations: type: object description: 'sentiment connotations contains sentiments (emotional reactions) related to the target category citation and the number of citations per each sentiment possible connotations: "anger", "fear", "happiness", "love", "sadness", "share", "neutral", "fun"' tasks.result.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the category citation and citation count per each sentiment type possible connotation types: "positive", "negative", "neutral"' tasks.result.text_categories: type: array items: type: string description: text categories contains objects with text categories and citation count in each text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.page_categories: type: array items: type: string description: page categories contains objects with page categories and citation count in each page category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.page_types: type: object description: page types contains page types and citation count per each page type tasks.result.countries: type: object description: countries contains countries and citation count in each country to obtain a full list of available countries, refer to the Locations endpoint tasks.result.languages: type: object description: languages contains languages and citation count in each language to obtain a full list of available languages, refer to the Languages endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: category_code: type: integer description: target category code required field to obtain a full list of available categories, refer to the Categories endpoint page_type: type: array items: type: string description: 'target page types optional field use this parameter to filter the dataset by page types possible values: "ecommerce", "news", "blogs", "message-boards", "organization"' search_mode: type: string description: 'results grouping type optional field possible grouping types: as_is – returns data on all citations for the target category_code one_per_domain – returns data on one citation of the category_code per domain default value: as_is' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: top_domains text_categories page_categories countries languages default value: 1 maximum value: 20' date_from: type: string description: 'starting date of the time range required field minimum value: 2022-10-31 date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' date_group: type: string description: 'time range which will be used to group the results optional field default value: month possible values: day, week, month' initial_dataset_filters: type: array items: {} description: 'initial dataset filtering parameters optional field initial filtering parameters that apply to fields in the Search endpoint; you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like,not_like, has, has_not, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["domain","", "logitech.com"] [["domain","","logitech.com"],"and",["content_info.connotation_types.negative",">",1000]] [["domain","","logitech.com"]], "and", [["content_info.connotation_types.negative",">",1000], "or", ["content_info.text_category","has",10994]]] for more information about filters, please refer to Content Analysis API – Filters learn more about the initial dataset filters in this help center article.' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - category_code - date_from tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/category_trends/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/available_filters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Filters for Content Analysis API description: 'The fields that `post_dataforseo_content_search_live` will accept in its `filters` argument: `url`, `domain`, `main_domain`, `url_rank`, `spam_score`, `domain_rank`, `fetch_time`, `country`, `language`, `score`, `page_category` and `page_types`. Measured at 1.8 KB. Free: upstream cost is 0. Read this before constructing a filter rather than guessing a field name - an unknown field is rejected, not ignored.' operationId: get_dataforseo_content_available_filters responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results contains the full list of available parameters that can be used for data filtration the parameters are grouped by the endpoint they can be used with '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/available_filters source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Languages for Content Analysis API description: 'The languages the content endpoints accept, as `language_name` and `language_code` - for example `Afrikaans` with `af`. 71 rows, and the code is the two-letter form, not a locale: `en`, not `en-US`. Measured at 3.9 KB. Free: upstream cost is 0. Reference data, so fetch once and reuse rather than calling it per request. The location equivalent is `get_dataforseo_content_locations`; the far larger category tree is `get_dataforseo_content_categories`.' operationId: get_dataforseo_content_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Locations for Content Analysis API description: 'The locations the content endpoints accept, as `location_name` and `country_iso_code` - for example `Afghanistan` with `AF`. The 235 rows are countries, not cities or regions, and the `country_iso_code` is returned for recognition only: the content endpoints match on the full `location_name` string. Measured at 13 KB. Free: upstream cost is 0. Reference data, so fetch once and reuse rather than calling it per request. The language equivalent is `get_dataforseo_content_languages`; the far larger category tree is `get_dataforseo_content_categories`.' operationId: get_dataforseo_content_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_name: type: string description: full name of the location tasks.result.country_iso_code: type: string description: ISO country code of the location '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/phrase_trends/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048504 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Content Analysis – Phrase Trends API description: The summary metrics for a keyword, repeated per time period. Each entry carries a `date` plus `total_count`, `rank`, `top_domains` (each `domain` and `count`), `sentiment_connotations` (anger, happiness, love, sadness, share, fun), `connotation_types` (positive, negative, neutral), `text_categories`, `page_categories`, `page_types`, `countries` and `languages`. `date_from`, `date_to` and `date_group` (day, week, month) set the range and granularity. Measured at 1.6 KB for two monthly points. Every response wraps its payload in DataForSEO's envelope - `tasks[0].result` holds the data and `tasks[0].cost` the upstream charge. Use this to see whether mentions of a phrase are rising or falling; for a single point in time use `post_dataforseo_content_summary_live`. To track a whole product category rather than one phrase, use `post_dataforseo_content_category_trends_live`. operationId: post_dataforseo_content_phrase_trends_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.type: type: string description: type of element = ‘content_analysis_trends’ tasks.result.date: type: string description: date for which the data is provided tasks.result.total_count: type: integer description: total number of results in our database relevant to your request tasks.result.rank: type: integer description: rank of all URLs citing the keyword normalized sum of ranks of all URLs citing the target keyword for the given date tasks.result.top_domains: type: array items: type: string description: top domains citing the target keyword contains objects with top domains citing the target keyword and citation count per each domain tasks.result.sentiment_connotations: type: object description: 'sentiment connotations contains sentiments (emotional reactions) related to the target keyword citation and the number of citations per each sentiment possible connotations: "anger", "happiness", "love", "sadness", "share", "fun"' tasks.result.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type possible connotation types: "positive", "negative", "neutral"' tasks.result.text_categories: type: array items: type: string description: text categories contains objects with text categories and citation count in each text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.page_categories: type: array items: type: string description: page categories contains objects with page categories and citation count in each page category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.page_types: type: object description: page types contains page types and citation count per each page type tasks.result.countries: type: object description: countries contains countries and citation count in each country to obtain a full list of available countries, refer to the Locations endpoint tasks.result.languages: type: object description: languages contains languages and citation count in each language to obtain a full list of available languages, refer to the Languages endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: 'target keyword required field UTF-8 encoding the keywords will be converted to a lowercase format; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword": "\"tesla palo alto\"" learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' keyword_fields: type: object description: 'target keyword fields and target keywords optional field use this parameter to filter the dataset by keywords that certain fields should contain; fields you can specify: title, main_title, previous_title, snippet you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword_fields": { "snippet": "\"logitech mouse\"", "main_title": "sale" }' properties: title: type: string main_title: type: string previous_title: type: string snippet: type: string page_type: type: array items: type: string description: 'target page types optional field use this parameter to filter the dataset by page types possible values: "ecommerce", "news", "blogs", "message-boards", "organization"' search_mode: type: string description: 'results grouping type optional field possible grouping types: as_is – returns data on all citations for the target keyword one_per_domain – returns data on one citation of the keyword per domain default value: as_is' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: top_domains text_categories page_categories countries languages default value: 1 maximum value: 20' date_from: type: string description: 'starting date of the time range required field date format: "yyyy-mm-dd" example: "2019-01-15"' date_to: type: string description: 'ending date of the time range optional field if you don’t specify this field, today’s date will be used by default date format: "yyyy-mm-dd" example: "2019-01-15"' date_group: type: string description: 'time range which will be used to group the results optional field default value: month possible values: day, week, month' initial_dataset_filters: type: array items: {} description: 'initial dataset filtering parameters optional field initial filtering parameters that apply to fields in the Search endpoint; you can add several filters at once (8 filters maximum); you should set a logical operator and, or between the conditions; the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like,not_like, has, has_not, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters; example: ["domain","", "logitech.com"] [["domain","","logitech.com"],"and",["content_info.connotation_types.negative",">",1000]] [["domain","","logitech.com"]], "and", [["content_info.connotation_types.negative",">",1000], "or", ["content_info.text_category","has",10994]]] for more information about filters, please refer to Content Analysis API – Filters learn more about the initial dataset filters in this help center article.' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword - date_from tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/phrase_trends/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/rating_distribution/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Content Analysis – Rating Distribution API description: Splits a keyword's citations into rating buckets and reports the full metric set for each. Returns one entry per bucket with `min`, `max` and a `metrics` object holding `total_count`, `rank`, `top_domains` (each `domain` and `count`), `sentiment_connotations` (anger, happiness, love, sadness, share, fun), `connotation_types` (positive, negative, neutral), `text_categories`, `page_categories`, `page_types`, `countries` and `languages`. Measured at 6.1 KB across 10 buckets - the largest response in this family, since every bucket repeats the whole metric set. Every response wraps its payload in DataForSEO's envelope - `tasks[0].result` holds the data and `tasks[0].cost` the upstream charge. `rank_scale` chooses the bucketing. For the same metrics un-bucketed use `post_dataforseo_content_summary_live`; for sentiment alone, `post_dataforseo_content_sentiment_analysis_live`. operationId: post_dataforseo_content_rating_distribution_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.type: type: string description: type of element = ‘content_analysis_rating_distribution’ tasks.result.min: type: number description: min rating on a distribution scale tasks.result.max: type: number description: max rating on a distribution scale tasks.result.metrics: type: object description: contains rating distribution metrics tasks.result.metrics.type: type: string description: type of element = ‘content_analysis_summary’ tasks.result.metrics.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.metrics.rank: type: integer description: rank of all URLs citing the keyword normalized sum of ranks of all URLs citing the target keyword tasks.result.metrics.top_domains: type: array items: type: string description: top domains citing the target keyword contains objects with top domains citing the target keyword and citation count per each domain tasks.result.metrics.sentiment_connotations: type: object description: 'sentiment connotations contains sentiments (emotional reactions) related to the target keyword citation and the number of citations per each sentiment; possible connotations: "anger", "happiness", "love", "sadness", "share", "fun"' tasks.result.metrics.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type; possible connotation types: "positive", "negative", "neutral"' tasks.result.metrics.text_categories: type: array items: type: string description: text categories contains objects with text categories and citation count in each text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.metrics.page_categories: type: array items: type: string description: page categories contains objects with page categories and citation count in each page category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.metrics.page_types: type: object description: page types contains page types and citation count per each page type tasks.result.metrics.countries: type: object description: countries contains countries and citation count in each country to obtain a full list of available countries, refer to the Locations endpoint tasks.result.metrics.languages: type: object description: languages contains languages and citation count in each language to obtain a full list of available languages, refer to the Languages endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: 'target keyword required field UTF-8 encoding the keywords will be converted to a lowercase format; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword": "\"tesla palo alto\"" learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' keyword_fields: type: object description: 'target keyword fields and target keywords optional field use this parameter to filter the dataset by keywords that certain fields should contain; fields you can specify: title, main_title, previous_title, snippet you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword_fields": { "snippet": "\"logitech mouse\"", "main_title": "sale" }' properties: title: type: string main_title: type: string previous_title: type: string snippet: type: string page_type: type: array items: type: string description: 'target page types optional field use this parameter to filter the dataset by page types possible values: "ecommerce", "news", "blogs", "message-boards", "organization"' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: top_domains text_categories page_categories countries languages default value: 1 maximum value: 20' search_mode: type: string description: 'results grouping type optional field possible grouping types: as_is – returns all citations for the target keyword one_per_domain – returns one citation of the keyword per domain default value: as_is' positive_connotation_threshold: type: number description: 'positive connotation threshold optional field specified as the probability index threshold for positive sentiment related to the citation content if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value possible values: from 0 to 1 default value: 0.4' sentiments_connotation_threshold: type: number description: 'sentiment connotation threshold optional field specified as the probability index threshold for sentiment connotations related to the citation content if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value possible values: from 0 to 1 default value: 0.4' initial_dataset_filters: type: array items: {} description: 'initial dataset filtering parameters optional field initial filtering parameters that apply to fields in the Search endpoint you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like,not_like, has, has_not, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["domain","", "logitech.com"] [["domain","","logitech.com"],"and",["content_info.connotation_types.negative",">",1000]] [["domain","","logitech.com"]], "and", [["content_info.connotation_types.negative",">",1000], "or", ["content_info.text_category","has",10994]]] for more information about filters, please refer to Content Analysis API – Filters learn more about the initial dataset filters in this help center article.' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/rating_distribution/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/search/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.0552 max: 0.0552 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Content Analysis – Search API description: Lists the individual pages citing a keyword, rather than the totals. Each item carries `url`, `domain`, `main_domain`, `url_rank`, `domain_rank`, `spam_score`, `fetch_time`, `country`, `language`, `score` and `page_category`, alongside `total_count` and `items_count`. Page with `offset_token` from the previous response, and cap the payload with `limit` - measured at 2.2 KB for a single item. Every response wraps its payload in DataForSEO's envelope - `tasks[0].result` holds the data and `tasks[0].cost` the upstream charge. `filters` accepts the fields listed by `get_dataforseo_content_available_filters`. For counts and distributions instead of pages, use `post_dataforseo_content_summary_live`. operationId: post_dataforseo_content_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.offset_token: type: string description: 'offset token for subsequent requests you can use the string provided in this field to get the subsequent results of the initial task; note: offset_token values are unique for each subsequent task' tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.items_count: type: integer description: the number of results returned in the items array tasks.result.items: type: array items: type: string description: contains citations and related data tasks.result.items.type: type: string description: type of element = ‘content_analysis_search’ tasks.result.items.url: type: string description: URL where the citation was found tasks.result.items.domain: type: string description: domain name tasks.result.items.main_domain: type: string description: main domain tasks.result.items.url_rank: type: integer description: rank of the url this value is based on backlink data for the given URL from DataForSEO Backlink Index; url_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.spam_score: type: string description: backlink spam score of the url this value is based on backlink data for the given URL from DataForSEO Backlink Index; learn more about how the metric is calculated on this help center page tasks.result.items.domain_rank: type: string description: rank of the domain this value is based on backlink data for the given domain from DataForSEO Backlink Index; domain_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm learn more about the metric and how it is calculated in this help center article tasks.result.items.fetch_time: type: string description: 'date and time when our crawler visited the page in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.country: type: string description: country code of the domain registration to obtain a full list of available countries, refer to the Locations endpoint tasks.result.items.language: type: string description: main language of the domain to obtain a full list of available languages, refer to the Languages endpoint tasks.result.items.score: type: string description: citation prominence score this value is based on url_rank, domain_rank, keyword presence in title, main_title, url, snippet the higher the score, the more value the related citation has tasks.result.items.page_category: type: array items: type: string description: contains all relevant page categories product and service categories relevant for the page to obtain a full list of available categories, refer to the Categories endpoint tasks.result.items.page_types: type: array items: type: string description: page types tasks.result.items.ratings: type: array items: type: string description: ratings found on the page all ratings found on the page based on microdata tasks.result.items.social_metrics: type: array items: type: string description: social media engagement metrics data on social media interactions associated with the content based on website embeds developed and supported by social media platforms tasks.result.items.content_info: type: object description: contains data on citations from the given url tasks.result.items.content_info.content_type: type: string description: 'type of content example: page_content, comment' tasks.result.items.content_info.title: type: string description: title of the result tasks.result.items.content_info.main_title: type: string description: page title tasks.result.items.content_info.previous_title: type: string description: title of the previous content block tasks.result.items.content_info.level: type: integer description: title heading level indicates h-tag level from 1 (top) to 6 (bottom) tasks.result.items.content_info.author: type: string description: author of the content tasks.result.items.content_info.snippet: type: string description: content snippet tasks.result.items.content_info.snippet_length: type: integer description: character length of the snippet tasks.result.items.content_info.social_metrics: type: array items: type: string description: social media engagement metrics data on social media interactions associated with the content based on website embeds developed and supported by social media platforms tasks.result.items.content_info.highlighted_text: type: string description: highlighted text from the snippet tasks.result.items.content_info.language: type: string description: content language to obtain a full list of available languages, refer to the Languages endpoint tasks.result.items.content_info.sentiment_connotations: type: object description: 'sentiment connotations contains sentiments (emotional reactions) related to the given citation and probability index per each sentiment possible sentiment connotations: anger, happiness, love, sadness, share, fun' tasks.result.items.content_info.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the given citation and probability index per each sentiment type possible sentiment connotation types: positive, negative, neutral' tasks.result.items.content_info.text_category: type: array items: type: string description: text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.items.content_info.date_published: type: string description: 'date and time when the content was published in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' tasks.result.items.content_info.content_quality_score: type: integer description: content quality score this value is calculated based on the number of words, sentences and characters the content contains tasks.result.items.content_info.semantic_location: type: string description: 'semantic location indicates semantic element in HTML where the target keyword citation is located example: article, header' tasks.result.items.content_info.rating: type: object description: content rating rating related to content_info tasks.result.items.content_info.rating.name: type: string description: 'rating name here you can find the following elements: Max5, Percents, CustomMax' tasks.result.items.content_info.rating.rating_value: type: integer description: the value of the rating tasks.result.items.content_info.rating.max_rating_value: type: integer description: maximum value for the rating name tasks.result.items.content_info.rating.rating_count: type: integer description: number of votes tasks.result.items.content_info.rating.relative_rating: type: number description: relative rating tasks.result.items.content_info.group_date: type: string description: 'citation group date and time indicates content publication date or date and time when our crawler visited the page for the first time; this field can be used to group citations by date and display citation trends; date and time are provided in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2017-01-24 13:20:59 +00:00' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: 'target keyword required field UTF-8 encoding the keywords will be converted to a lowercase format; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword": "\"tesla palo alto\"" learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' keyword_fields: type: object description: 'target keyword fields and target keywords optional field use this parameter to filter the dataset by keywords that certain fields should contain; fields you can specify: title, main_title, previous_title, snippet you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword_fields": { "snippet": "\"logitech mouse\"", "main_title": "sale" }' properties: title: type: string main_title: type: string previous_title: type: string snippet: type: string page_type: type: array items: type: string description: 'target page types optional field use this parameter to filter the dataset by page types possible values: "ecommerce", "news", "blogs", "message-boards", "organization"' search_mode: type: string description: 'results grouping type optional field possible grouping types: as_is – returns all citations for the target keyword one_per_domain – returns one citation of the keyword per domain default value: as_is' limit: type: integer description: 'the maximum number of returned citations optional field default value: 100 maximum value: 1000' filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like,not_like, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["country","=", "US"] [["domain_rank",">",800],"and",["content_info.connotation_types.negative",">",0.9]] [["domain_rank",">",800], "and", [["page_types","has","ecommerce"], "or", ["content_info.text_category","has",10994]]] for more information about filters, please refer to Content Analysis API – Filters' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["content_info.sentiment_connotations.anger,desc"] default rule: ["content_info.sentiment_connotations.anger,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["content_info.sentiment_connotations.anger,desc","keyword_data.keyword_info.cpc,desc"]' offset: type: integer description: 'offset in the results array of returned citations optional field default value: 0 if you specify the 10 value, the first ten citations in the results array will be omitted and the data will be provided for the successive citations Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'offset token for subsequent requests optional field provided in the identical field of the response to each request; use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task learn more about this parameter on our Help Center' rank_scale: type: string description: 'defines the scale used for calculating and displaying the domain_rank, and url_rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response anyOf: - required: - keyword - required: - offset_token tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/search/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/sentiment_analysis/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048072 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Content Analysis – Sentiment Analysis API description: 'Sentiment distributions for the citations of a keyword: `positive_connotation_distribution` (positive, negative, neutral) and `sentiment_connotation_distribution` (anger, happiness, love, sadness, share, fun). `positive_connotation_threshold` and `sentiments_connotation_threshold` set how confident a classification must be to count. Measured at 5.7 KB. Every response wraps its payload in DataForSEO''s envelope - `tasks[0].result` holds the data and `tasks[0].cost` the upstream charge. ⚠️ Both blocks are already inside `post_dataforseo_content_summary_live`, which costs the same and adds domains, categories, countries and languages - prefer it unless the smaller response matters. To see the sentiment split by star rating use `post_dataforseo_content_rating_distribution_live`.' operationId: post_dataforseo_content_sentiment_analysis_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.type: type: string description: type of element = ‘content_analysis_sentiment_analysis’ tasks.result.positive_connotation_distribution: type: object description: 'citation distribution by sentiment connotation types contains objects with citation counts and relevant data distributed by types of sentiments (sentiment polarity); possible sentiment connotation types: positive, negative, neutral' tasks.result.positive_connotation_distribution.$positive: type: object description: 'positive, negative, or neutral connotations variable can take the following values: positive, negative, neutral' tasks.result.positive_connotation_distribution.$positive.type: type: string description: type of element = ‘content_analysis_summary’ tasks.result.positive_connotation_distribution.$positive.total_count: type: integer description: total number of relevant results tasks.result.positive_connotation_distribution.$positive.rank: type: integer description: rank of all relevant URLs tasks.result.positive_connotation_distribution.$positive.top_domains: type: array items: type: string description: top relevant domains contains objects with top relevant domains and the number of citations per each domain tasks.result.positive_connotation_distribution.$positive.sentiment_connotations: type: object description: 'sentiment connotations contains relevant sentiments (emotional reactions) and the number of citations per each sentiment; possible connotations: "anger", "happiness", "love", "sadness", "share", "fun"' tasks.result.positive_connotation_distribution.$positive.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type; possible connotation types: "positive", "negative", "neutral"' tasks.result.positive_connotation_distribution.$positive.text_categories: type: array items: type: string description: text categories contains text categories and citation count in each text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.positive_connotation_distribution.$positive.page_categories: type: array items: type: string description: page categories contains objects with page categories and citation count in each page category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.positive_connotation_distribution.$positive.page_types: type: object description: page types contains page types and citation count per each page type tasks.result.positive_connotation_distribution.$positive.countries: type: object description: countries contains countries and citation count in each country to obtain a full list of available countries, refer to the Locations endpoint tasks.result.positive_connotation_distribution.$positive.languages: type: object description: languages to obtain a full list of available languages, refer to the Languages endpoint tasks.result.sentiment_connotation_distribution: type: object description: 'citation distribution by sentiment connotations contains objects with citation counts and relevant data distributed by sentiments (emotional reactions); possible sentiment connotation types: anger, happiness, love, sadness, share, fun' tasks.result.sentiment_connotation_distribution.$anger: type: object description: 'sentiment name variable can take the following values: anger, happiness, love, sadness, share, fun' tasks.result.sentiment_connotation_distribution.$anger.type: type: string description: type of element = ‘content_analysis_summary’ tasks.result.sentiment_connotation_distribution.$anger.total_count: type: integer description: total number of relevant results tasks.result.sentiment_connotation_distribution.$anger.rank: type: integer description: rank of all relevant URLs tasks.result.sentiment_connotation_distribution.$anger.top_domains: type: array items: type: string description: top relevant domains contains objects with top relevant domains and the number of citations per each domain tasks.result.sentiment_connotation_distribution.$anger.sentiment_connotations: type: object description: 'sentiment connotations contains relevant sentiments (emotional reactions) and the number of citations per each sentiment; possible connotations: "anger", "happiness", "love", "sadness", "share", "fun"' tasks.result.sentiment_connotation_distribution.$anger.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type; possible connotation types: "positive", "negative", "neutral"' tasks.result.sentiment_connotation_distribution.$anger.text_categories: type: array items: type: string description: text categories contains text categories and citation count in each text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.sentiment_connotation_distribution.$anger.page_categories: type: array items: type: string description: page categories contains objects with page categories and citation count in each page category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.sentiment_connotation_distribution.$anger.page_types: type: object description: page types contains page types and citation count per each page type tasks.result.sentiment_connotation_distribution.$anger.countries: type: object description: countries contains countries and citation count in each country to obtain a full list of available countries, refer to the Locations endpoint tasks.result.sentiment_connotation_distribution.$anger.languages: type: object description: languages to obtain a full list of available countries, refer to the Languages endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: 'target keyword required field UTF-8 encoding the keywords will be converted to a lowercase format; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword": "\"tesla palo alto\"" learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' keyword_fields: type: object description: 'target keyword fields and target keywords optional field use this parameter to filter the dataset by keywords that certain fields should contain; fields you can specify: title, main_title, previous_title, snippet you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword_fields": { "snippet": "\"logitech mouse\"", "main_title": "sale" }' properties: title: type: string main_title: type: string previous_title: type: string snippet: type: string page_type: type: array items: type: string description: 'target page types optional field use this parameter to filter the dataset by page types possible values: "ecommerce", "news", "blogs", "message-boards", "organization"' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: top_domains text_categories page_categories countries languages default value: 1 maximum value: 20' positive_connotation_threshold: type: number description: 'positive connotation threshold optional field specified as the probability index threshold for positive sentiment related to the citation content if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value possible values: from 0 to 1 default value: 0.4' sentiments_connotation_threshold: type: number description: 'sentiment connotation threshold optional field specified as the probability index threshold for sentiment connotations related to the citation content if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value possible values: from 0 to 1 default value: 0.4' initial_dataset_filters: type: array items: {} description: 'initial dataset filtering parameters optional field initial filtering parameters that apply to fields in the Search endpoint you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like,not_like, has, has_not, match, not_match you can use the % operator with like and not_like to match any string of zero or more characters example: ["domain","", "logitech.com"] [["domain","","logitech.com"],"and",["content_info.connotation_types.negative",">",1000]] [["domain","","logitech.com"]], "and", [["content_info.connotation_types.negative",">",1000], "or", ["content_info.text_category","has",10994]]] for more information about filters, please refer to Content Analysis API – Filters learn more about the initial dataset filters in this help center article.' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/sentiment_analysis/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/content_analysis/summary/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.048072 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Content Analysis – Summary API description: 'Aggregate view of every citation of a keyword across the web index. Returns `total_count`, `rank`, `top_domains` (each `domain` and `count`), `sentiment_connotations` (anger, happiness, love, sadness, share, fun), `connotation_types` (positive, negative, neutral), `text_categories`, `page_categories`, `page_types`, `countries` and `languages`. Measured at 1.1 KB for one keyword. Every response wraps its payload in DataForSEO''s envelope - `tasks[0].result` holds the data and `tasks[0].cost` the upstream charge. This is the hub of the content family: `post_dataforseo_content_sentiment_analysis_live` returns only the two connotation blocks already included here, so call this one instead unless you specifically want the smaller payload. For the individual citing pages rather than the totals use `post_dataforseo_content_search_live`; for the same aggregate over time, `post_dataforseo_content_phrase_trends_live`.' operationId: post_dataforseo_content_summary_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.type: type: string description: type of element = ‘content_analysis_summary’ tasks.result.total_count: type: integer description: total amount of results in our database relevant to your request tasks.result.rank: type: integer description: rank of all URLs citing the keyword normalized sum of ranks of all URLs citing the target keyword tasks.result.top_domains: type: array items: type: string description: top domains citing the target keyword contains objects with top domains citing the target keword and citation count per each domain tasks.result.sentiment_connotations: type: object description: 'sentiment connotations contains sentiments (emotional reactions) related to the target keyword citation and the number of citations per each sentiment possible sentiment connotations: anger, happiness, love, sadness, share, fun' tasks.result.connotation_types: type: object description: 'connotation types contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type possible sentiment connotation types: positive, negative, neutral' tasks.result.text_categories: type: array items: type: string description: text categories contains objects with text categories and citation count in each text category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.page_categories: type: array items: type: string description: page categories contains objects with page categories and citation count in each page category to obtain a full list of available categories, refer to the Categories endpoint tasks.result.page_types: type: object description: page types contains page types and citation count per each page type tasks.result.countries: type: object description: countries contains countries and citation count in each country to obtain a full list of available countries, refer to the Locations endpoint tasks.result.languages: type: object description: languages contains languages and citation count in each language to obtain a full list of available languages, refer to the Languages endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: 'target keyword required field UTF-8 encoding the keywords will be converted to a lowercase format; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword": "\"tesla palo alto\"" learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article' keyword_fields: type: object description: 'target keyword fields and target keywords optional field use this parameter to filter the dataset by keywords that certain fields should contain; fields you can specify: title, main_title, previous_title, snippet you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: "keyword_fields": { "snippet": "\"logitech mouse\"", "main_title": "sale" }' properties: title: type: string main_title: type: string previous_title: type: string snippet: type: string page_type: type: array items: type: string description: 'target page types optional field use this parameter to filter the dataset by page types possible values: "ecommerce", "news", "blogs", "message-boards", "organization"' internal_list_limit: type: integer description: 'maximum number of elements within internal arrays optional field you can use this field to limit the number of elements within the following arrays: top_domains text_categories page_categories countries languages default value: 1 maximum value: 20' positive_connotation_threshold: type: number description: 'positive connotation threshold optional field specified as the probability index threshold for positive sentiment related to the citation content if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value possible values: from 0 to 1 default value: 0.4' sentiments_connotation_threshold: type: number description: 'sentiment connotation threshold optional field specified as the probability index threshold for sentiment connotations related to the citation content if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value possible values: from 0 to 1 default value: 0.4' initial_dataset_filters: type: array items: {} description: 'initial dataset filtering parameters optional field initial filtering parameters that apply to fields in the Search endpoint you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like,not_like, has, has_not you can use the % operator with like and not_like to match any string of zero or more characters example: ["domain","", "logitech.com"] [["domain","","logitech.com"],"and",["content_info.connotation_types.negative",">",1000]] [["domain","","logitech.com"]], "and", [["content_info.connotation_types.negative",">",1000], "or", ["content_info.text_category","has",10994]]] for more information about filters, please refer to Content Analysis API – Filters learn more about the initial dataset filters in this help center article.' rank_scale: type: string description: 'defines the scale used for calculating and displaying the rank values optional field you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: one_hundred — rank values are displayed on a 0–100 scale one_thousand — rank values are displayed on a 0–1000 scale default value: one_thousand learn more about how this parameter works in this Help Center article' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/content_analysis/summary/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/asin/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon ASIN Results by id description: 'One Amazon product page, from a task queued by `post_dataforseo_merchant_amazon_asin_submit`. Returns `asin`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `item_types`, `items_count` and `items`, each item carrying `title`, `details`, `image_url`, `author`, `data_asin`, `parent_asin` and `product_asins` - that last field is the variant family, which is how you find the other sizes or colours. Measured at 38 KB. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 The `_fetch_html` twin returns the raw page source instead: measured at 2.6 MB against 82 KB for the parsed version of the same task, a 32x difference. Reach for it only when the parsed result is missing something you can point at.' operationId: get_dataforseo_merchant_amazon_asin_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/asin/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/asin/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon ASIN HTML Results by id description: 'The raw HTML of one Amazon product page, from a task queued by `post_dataforseo_merchant_amazon_asin_submit`. 🔴 Far larger than the 38 KB parsed twin; the equivalent Google pair measured 2.6 MB against 83 KB. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The parsed version is `get_dataforseo_merchant_amazon_asin_fetch`.' operationId: get_dataforseo_merchant_amazon_asin_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/asin/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/asin/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.003 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Amazon ASIN Tasks description: 'Queues a lookup of one Amazon product by `asin`, returning a task `id`. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. ⚠️ The Amazon endpoints require a locale-form language - `en_US`, or `English (United States)` - and reject the bare `en` that the Google endpoints accept. Omitting it entirely also answers `Invalid Field: ''language_name''`, so that message means wrong or missing, not just wrong. `get_dataforseo_merchant_amazon_languages` lists the 27 valid pairs. Measured at $0.0015 to submit. Retrieve with `get_dataforseo_merchant_amazon_asin_fetch`.' operationId: post_dataforseo_merchant_amazon_asin_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: asin: type: string description: product ID required field unique product identifier (ASIN) in Amazon you can receive the asin parameter by making a separate request to the Amazon Products endpoint priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations example: HA1,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations with their location_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations example: 9045969' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages example: English (United Kingdom)' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages example: en_GB' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: amazon.com, amazon.co.uk, amazon.fr, etc.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - asin allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/asin/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/asin/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon ASIN Completed Tasks description: 'Lists finished Amazon ASIN tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_merchant_amazon_asin_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: 'type of search engine can take the following values: shopping' tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.endpoint_advanced: type: string description: URL for collecting the results of the Amazon ASIN Advanced task tasks.result.endpoint_html: type: string description: URL for collecting the results of the Amazon ASIN HTML task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/asin/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Amazon Languages for Merchant API description: 'The 27 languages the Amazon endpoints accept, as `language_name` and `language_code`. Measured at 2.1 KB. Free: upstream cost is 0. **Read this before submitting an Amazon task.** These are locale pairs - `en_US` with `English (United States)`, `ar_SA` with `Arabic (Saudi Arabia)` - and the bare `en` that Google accepts is rejected here. The Google equivalent is `get_dataforseo_merchant_google_languages`.' operationId: get_dataforseo_merchant_amazon_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Amazon Locations for Merchant API description: 'The locations the Amazon endpoints accept. 🔴 **Measured at 20 MB.** This is not a response an agent should ever request: it is roughly eighty times the largest reference endpoint elsewhere in this provider and will exhaust any context window. `location_code` 2840 is the United States; look codes up in DataForSEO''s own documentation rather than pulling this list. Free upstream, which is exactly why nothing else warns you.' operationId: get_dataforseo_merchant_amazon_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: country: type: string description: 'country ISO code optional field specify the ISO code if you want to filter the list of locations by country example: us' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/products/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon Products Results by id description: 'The parsed result of an Amazon search queued by `post_dataforseo_merchant_amazon_products_submit`: ranked listings with title, price, rating and ASIN per item. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Feed an ASIN from here into `post_dataforseo_merchant_amazon_asin_submit` for the full product page. 🔴 The `_fetch_html` twin returns the raw page source instead: measured at 2.6 MB against 82 KB for the parsed version of the same task, a 32x difference. Reach for it only when the parsed result is missing something you can point at.' operationId: get_dataforseo_merchant_amazon_products_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/products/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/products/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon Products HTML Results by id description: 'The raw HTML of an Amazon search queued by `post_dataforseo_merchant_amazon_products_submit`. 🔴 Expect the same order of magnitude as the Google twin measured at 2.6 MB against 83 KB parsed - reach for it only to check what the parser dropped. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The parsed version is `get_dataforseo_merchant_amazon_products_fetch`.' operationId: get_dataforseo_merchant_amazon_products_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/products/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/products/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.003 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Amazon Products Tasks description: 'Queues an Amazon search for a `keyword`, returning a task `id`. `location_code`, `depth` and `se_domain` shape it. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. ⚠️ The Amazon endpoints require a locale-form language - `en_US`, or `English (United States)` - and reject the bare `en` that the Google endpoints accept. Omitting it entirely also answers `Invalid Field: ''language_name''`, so that message means wrong or missing, not just wrong. `get_dataforseo_merchant_amazon_languages` lists the 27 valid pairs. Retrieve with `get_dataforseo_merchant_amazon_products_fetch`.' operationId: post_dataforseo_merchant_amazon_products_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 700 characters in this field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article url: type: string description: 'direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: https://www.amazon.com/s/?field-keywords=shoes&language=en_US' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations example: HA1,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations with their location_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations example: 9045969' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages example: English (United Kingdom)' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages example: en_GB' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: amazon.com, amazon.co.uk, amazon.fr, etc.' depth: type: integer description: 'parsing depth optional field number of results to be retrieved from the Amazon results page default value: 100 max value: 700 Your account will be billed per each SERP containing up to 100 results; Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; The cost can be calculated on the Pricing page.' max_crawl_pages: type: integer description: 'page crawl limit optional field number of search results pages to crawl max value: 7 Note: the max_crawl_pages and depth parameters complement each other; learn more at our help center' department: type: string description: 'amazon product department optional field specify one of the following amazon departments for extracting product listings: "Arts & Crafts", "Automotive", "Baby", "Beauty & Personal Care", "Books", "Computers", "Digital Music", "Electronics", "Kindle Store", "Prime Video", "Women''s Fashion", "Men''s Fashion", "Girls'' Fashion", "Boys'' Fashion", "Deals", "Health & Household", "Home & Kitchen", "Industrial & Scientific", "Luggage", "Movies & TV", "Music, CDs & Vinyl", "Pet Supplies", "Software", "Sports & Outdoors", "Tools & Home Improvement", "Toys & Games", "Video Games"' search_param: type: string description: 'additional parameters of the search query optional field you can use the following Amazon search URL parameters for customizing the search example: &low-price=52 – search for products that cost more than 52 USD; &high-price=45 – search for products that cost less than 45 USD; &sort=relevancerank – sort results by relevance; &sort=featured-rank – sort results by featured products; &sort=price-asc-rank – sort by ascending price; &sort=price-desc-rank – sort by descending price; &sort=review-rank – sort by the average customer reviews value; &sort=date-desc-rank – sort by the newest arrival Note that search_param values will be ignored if any of the following parameters is used: price_min, price_max, sort_by' price_min: type: integer description: 'minimum product price optional field minimum price of the returned products listed on Amazon for the specified query example: 5 Note: if you specify price_min, the search_param parameter will be ignored' price_max: type: integer description: 'maximum product price optional field maximum price of the returned products listed on Amazon for the specified query example: 100 Note: if you specify price_max, the search_param parameter will be ignored' sort_by: type: string description: 'results sorting rules optional field the following sorting rules are supported: relevance, price_low_to_high, price_high_to_low, featured, avg_customer_review, newest_arrival example: sort_by:"relevance" Note: if you specify sort_by, the search_param parameter will be ignored' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/products/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/products/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon Products Completed Tasks description: 'Lists finished Amazon search tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_merchant_amazon_products_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: 'type of search engine can take the following values: organic' tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.tag: type: string description: user-defined task identifier tasks.result.endpoint_advanced: type: string description: URL for collecting the results of the Amazon Products Advanced task tasks.result.endpoint_html: type: string description: URL for collecting the results of the Amazon Products HTML task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/products/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/sellers/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon Sellers Results by id description: 'The sellers offering one Amazon product and what each charges, from a task queued by `post_dataforseo_merchant_amazon_sellers_submit`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This answers who else is in the buy box; the product itself is `get_dataforseo_merchant_amazon_asin_fetch`. 🔴 The `_fetch_html` twin returns the raw page source instead: measured at 2.6 MB against 82 KB for the parsed version of the same task, a 32x difference. Reach for it only when the parsed result is missing something you can point at.' operationId: get_dataforseo_merchant_amazon_sellers_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/sellers/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/sellers/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon Sellers HTML Results by id description: 'The raw HTML of an Amazon sellers page, from a task queued by `post_dataforseo_merchant_amazon_sellers_submit`. 🔴 Far larger than the parsed twin, on the order of the 2.6 MB against 83 KB measured on the Google pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The parsed version is `get_dataforseo_merchant_amazon_sellers_fetch`.' operationId: get_dataforseo_merchant_amazon_sellers_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/sellers/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/sellers/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.003 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Amazon Sellers Tasks description: 'Queues the list of sellers offering one Amazon product, returning a task `id`. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. ⚠️ The Amazon endpoints require a locale-form language - `en_US`, or `English (United States)` - and reject the bare `en` that the Google endpoints accept. Omitting it entirely also answers `Invalid Field: ''language_name''`, so that message means wrong or missing, not just wrong. `get_dataforseo_merchant_amazon_languages` lists the 27 valid pairs. Retrieve with `get_dataforseo_merchant_amazon_sellers_fetch`.' operationId: post_dataforseo_merchant_amazon_sellers_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: asin: type: string description: 'unique product identifier on Amazon required field you can get this value making a separate request to the Amazon Products endpoint note that there is no full list of possible values as the asin values is a dynamic value assigned by Amazon example: B085RFFC9Q learn more about the identifier in this help center guide' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of the location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available Amazon locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations example: London,England,United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available Amazon locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of the language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available Amazon languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages example: English (United States)' language_code: type: string description: 'language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available Amazon languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages example: en_US' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: amazon.co.uk, amazon.com.au, amazon.de, etc.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - asin allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/sellers/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/amazon/sellers/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Amazon Sellers Completed Tasks description: 'Lists finished Amazon seller tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_merchant_amazon_sellers_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: type of search engine tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.tag: type: string description: user-defined task identifier tasks.result.endpoint_advanced: type: string description: URL for collecting the results of Amazon Sellers Advanced task tasks.result.endpoint_html: type: string description: URL for collecting the results of Amazon Sellers HTML task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/amazon/sellers/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Shopping Languages for Merchant API description: 'The languages the Google Shopping endpoints accept, as `language_name` and `language_code`. Measured at 6.7 KB. Free: upstream cost is 0. These are plain codes such as `en`, unlike the Amazon list''s locale pairs - see `get_dataforseo_merchant_amazon_languages`, which rejects what this one accepts.' operationId: get_dataforseo_merchant_google_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Shopping Locations for Merchant API description: The locations the Google Shopping endpoints accept. 🔴 **Measured at 43 MB - the largest response found anywhere in this provider by two orders of magnitude.** Do not call this from an agent. `location_code` 2840 is the United States; look other codes up in DataForSEO's documentation. Free upstream, so no billing signal warns you before it lands. operationId: get_dataforseo_merchant_google_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: country: type: string description: 'country ISO code optional field specify the ISO code if you want to filter the list of locations by country example: us' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/product_info/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Product Info Results by id description: 'The detail page of one Google Shopping product, from a task queued by `post_dataforseo_merchant_google_product_info_submit`: specifications, description, images and the sellers carrying it. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For the search results that lead here use `get_dataforseo_merchant_google_products_fetch`; for buyer opinion, `get_dataforseo_merchant_google_reviews_fetch`.' operationId: get_dataforseo_merchant_google_product_info_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/product_info/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/product_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.002 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Shopping Product Info Tasks description: 'Queues a lookup of one specific Google Shopping product, returning a task `id`. Identify the product with `product_id` and the `gid` or `data_docid` taken from a `get_dataforseo_merchant_google_products_fetch` result. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. Retrieve with `get_dataforseo_merchant_google_product_info_fetch`.' operationId: post_dataforseo_merchant_google_product_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: product_id: type: string description: 'unique product identifier on Google Shopping required field if data_docid or gid is not specified we recommend specifying product_id together with data_docid and gid for optimal results; you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint example: 4485466949985702538 learn more about the parameter in this help center guide' data_docid: type: string description: 'unique identifier of the SERP data element required field if product_id or gid is not specified we recommend specifying data_docid together with product_id and gid for optimal results; you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint example: 13071766526042404278' gid: type: string description: 'global product identifier on Google Shopping required field if product_id or data_docid is not specified we recommend specifying gid together with product_id and data_docid for optimal results; you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint example: 4702526954592161872 learn more about the parameter in this help center guide' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of the location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations example: London,England,United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of the language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available Google Shopping languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages example: en' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: google.co.uk, google.com.au, google.de, etc.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype optional field corresponds to the datatype that will be sent to your server possible values: advanced' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - required: - product_id - required: - data_docid - required: - gid tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/product_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/product_info/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Product Info Completed Tasks description: 'Lists finished Google Shopping product-info tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_merchant_google_product_info_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: 'type of search engine can take the following values: shopping_specifications' tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.endpoint_advanced: type: string description: URL for collecting the results of the Google Shopping Product Specifications Advanced task tasks.result.endpoint_html: type: string description: 'URL for collecting the results of the Google Shopping Product Specifications HTML task note: HTML is not available for this endpoint, the value will be null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/product_info/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/products/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Products Results by id description: 'The parsed result of a Google Shopping search queued by `post_dataforseo_merchant_google_products_submit`. Returns `keyword`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `item_types`, `items_count` and `items`, each item carrying `rank_group`, `rank_absolute`, `position`, `xpath`, `title` and nested `items`. Measured at 83 KB for a ten-result search. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 The `_fetch_html` twin returns the raw page source instead: measured at 2.6 MB against 82 KB for the parsed version of the same task, a 32x difference. Reach for it only when the parsed result is missing something you can point at.' operationId: get_dataforseo_merchant_google_products_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/products/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/products/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Products HTML Results by id description: 'The raw HTML of a Google Shopping search queued by `post_dataforseo_merchant_google_products_submit`. 🔴 **Measured at 2.6 MB for a ten-result search, against 83 KB for the parsed twin** - one of the largest responses in this provider, and almost never what an agent wants. Use `get_dataforseo_merchant_google_products_fetch` unless you are verifying that the parser dropped something. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_merchant_google_products_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/products/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/products/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.002 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Shopping Products Tasks description: 'Queues a Google Shopping search for a `keyword`, returning a task `id`. `location_code`, `language_code`, `se_domain` and `depth` shape the search. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. Retrieve with `get_dataforseo_merchant_google_products_fetch`. Measured at $0.001 to submit.' operationId: post_dataforseo_merchant_google_products_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 700 characters in the keyword filed all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article url: type: string description: 'direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: https://www.google.com/search?q=fish&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of the location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations example: London,England,United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of the language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available Google Shopping languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages example: en' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: google.co.uk, google.com.au, google.de, etc.' depth: type: integer description: 'parsing depth optional field number of results to be retrieved from Google Shopping SERP default value: 40 max value: 120 Your account will be billed per each SERP containing up to 40 results; Setting depth above 40 may result in additional charges if the search engine returns more than 40 results; The cost can be calculated on the Pricing page.' max_crawl_pages: type: integer description: 'page crawl limit optional field number of search results pages to crawl max value: 7 Note: the max_crawl_pages and depth parameters complement each other; learn more at our help center' search_param: type: string description: 'additional parameters of the search query optional field you can use the following search URL parameters for customizing the search; example: &tbs=ppr_min:45 – search for products that cost more than 45 USD; &tbs=ppr_max:50 – search for products that cost less than 50 USD; &tbs=p_ord:p – sort by ascending price; &tbs=p_ord:pd – sort by descending price; &tbs=p_ord:rv – sort by review score; &tbs=ppr_max:50,p_ord:rv – sort by review score with the maximum price of 50 USD.; &udm=28 – use new Google Shopping markup with 40 SERP results returned by default (the cost for one SERP is deducted accordingly); the maximum depth is 200; this parameter must be specified without tbm=shop in the url; &shoprs=$value – specify advanced filtering and sorting in the new Shopping markup; replace $value with a string in protobuf Base64 format; learn more on our help center. Note that search_param values will be ignored if any of the following parameters are used: price_min, price_max, sort_by' price_min: type: integer description: 'minimum product price optional field minimum price of the returned products listed on Google Shopping for the specified query example: 5 Note: if you specify price_min, the search_param parameter will be ignored' price_max: type: integer description: 'maximum product price optional field maximum price of the returned products listed on Google Shopping for the specified query example: 100 Note: if you specify price_max, the search_param parameter will be ignored' sort_by: type: string description: 'results sorting rules optional field the following sorting rules are supported: review_score, price_low_to_high, price_high_to_low example: sort_by:"review_score" Note: if you specify sort_by, the search_param parameter will be ignored' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/products/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/products/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Products Completed Tasks description: 'Lists finished Google Shopping search tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This endpoint answers what is ready across the whole account, which is a different question.' operationId: get_dataforseo_merchant_google_products_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: 'type of search engine example: products' tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.tag: type: string description: user-defined task identifier tasks.result.endpoint_advanced: type: string description: URL for collecting the results of Google Shopping Products Advanced task tasks.result.endpoint_html: type: string description: URL for collecting the results of Google Shopping Products HTML task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/products/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/reviews/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Reviews Results by id description: 'Buyer reviews for one Google Shopping product, from a task queued by `post_dataforseo_merchant_google_reviews_submit`: rating, text, author and date per review. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For the product''s own specification and sellers use `get_dataforseo_merchant_google_product_info_fetch`.' operationId: get_dataforseo_merchant_google_reviews_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/reviews/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Shopping Reviews Tasks description: 'Queues the reviews of one Google Shopping product, returning a task `id`. Identify the product with `product_id` plus `gid` or `data_docid` from a products result. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. Retrieve with `get_dataforseo_merchant_google_reviews_fetch`.' operationId: post_dataforseo_merchant_google_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: gid: type: string description: 'global product identifier on Google Shopping required field we recommend specifying gid together with data_docid and product_id for optimal results; you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint example: 4702526954592161872 learn more about the parameter in this help center guide' product_id: type: string description: 'unique product identifier on Google Shopping optional field we recommend specifying product_id together with data_docid and gid for optimal results; you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint example: 4485466949985702538 learn more about the parameter in this help center guide' data_docid: type: string description: 'unique identifier of the SERP data element optional field we recommend specifying data_docid together with product_id and gid for optimal results; you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint example: 13071766526042404278' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. the cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations with their location_name parameters by making a separate request to https://api.dataforseo.com/v3/merchant/google/locations example: HA1,England,United Kingdom' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available locations with their location_code parameters by making a separate request to https://api.dataforseo.com/v3/merchant/google/locations example: 9045969' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with their language_name parameters by making a separate request to https://api.dataforseo.com/v3/merchant/google/languages example: English (United Kingdom)' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code parameters by making a separate request to https://api.dataforseo.com/v3/merchant/google/languages example: en_GB' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: google.co.uk, google.com.au, google.de, etc.' depth: type: integer description: 'parsing depth optional field number of reviews in SERP; we strongly recommend setting the parsing depth in the multiples of ten, because our system processes ten reviews in a row; maximum value: 8000 default value: 10 Your account will be billed per each SERP containing up to 10 results; Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype optional field corresponds to the datatype that will be sent to your server possible values: advanced' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - gid allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/reviews/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Reviews Completed Tasks description: 'Lists finished Google Shopping review tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_merchant_google_reviews_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: 'type of search engine can take the following values: shopping_specifications' tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.endpoint_advanced: type: string description: URL for collecting the results of the Google Shopping Product Specifications Advanced task tasks.result.endpoint_html: type: string description: 'URL for collecting the results of the Google Shopping Product Specifications HTML task note: HTML is not available for this endpoint, the value will be null' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/reviews/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/sellers/ad_url: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0 max: 0.0 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Sellers Ad URL description: 'Intended to return the full advertisement URL for a seller, with the parameters that seller attached. ⚠️ **Not usable as specified**: this spec declares no parameters for it, and calling it as written answers `status_code` 40400, `Not Found.`, with a null `tasks` array. Upstream expects identifiers this document does not describe. Withheld from the MCP server for that reason - an endpoint that always fails is worse than an absent one. Use the `check_url` on a `get_dataforseo_merchant_google_sellers_fetch` result instead.' operationId: get_dataforseo_merchant_google_sellers_ad_url responses: '200': description: Successful response content: application/json: schema: type: object properties: shop_ad_aclk: type: string description: unique ad click referral parameter you can obtain this parameter with Google Shopping Products or Google Shopping Sellers '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/sellers/ad_url source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/sellers/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Sellers Results by id description: 'The sellers offering one Google Shopping product and what each charges, from a task queued by `post_dataforseo_merchant_google_sellers_submit`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is the price-comparison view; the product itself is `get_dataforseo_merchant_google_product_info_fetch`.' operationId: get_dataforseo_merchant_google_sellers_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/sellers/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/sellers/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.002 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Shopping Sellers Tasks description: 'Queues the list of sellers offering one Google Shopping product, returning a task `id`. This family is asynchronous throughout: submit returns a task `id` in `tasks[0].id`, and the fetch tool returns the result once it is ready. 💰 The charge lands on the submit, measured at $0.001 to $0.0015; fetching is free, and re-fetching costs nothing. Retrieve with `get_dataforseo_merchant_google_sellers_fetch`.' operationId: post_dataforseo_merchant_google_sellers_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: product_id: type: string description: 'unique product identifier on Google Shopping required field if data_docid or gid is not specified we recommend specifying product_id together with data_docid and gid for optimal results; you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint example: 4485466949985702538 learn more about the parameter in this help center guide' data_docid: type: string description: 'unique identifier of the SERP data element required field if product_id or gid is not specified we recommend specifying data_docid together with product_id and gid for optimal results; you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint example: 13071766526042404278' gid: type: string description: 'global product identifier on Google Shopping required field if product_id or data_docid is not specified we recommend specifying gid together with product_id and data_docid for optimal results; you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint example: 4702526954592161872 learn more about the parameter in this help center guide' pvf: type: string description: 'product variant filter on Google Shopping optional field parameter in Google Shopping URL, setting optional product variant filtration; example: Eg4iBWNvbG9yKgV3aGl0ZRISIgxwYWNrYWdlIHNpemUqAjE0EgoiBHNpemUqAnhs' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' location_name: type: string description: 'full name of the location required field if you don’t specify location_code or location_coordinate if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations example: London,England,United Kingdom' location_code: type: integer description: 'location code required field if you don’t specify location_name or location_coordinate if you use this field, you don’t need to specify location_name or location_coordinate you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations example: 2840' location_coordinate: type: string description: 'GPS coordinates of a location required field if you don’t specify location_name or location_code if you use this field, you don’t need to specify location_name or location_code location_coordinate parameter should be specified in the “latitude,longitude,radius” format the maximum number of decimal digits for “latitude” and “longitude”: 7 the minimum value for “radius”: 199.9 example: 53.476225,-2.243572,200' language_name: type: string description: 'full name of the language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages example: English' language_code: type: string description: 'language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available Google Shopping languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages example: en' depth: type: integer description: 'parsing depth optional field number of results to be retrieved from Google Shopping SERP default value: 10 max value: 200 your account will be billed per each SERP containing up to 10 results; setting depth above 10 may result in additional charges if the search engine returns more than 10 results; the cost can be calculated on the Pricing page' se_domain: type: string description: 'search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: google.co.uk, google.com.au, google.de, etc.' get_shops_on_google: type: boolean description: 'include “buy on Google” shops optional field if set to true, the response will contain the list of sellers that allow to purchase a given product directly on Google Note: if set to true, the cost of a task will be doubled' additional_specifications: type: object description: 'object containing additional url parameters you can get additional information about the product by using the "additional_specifications object, which you can get by making a separate request to the Google Shopping Products endpoint example: "additional_specifications": { "eto": "16157121050167572763_0" }' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - required: - product_id - required: - data_docid - required: - gid tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/sellers/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/merchant/google/sellers/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Shopping Sellers Completed Tasks description: 'Lists finished Google Shopping seller tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_merchant_google_sellers_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the request’s URL tasks.result: type: array items: type: string description: array of results tasks.result.id: type: string description: task identifier of the completed task unique task identifier in our system in the UUID format tasks.result.se: type: string description: search engine specified when setting the task tasks.result.se_type: type: string description: 'type of search engine can take the following values: shopping' tasks.result.date_posted: type: string description: date when the task was posted (in the UTC format) tasks.result.tag: type: string description: user-defined task identifier tasks.result.endpoint_advanced: type: string description: URL for collecting the results of Google Shopping Sellers Advanced task tasks.result.endpoint_html: type: string description: URL for collecting the results of Google Shopping Sellers HTML task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/merchant/google/sellers/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_info/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Apple App Info Results by id description: 'One App Store app''s listing, from a task queued by `post_dataforseo_app_apple_app_info_submit`: description, developer, rating, size, version and screenshots. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For user opinion use `get_dataforseo_app_apple_app_reviews_fetch`.' operationId: get_dataforseo_app_apple_app_info_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_info/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Apple App Info Tasks description: 'Queues a lookup of one App Store app by `app_id`, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. Retrieve with `get_dataforseo_app_apple_app_info_fetch`. No HTML variant exists on the Apple half.' operationId: post_dataforseo_app_apple_app_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on App Store; you can find the ID in the URL of every app listed on App Store; example: in the URL https://apps.apple.com/us/app/id835599320 the id is 835599320' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: English' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_list/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Apple App List Results by id description: 'One App Store chart, from a task queued by `post_dataforseo_app_apple_app_list_submit`: ranked apps with position, title, rating and price. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_app_apple_app_list_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_list/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_list/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Apple App List Tasks description: 'Queues one of the App Store''s curated collections, chosen with `app_collection`, returning a task `id`. `depth` caps how far down the chart to read. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. Retrieve with `get_dataforseo_app_apple_app_list_fetch`. No HTML variant exists on the Apple half.' operationId: post_dataforseo_app_apple_app_list_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_collection: type: string description: 'app collection required field app collection on App Store from which apps will be collected; you can specify the following values: top_free_ios, top_paid_ios, top_grossing_ios, new_ios, new_free_ios, new_paid_ios' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: English' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' depth: type: integer description: 'parsing depth optional field number of apps to be returned from the App Store SERP; we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row; default value: 100 maximum value: 1000 Your account will be billed per each SERP containing up to 100 results; Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; The cost can be calculated on the Pricing page.' app_category: type: string description: 'application category on the App Store optional field you can filter the results by app category; example: lifestyle; you can review the full list of available categories here or by making a separate request to https://api.dataforseo.com/v3/app_data/apple/categories' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - app_collection allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_list/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_listings/categories: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of App Store Listings Categories for App Data API description: 'The categories `post_dataforseo_app_apple_app_listings_search_live` will accept, as `category` and `count` - 55 rows. Measured at 2.6 KB. Free: upstream cost is 0. Note the Apple and Google category vocabularies differ in both names and count; `get_dataforseo_app_google_app_listings_categories` is the other one.' operationId: get_dataforseo_app_apple_app_listings_categories responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.category: type: string description: name of the supported app category tasks.result.count: type: integer description: number of app listings that make up the supported app category '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_listings/categories source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_listings/search/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.204 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Apple App Listings Search Results description: 'Searches DataForSEO''s own index of App Store listings, synchronously - the Apple twin of `post_dataforseo_app_google_app_listings_search_live`, same arguments and same shape. Measured at 8.1 KB for one result. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 **Measured at $0.101 upstream, about eight times the flat rate billed**, and the price does not fall with `limit` - ask for many results in one call rather than few in several. Category names come from `get_dataforseo_app_apple_app_listings_categories`.' operationId: post_dataforseo_app_apple_app_listings_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array that were returned an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: the total number of relevant results in the database tasks.result.count: type: integer description: the number of items in the results array tasks.result.offset: type: integer description: offset in the results array of returned apps tasks.result.offset_token: type: string description: token for subsequent requests you can use this parameter in the POST request to avoid timeouts while trying to obtain over 100,000 results in a single request tasks.result.items: type: array items: type: string description: array of apps and related data tasks.result.items.app_id: type: string description: ID of the returned app tasks.result.items.se_domain: type: string description: search engine domain in a POST array tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.time_update: type: string description: 'date and time when SERP data was last updated in the ISO 8601 format: “YYYY-MM-DDThh:mm:ss.sssssssZ” example: 2023-05-23 10:16:19 +00:00' tasks.result.items.item: type: object description: detailed information about the app tasks.result.items.item.type: type: string description: 'the item’s type possible item types: "app_store_info_organic"' tasks.result.items.item.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.item.rank_absolute: type: integer description: absolute rank among all the listed apps absolute position among all apps on the list tasks.result.items.item.position: type: string description: 'the alignment of the element in SERP can take the following values: left' tasks.result.items.item.app_id: type: string description: ID of the returned app tasks.result.items.item.title: type: string description: title of the returned app tasks.result.items.item.url: type: string description: URL to the app page on App Store tasks.result.items.item.icon: type: string description: URL to the app icon tasks.result.items.item.description: type: string description: description of the returned app tasks.result.items.item.reviews_count: type: integer description: the total number of reviews the app has tasks.result.items.item.rating: type: object description: average rating of the app tasks.result.items.item.rating.rating_type: type: string description: 'the type of the rating can take the following values: Max5' tasks.result.items.item.rating.value: type: number description: the value of the rating tasks.result.items.item.rating.votes_count: type: integer description: the amount of feedback in this case, the value will be null tasks.result.items.item.rating.rating_max: type: integer description: the maximum value for a rating_type the maximum value for Max5 is 5 tasks.result.items.item.price: type: object description: price of the app tasks.result.items.item.price.current: type: number description: current price refers to the current price indicated in the element tasks.result.items.item.price.regular: type: number description: regular price refers to the regular price indicated in the element tasks.result.items.item.price.max_value: type: number description: the maximum price refers to the maximum price indicated in the element tasks.result.items.item.price.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.item.price.is_price_range: type: boolean description: price is provided as a range indicates whether a price is provided in a range tasks.result.items.item.price.displayed_price: type: string description: price string in the result raw price string as provided in the result tasks.result.items.item.is_free: type: boolean description: indicates whether the app is free tasks.result.items.item.main_category: type: string description: app category App Store category most relevant to the app tasks.result.items.item.categories: type: array items: type: string description: list of additional app categories App Store categories relevant to the app tasks.result.items.item.languages: type: array items: type: string description: languages supported in the app tasks.result.items.item.advisories: type: array items: type: string description: app advisory rating and usage restrictions tasks.result.items.item.developer: type: string description: name of the app developer tasks.result.items.item.developer_id: type: string description: ID of the developer on App Store tasks.result.items.item.developer_url: type: string description: URL to the developer page on App Store tasks.result.items.item.version: type: string description: current version of the app tasks.result.items.item.minimum_os_version: type: string description: minimum OS version required to install the app tasks.result.items.item.size: type: string description: size of the app tasks.result.items.item.released_date: type: string description: 'date and time when the app was released in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.item.last_update_date: type: string description: 'date and time when the app was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.item.update_notes: type: string description: update notes contains the latest update notes from the developer tasks.result.items.item.images: type: array items: type: string description: app images contains URLs to the images published on the app page on App Store tasks.result.items.item.similar_apps: type: array items: type: string description: similar apps displays apps similar to the app in a POST request tasks.result.items.item.similar_apps.app_id: type: string description: ID of the app tasks.result.items.item.similar_apps.title: type: string description: title of the app tasks.result.items.item.similar_apps.url: type: string description: URL to the app page on App Store tasks.result.items.item.more_apps_by_developer: type: array items: type: string description: similar apps information about apps built by the same developer tasks.result.items.item.more_apps_by_developer.app_id: type: string description: ID of the app tasks.result.items.item.more_apps_by_developer.title: type: string description: title of the app tasks.result.items.item.more_apps_by_developer.url: type: string description: URL to the app page on App Store '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: categories: type: array items: type: string description: app categories optional field the categories you specify are used to search for app listings; you can get the full list of available app listing categories by this link you can specify up to 10 categories description: type: string description: keyword in the app’s description optional field keywords that occur in the description of the app; can contain up to 200 characters title: type: string description: keyword in the app’s title optional field keywords that occur in the title of the app; can contain up to 200 characters filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["rating.value",">",3] you can receive the list of available filters by making a separate request to https://api.dataforseo.com/v3/app_data/apple/app_listings/available_filters' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["item.rating.value,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["item.rating.value,desc","item.rating.value,desc"]' limit: type: integer description: 'the maximum number of returned apps optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned apps optional field default value: 0 if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request learn more about this parameter on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_listings/search/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_reviews/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Apple App Reviews Results by id description: 'User reviews of one App Store app, from a task queued by `post_dataforseo_app_apple_app_reviews_submit`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the `depth` set at submit and cannot be narrowed at fetch time.' operationId: get_dataforseo_app_apple_app_reviews_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_reviews/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Apple App Reviews Tasks description: 'Queues the reviews of one App Store app by `app_id`, returning a task `id`. `depth` sets how many to collect. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. Retrieve with `get_dataforseo_app_apple_app_reviews_fetch`.' operationId: post_dataforseo_app_apple_app_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on App Store; you can find the ID in the URL of every app listed on App Store; example: in the URL https://apps.apple.com/us/app/id835599320 the id is 835599320' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: English' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' depth: type: integer description: 'parsing depth optional field number of reviews to be returned in the API response; we strongly recommend setting the parsing depth in the multiples of 50, because our system processes 50 reviews in a row; default value: 50; maximum value: 500; Your account will be billed per each SERP containing up to 50 results; Setting depth above 50 may result in additional charges if the search engine returns more than 50 results; The cost can be calculated on the Pricing page.' sort_by: type: string description: 'results sorting parameters optional field you can use this field to sort the results; possible types of sorting: most_recent — sort by the most recent reviews; most_helpful — sort by the most relevant reviews; default rule: most_helpful' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_searches/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Apple App Searches Results by id description: 'The parsed result of an App Store search queued by `post_dataforseo_app_apple_app_searches_submit`: ranked apps with `app_id`, `title`, `rating`, `reviews_count`, `is_free` and `price`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Feed an `app_id` from here into `post_dataforseo_app_apple_app_info_submit`.' operationId: get_dataforseo_app_apple_app_searches_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_searches/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/app_searches/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Apple App Searches Tasks description: 'Queues an App Store search for a `keyword`, returning a task `id`. `location_code`, `language_code` and `depth` shape it. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. ⚠️ Unlike its Google twin, the Apple half offers no HTML variant - the parsed result is the only form. Retrieve with `get_dataforseo_app_apple_app_searches_fetch`.' operationId: post_dataforseo_app_apple_app_searches_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 700 characters in the keyword field; all %## will be decoded (plus character ‘+’ will be decoded to a space character); if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B” learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if language_code is not specified if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: English' language_code: type: string description: 'search engine language code required field if language_name is not specified if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' depth: type: integer description: 'parsing depth optional field number of results to be returned from the App Store SERP; we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row; default value: 100 maximum value: 700 Your account will be billed per each SERP containing up to 100 results; Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; The cost can be calculated on the Pricing page.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/app_searches/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/categories: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Apple App Categories for App Data API description: 'The App Store category tree used by the task endpoints, under a `categories` key. Measured at 1.6 KB. Free: upstream cost is 0. This is a different list from `get_dataforseo_app_apple_app_listings_categories`, which serves the live listings search and carries counts - check which endpoint you are feeding before picking one.' operationId: get_dataforseo_app_apple_categories responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.categories: type: array items: type: string description: contains full list of supported app categories '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/categories source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Apple Languages for App Data API description: 'The 39 languages the Apple endpoints accept, as `language_name` and `language_code`. Measured at 2.4 KB. Free: upstream cost is 0. The Google half accepts 127 - see `get_dataforseo_app_google_languages` - so a code valid there may not be valid here. Free: upstream cost is 0, and it is reference data - fetch once and keep what you need rather than calling it per request. ⚠️ Catalogues in this provider are not shared between families: the same endpoint name under a different product returns a different list, and one of them measured 46 MB. Check the list belonging to the endpoint you are actually calling.' operationId: get_dataforseo_app_apple_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/apple/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Apple Locations for App Data API description: 'The 105 locations the Apple endpoints accept, as `location_code`, `location_name`, `location_name_parent` and `country_iso_code`. Measured at 13.8 KB - small, because Apple''s list is countries only. Free: upstream cost is 0. ⚠️ Its Google counterpart is not small: `get_dataforseo_app_google_locations` measured 46 MB.' operationId: get_dataforseo_app_apple_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.location_name_parent: type: integer description: 'the name of the superordinate location example: "location_code": 1006473, "location_name": "Altrincham,England,United Kingdom", "location_name_parent": "England,United Kingdom", where location_name_parent corresponds to: "location_code": 20339, "location_name": "England,United Kingdom" note: Apple App Data API currently supports countries only, that is why this value will always be null' tasks.result.country_iso_code: type: string description: ISO country code of the location tasks.result.location_type: type: string description: location type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/apple/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_info/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App Info Results by id description: 'One Google Play app''s store listing, from a task queued by `post_dataforseo_app_google_app_info_submit`: description, developer, rating, install counts, screenshots and version history. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. For user opinion rather than the listing use `get_dataforseo_app_google_app_reviews_fetch`. 🔴 The `_fetch_html` twin returns the raw store page instead: measured at 1.3 MB against 21 KB for the parsed version of the same task, a 63x difference.' operationId: get_dataforseo_app_google_app_info_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_info/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_info/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App Info HTML Results by id description: 'The raw HTML of one Google Play listing. 🔴 On the order of the 1.3 MB measured for the search HTML twin, against tens of kilobytes parsed. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The parsed version is `get_dataforseo_app_google_app_info_fetch`.' operationId: get_dataforseo_app_google_app_info_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_info/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google App Info Tasks description: 'Queues a lookup of one Google Play app by `app_id`, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. `location_code` 2840 is the United States. ⚠️ Do not fetch the Google location list to look one up - `get_dataforseo_app_google_locations` measured 46 MB. Retrieve with `get_dataforseo_app_google_app_info_fetch`. App ids come from a search result or from `post_dataforseo_app_google_app_listings_search_live`.' operationId: post_dataforseo_app_google_app_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on Google Play; you can find the ID in the URL of every app listed on Google Play; example: in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger the id is org.telegram.messenger' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if language_code is not specified if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: English' language_code: type: string description: 'search engine language code required field if language_name is not specified if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23' required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_list/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App List Results by id description: 'One Google Play chart, from a task queued by `post_dataforseo_app_google_app_list_submit`: ranked apps with position, title, rating and price. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 The `_fetch_html` twin returns the raw store page instead: measured at 1.3 MB against 21 KB for the parsed version of the same task, a 63x difference.' operationId: get_dataforseo_app_google_app_list_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_list/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_list/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App List HTML Results by id description: 'The raw HTML of a Google Play chart. 🔴 On the order of the 1.3 MB measured for the search HTML twin. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The parsed version is `get_dataforseo_app_google_app_list_fetch`.' operationId: get_dataforseo_app_google_app_list_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_list/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_list/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google App List Tasks description: 'Queues one of Google Play''s own curated collections - top free, top grossing, trending - chosen with `app_collection`, returning a task `id`. `depth` caps how far down the chart to read. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. Retrieve with `get_dataforseo_app_google_app_list_fetch`. This is the chart view; for a keyword search use `post_dataforseo_app_google_app_searches_submit`.' operationId: post_dataforseo_app_google_app_list_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_collection: type: string description: 'app collection required field app collection on Google Play from which apps will be collected; you can specify the following values: featured, topselling_paid, topselling_free, topselling_new_free, topselling_new_paid, topgrossing, movers_shakers Note: if featured is selected, the app_category parameter cannot be used' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if language_code is not specified if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: English' language_code: type: string description: 'search engine language code required field if language_name is not specified if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' depth: type: integer description: 'parsing depth optional field number of apps to be returned in the API response; we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row; default value: 100; maximum value: 200; Your account will be billed per each SERP containing up to 100 results; Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; The cost can be calculated on the Pricing page.' app_category: type: string description: 'application category on Google Play optional field you can filter the results by app category; example: family; you can receive the full list of available categories by making a separate request to https://api.dataforseo.com/v3/app_data/google/categories Note: app_category cannot be used if app_collection parameter is set to featured' age_rating: type: string description: 'filter results by age rating optional field you can use this field to filter the results by age rating; possible types of filtering: ages_up_to_5 — return apps approved for children up to 5 years old; ages_6_8 — return apps approved for children from 6 to 8 years old; ages_9_12 — return apps approved for children from 9 to 12 years old; by default, the API returns apps for all ages; Note: this filter works only in conjunction with the "category": "family" parameter' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23' required: - app_collection allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_list/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_listings/categories: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google App Listings Categories for App Data API description: 'The categories `post_dataforseo_app_google_app_listings_search_live` will accept, as `category` and `count` - 49 rows, with the count showing how many listings sit in each. Measured at 2.4 KB. Free: upstream cost is 0. Read it before searching; the counts also tell you which categories are worth searching at all.' operationId: get_dataforseo_app_google_app_listings_categories responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.category: type: string description: name of the supported app category tasks.result.count: type: integer description: number of app listings that make up the supported app category '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_listings/categories source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_listings/search/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.204 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google App Listings Search Results description: 'Searches DataForSEO''s own index of Google Play listings, synchronously - no task to submit. Match on `categories`, `title` or `description`, narrow with `filters` and `order_by`, page with `limit`, `offset` and `offset_token`. Returns `total_count`, `count`, `offset`, `offset_token` and `items`, each carrying `app_id`, `se_domain`, `location_code`, `language_code`, `check_url`, `time_update` and a nested `item`. Measured at 8.8 KB for one result. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. 🔴 **Measured at $0.101 upstream for that single result - roughly eight times the flat rate billed, and the second most expensive endpoint in this provider.** The price does not fall with `limit`, so one call for many results is far better value than many calls for few. Category names come from `get_dataforseo_app_google_app_listings_categories`.' operationId: post_dataforseo_app_google_app_listings_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array that were returned an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results tasks.result.total_count: type: integer description: the total number of relevant results in the database tasks.result.count: type: integer description: the number of items in the results array tasks.result.offset: type: integer description: offset in the results array of returned apps tasks.result.offset_token: type: string description: token for subsequent requests you can use this parameter in the POST request to avoid timeouts while trying to obtain over 100,000 results in a single request tasks.result.items: type: array items: type: string description: array of apps and related data tasks.result.items.app_id: type: string description: ID of the returned app tasks.result.items.se_domain: type: string description: search engine domain in a POST array tasks.result.items.location_code: type: integer description: location code in a POST array tasks.result.items.language_code: type: string description: language code in a POST array tasks.result.items.check_url: type: string description: direct URL to search engine results you can use it to make sure that we provided accurate results tasks.result.items.time_update: type: string description: 'date and time when SERP data was last updated in the ISO 8601 format: “YYYY-MM-DDThh:mm:ss.sssssssZ” example: 2023-05-23 10:16:19 +00:00' tasks.result.items.item: type: object description: detailed information about the app tasks.result.items.item.type: type: string description: 'the item’s type possible item types: "google_play_info_organic"' tasks.result.items.item.rank_group: type: integer description: position within a group of elements with identical type values positions of elements with different type values are omitted from rank_group tasks.result.items.item.rank_absolute: type: integer description: absolute rank among all the listed apps absolute position among all apps on the list tasks.result.items.item.position: type: string description: 'the alignment of the element in SERP can take the following values: left' tasks.result.items.item.app_id: type: string description: ID of the returned app tasks.result.items.item.title: type: string description: title of the returned app tasks.result.items.item.url: type: string description: URL to the app page on Google Play tasks.result.items.item.icon: type: string description: URL to the app icon tasks.result.items.item.description: type: string description: description of the returned app tasks.result.items.item.reviews_count: type: integer description: the total number of reviews the app has tasks.result.items.item.rating: type: object description: average rating of the app tasks.result.items.item.rating.rating_type: type: string description: 'the type of the rating can take the following values: Max5' tasks.result.items.item.rating.value: type: number description: the value of the rating tasks.result.items.item.rating.votes_count: type: integer description: the amount of feedback in this case, the value will be null tasks.result.items.item.rating.rating_max: type: integer description: the maximum value for a rating_type the maximum value for Max5 is 5 tasks.result.items.item.price: type: object description: price of the app tasks.result.items.item.price.current: type: number description: current price refers to the current price indicated in the element tasks.result.items.item.price.regular: type: number description: regular price refers to the regular price indicated in the element tasks.result.items.item.price.max_value: type: number description: the maximum price refers to the maximum price indicated in the element tasks.result.items.item.price.currency: type: string description: currency of the listed price ISO code of the currency applied to the price tasks.result.items.item.price.is_price_range: type: boolean description: price is provided as a range indicates whether a price is provided in a range tasks.result.items.item.price.displayed_price: type: string description: price string in the result raw price string as provided in the result tasks.result.items.item.is_free: type: boolean description: indicates whether the app is free tasks.result.items.item.main_category: type: string description: app category Google Play category relevant to the app tasks.result.items.item.installs: type: string description: approximate number of app installs tasks.result.items.item.installs_count: type: integer description: accurate number of app installs tasks.result.items.item.developer: type: string description: name of the app developer tasks.result.items.item.developer_id: type: string description: ID of the developer on Google Play tasks.result.items.item.developer_url: type: string description: URL to the developer page on Google Play tasks.result.items.item.developer_email: type: string description: email address of the developer tasks.result.items.item.developer_address: type: string description: physical address of the developer tasks.result.items.item.developer_website: type: string description: official website of the developer tasks.result.items.item.version: type: string description: current version of the app tasks.result.items.item.minimum_os_version: type: string description: minimum OS version required to install the app tasks.result.items.item.size: type: string description: size of the app tasks.result.items.item.released_date: type: string description: 'date and time when the app was released in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.item.last_update_date: type: string description: 'date and time when the app was last updated in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”; example: 2019-11-15 12:57:46 +00:00' tasks.result.items.item.update_notes: type: string description: update notes contains the latest update notes from the developer tasks.result.items.item.images: type: array items: type: string description: app images contains URLs to the images published on the app page on Google Play tasks.result.items.item.videos: type: array items: type: string description: app videos contains URLs to the video published on the app page on Google Play tasks.result.items.item.similar_apps: type: array items: type: string description: similar apps displays apps similar to the app in a POST request tasks.result.items.item.similar_apps.app_id: type: string description: ID of the app tasks.result.items.item.similar_apps.title: type: string description: title of the app tasks.result.items.item.similar_apps.url: type: string description: URL to the app page on Google Play tasks.result.items.item.more_apps_by_developer: type: array items: type: string description: similar apps information about apps built by the same developer tasks.result.items.item.more_apps_by_developer.app_id: type: string description: ID of the app tasks.result.items.item.more_apps_by_developer.title: type: string description: title of the app tasks.result.items.item.more_apps_by_developer.url: type: string description: URL to the app page on Google Play tasks.result.items.item.genres: type: array items: type: string description: app genres contains relevant app categories tasks.result.items.item.tags: type: array items: type: string description: app tags contains relevant app tags '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: categories: type: array items: type: string description: app categories optional field the categories you specify are used to search for app listings; you can get the full list of available app listing categories by this link you can specify up to 10 categories description: type: string description: keyword in the app’s description optional field keywords that occur in the description of the app; can contain up to 200 characters title: type: string description: keyword in the app’s title optional field keywords that occur in the title of the app; can contain up to 200 characters filters: type: array items: {} description: 'array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, , , >, >=, =, , in, not_in, like, not_like you can use the % operator with like and not_like to match any string of zero or more characters example: ["item.rating.value",">",3] you can receive the list of available filters by making a separate request to https://api.dataforseo.com/v3/app_data/google/app_listings/available_filters' order_by: type: array items: type: string description: 'results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["item.installs_count,asc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["item.rating.value,desc","item.installs_count,asc"]' limit: type: integer description: 'the maximum number of returned apps optional field default value: 100 maximum value: 1000' offset: type: integer description: 'offset in the results array of returned apps optional field default value: 0 if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead.' offset_token: type: string description: 'token for subsequent requests optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request; by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request learn more about this parameter on our Help Center' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_listings/search/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_reviews/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App Reviews Results by id description: 'User reviews of one Google Play app, from a task queued by `post_dataforseo_app_google_app_reviews_submit`: rating, text, author, date and helpful counts per review. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the `depth` set at submit, so cap it there - it cannot be narrowed at fetch time. For the listing rather than the reviews use `get_dataforseo_app_google_app_info_fetch`.' operationId: get_dataforseo_app_google_app_reviews_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_reviews/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google App Reviews Tasks description: 'Queues the reviews of one Google Play app by `app_id`, returning a task `id`. `depth` sets how many to collect. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. Retrieve with `get_dataforseo_app_google_app_reviews_fetch`.' operationId: post_dataforseo_app_google_app_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: app_id: type: string description: 'id of the app required field ID of the mobile application on Google Play; you can find the ID in the URL of every app listed on Google Play; example: https://play.google.com/store/apps/details?id=org.telegram.messenger' location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: 9061121' language_name: type: string description: 'full name of search engine language required field if you don’t specify language_code if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: English' language_code: type: string description: 'search engine language code required field if you don’t specify language_name if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' depth: type: integer description: 'parsing depth optional field number of reviews to be returned in the API response; we strongly recommend setting the parsing depth in the multiples of 150, because our system processes 150 reviews in a row; default value: 150; maximum value: 100000; Your account will be billed per each SERP containing up to 150 results; Setting depth above 150 may result in additional charges if the search engine returns more than 150 results; The cost can be calculated on the Pricing page.' rating: type: integer description: 'filter reviews by rating optional field you can use this field to filter the results; possible types of filtering: 5 — return reviews with five-star rating only; 4 — return reviews with four-star rating only; 3 — return reviews with three-star rating only; 2 — return reviews with two-star rating only; 1 — return reviews with one-star rating only; by default, the API returns all reviews regardless of the number of stars' sort_by: type: string description: 'results sorting parameters optional field you can use this field to sort the results; possible types of sorting: newest — sort by the most recent reviews; most_relevant — sort by the most relevant reviews; default rule: most_relevant' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23' required: - app_id allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - required: - language_name - required: - language_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_searches/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App Searches Results by id description: 'The parsed result of a Google Play search queued by `post_dataforseo_app_google_app_searches_submit`. Returns `keyword`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `se_results_count`, `items_count` and `items`, each item carrying `rank_group`, `rank_absolute`, `position`, `app_id`, `title`, `url`, `icon`, `reviews_count`, `rating`, `is_free` and `price`. Measured at 21 KB for ten results. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Feed an `app_id` from here into `post_dataforseo_app_google_app_info_submit`. 🔴 The `_fetch_html` twin returns the raw store page instead: measured at 1.3 MB against 21 KB for the parsed version of the same task, a 63x difference.' operationId: get_dataforseo_app_google_app_searches_fetch responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 30 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_searches/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_searches/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google App Searches HTML Results by id description: 'The raw HTML of a Google Play search queued by `post_dataforseo_app_google_app_searches_submit`. 🔴 **Measured at 1.3 MB against 21 KB for the parsed twin** - reach for it only when verifying that the parser dropped something. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The parsed version is `get_dataforseo_app_google_app_searches_fetch`.' operationId: get_dataforseo_app_google_app_searches_fetch_html responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: task identifier unique task identifier in our system in the UUID format you will be able to use it within 7 days to request the results of the task at any time '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_searches/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/app_searches/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google App Searches Tasks description: 'Queues a Google Play search for a `keyword`, returning a task `id`. `location_code`, `language_code` and `depth` shape it. Asynchronous: submit returns a task `id` in `tasks[0].id` and the fetch tool returns the result once ready. 💰 The charge lands on the submit, measured at $0.0012; fetching is free, including re-fetching. `location_code` 2840 is the United States. ⚠️ Do not fetch the Google location list to look one up - `get_dataforseo_app_google_locations` measured 46 MB. Retrieve with `get_dataforseo_app_google_app_searches_fetch`.' operationId: post_dataforseo_app_google_app_searches_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: 'general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions' status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasksarray tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: unique task identifier in our system in the Universally unique identifier (UUID) format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: informational message of the task tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the same parameters that you specified in the POST request tasks.result: type: array items: type: string description: array of results in this case, the value will be null '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: keyword required field you can specify up to 700 characters in the keyword field; all %## will be decoded (plus character ‘+’ will be decoded to a space character); if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B” learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article location_name: type: string description: 'full name of search engine location required field if you don’t specify location_code if you use this field, you don’t need to specify location_code you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: West Los Angeles,California,United States' location_code: type: integer description: 'search engine location code required field if you don’t specify location_name if you use this field, you don’t need to specify location_name you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations example: 9061121' language_name: type: string description: 'full name of search engine language optional field if you use this field, you don’t need to specify language_code you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: English' language_code: type: string description: 'search engine language code optional field if you use this field, you don’t need to specify language_name you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages example: en' priority: type: integer description: 'task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the Pricing page.' depth: type: integer description: 'parsing depth optional field number of results to be returned to be returned from the Google Play SERP; we strongly recommend setting the parsing depth in the multiples of 30, because our system processes 30 results in a row; default value: 30; maximum value: 200; Your account will be billed per each SERP containing up to 30 results; Setting depth above 30 may result in additional charges if the search engine returns more than 30 results; The cost can be calculated on the Pricing page.' tag: type: string description: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response postback_url: type: string description: 'URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23' postback_data: type: string description: 'postback_url datatype required field if you specify postback_url corresponds to the datatype that will be sent to your server possible values: advanced, html' pingback_url: type: string description: 'notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/app_searches/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/categories: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google App Categories for App Data API description: 'The Google Play category tree used by the task endpoints, under a `categories` key. Measured at 1.2 KB. Free: upstream cost is 0. Distinct from `get_dataforseo_app_google_app_listings_categories`, which serves the live listings search and carries per-category counts.' operationId: get_dataforseo_app_google_categories responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.categories: type: array items: type: string description: contains full list of supported app categories '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/categories source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Languages for App Data API description: 'The 127 languages the Google Play endpoints accept, as `language_name` and `language_code`. Measured at 6.7 KB. Free: upstream cost is 0. The Apple half accepts only 39 - see `get_dataforseo_app_apple_languages` - so do not assume a code carries across.' operationId: get_dataforseo_app_google_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.language_name: type: string description: language name tasks.result.language_code: type: string description: language code according to ISO 639-1 '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/app_data/google/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Locations for App Data API description: 'The locations the Google Play endpoints accept. 🔴 **Measured at 46 MB across 269,681 rows - the largest response found anywhere in this provider.** Google''s list is every city and region worldwide, where the Apple equivalent is 105 countries and 13.8 KB. Do not call this from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s own documentation. Free upstream, so nothing bills and nothing warns before it lands.' operationId: get_dataforseo_app_google_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: the current version of the API status_code: type: integer description: general status code you can find the full list of the response codes here status_message: type: string description: general informational message you can find the full list of general informational messages here time: type: string description: execution time, seconds cost: type: number description: total tasks cost, USD tasks_count: type: integer description: the number of tasks in the tasks array tasks_error: type: integer description: the number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: array of tasks tasks.id: type: string description: task identifier unique task identifier in our system in the UUID format tasks.status_code: type: integer description: 'status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here' tasks.status_message: type: string description: informational message of the task you can find the full list of general informational messages here tasks.time: type: string description: execution time, seconds tasks.cost: type: number description: cost of the task, USD tasks.result_count: type: integer description: number of elements in the result array tasks.path: type: array items: type: string description: URL path tasks.data: type: object description: contains the parameters passed in the URL of the GET request tasks.result: type: array items: type: string description: array of results tasks.result.location_code: type: integer description: location code tasks.result.location_name: type: string description: full name of the location tasks.result.location_name_parent: type: string description: 'the name of the superordinate location example: "location_code": 1006473, "location_name": "Altrincham,England,United Kingdom", "location_name_parent": "England,United Kingdom", where location_name_parent corresponds to: "location_code": 20339, "location_name": "England,United Kingdom"' tasks.result.country_iso_code: type: string description: ISO country code of the location tasks.result.location_type: type: string description: location type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/app_data/google/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/business_listings/search/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.0312 max: 0.744 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Business Listings Search Tasks description: 'Searches DataForSEO''s own index of local business listings by `categories`, `description`, `title` and `location_coordinate` - a latitude, longitude and radius triple. Returns `total_count`, `count`, `offset`, `offset_token` and `items`, paged with the token. Measured at 4.0 KB for one result and $0.01236 upstream, close to the flat rate billed - **the only reasonably priced way into this family**. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This reads an index and answers immediately; everything else here queues a live scrape of the source. Start with this and drill in only where it matters.' operationId: post_dataforseo_business_listings_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.total_count: type: integer description: '*total number of results in our database relevant to your request*' result.count: type: integer description: '*item types* the number of items in the `items` array' result.offset: type: integer description: '*offset in the results array of returned businesses*' result.offset_token: type: string description: '*token for subsequent requests* by specifying the unique `offset_token` when setting a new task, you will get the subsequent results of the initial task; `offset_token` values are unique for each subsequent task' items: type: array items: type: string description: '*encountered item types* types of search engine results encountered in the `items` array; possible item types: `business_listing`' items.type: type: string description: '*type of element = **‘business\_listing’***' items.title: type: string description: '*title of the element in SERP* the name of the business entity for which the results are collected' items.original_title: type: string description: '*original title of the element* original title not translated by Google' items.description: type: string description: '*description of the element in SERP* the description of the business entity for which the results are collected' items.category: type: string description: '*business category* Google My Business general category that best describes the services provided by the business entity' items.category_ids: type: array items: type: string description: '*global category IDs* universal category IDs that do not change based on the selected country' items.additional_categories: type: array items: type: string description: '*additional business categories* additional Google My Business categories that describe the services provided by the business entity in more detail' items.cid: type: string description: '*google-defined client id* unique id of a local establishment learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.feature_id: type: string description: '*the unique identifier of the element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.address: type: string description: '*street address of the business entity*' items.address_info: type: object description: '*object containing address components of the business entity*' items.borough: type: string description: '*administrative unit or district the business entity location belongs to*' items.city: type: string description: '*name of the city where the business entity is located*' items.zip: type: string description: '*ZIP code of the business entity*' items.region: type: string description: '*DMA region of the business entity location*' items.country_code: type: string description: '*ISO country code of the business entity location*' items.place_id: type: string description: '*unique place identifier* [place id](https://developers.google.com/places/place-id) of the local establishment featured in the element learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.phone: type: string description: '*phone number of the business entity*' items.url: type: string description: '*absolute url of the business entity*' items.domain: type: string description: '*domain of the business entity*' items.logo: type: string description: '*URL of the logo featured in Google My Business profile*' items.main_image: type: string description: '*URL of the main image featured in Google My Business profile*' items.total_photos: type: integer description: '*total count of images featured in Google My Business profile*' items.snippet: type: string description: '*additional information on the business entity*' items.latitude: type: number description: '*latitude coordinate of the local establishments in google maps* example: `"latitude": 51.584091`' items.longitude: type: number description: '*longitude coordinate of the local establishment in google maps* example: `"longitude": -0.31365919999999997`' items.is_claimed: type: boolean description: '*shows whether the entity is verified by its owner on Google Maps*' items.attributes: type: object description: '*service details in a form of user-reviewed checks;* service details of a business entity displayed in a form of checks and based on user feedback and business `category`' items.available_attributes: type: object description: '*available attributes* indicates attributes a business entity can offer' items.unavailable_attributes: type: object description: '*unavailable attributes* indicates attributes a business entity cannot offer' items.place_topics: type: object description: '*keywords mentioned in customer reviews* contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword example: `"place_topics": {"egg roll": 48,"birthday": 33}`' items.rating: type: object description: '*the element’s rating* the popularity rate based on reviews and displayed in SERP' items.rating_type: type: string description: '*the type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' items.value: type: integer description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback*' items.rating_max: type: integer description: '*the maximum value for a `rating_type`*' items.hotel_rating: type: integer description: '*hotel class rating* class ratings range between 1-5 stars, [learn more](https://support.google.com/business/answer/7660515?hl=en) if there is no hotel class rating information, the value will be `null`' items.price_level: type: string description: '*property price level* can take values: `inexpensive`, `moderate`, `expensive`, `very_expensive` if there is no price level information, the value will be `null`' items.rating_distribution: type: object description: '*the distribution of ratings of the business entity* the object displays the number of 1-star to 5-star ratings, as reviewed by users' items.1: type: integer description: '*the number of 1-star ratings*' items.2: type: integer description: '*the number of 2-star ratings*' items.3: type: integer description: '*the number of 3-star ratings*' items.4: type: integer description: '*the number of 4-star ratings*' items.5: type: integer description: '*the number of 5-star ratings*' items.people_also_search: type: array items: type: string description: '*related business entities*' items.work_time: type: object description: '*work time details* information related to operational hours of the business entity' items.work_hours: type: object description: '*open hours* information about work hours of the local establishment' items.timetable: type: object description: '*work hours timetable*' items.sunday: type: array items: type: string description: '*work hours on Sunday* **can take values of the corresponding days of the week**' items.open: type: object description: '*opening time*' items.hour: type: integer description: '*hours in the 24-hour format*' items.minute: type: integer description: '*minutes*' items.close: type: object description: '*closing time*' items.current_status: type: string description: '*current status of the establishment* possible values: `open`, `close`, `temporarily_closed`, `closed_forever`' popular_times: type: object description: '*popular times* information related to busy hours of the business entity' popular_times.popular_times_by_days: type: object description: '*popular hours* information about busy hours of the local establishment on each day of the week' popular_times.sunday: type: array items: type: string description: '*busy hours on Sunday* **can take values of the corresponding days of the week**' popular_times.time: type: object description: '*busy hours*' popular_times.hour: type: integer description: '*hours in a 24-hour format*' popular_times.minute: type: integer description: '*minutes*' popular_times.popular_index: type: integer description: '*popularity index* relative time-bound popularity index measured from `0` to `100`; higher value corresponds to a busier time of a day' local_business_links: type: array items: type: string description: '*available interactions with the business* list of options to interact with the business directly from search results' local_business_links.type: type: string description: '*type of element* possible values: `"reservation""order""delivery_services_element""menu"`' local_business_links.title: type: string description: '*title of the element* domain of the reservation software' local_business_links.url: type: string description: '*URL to the services*' contact_info: type: array items: type: string description: '*available contacts of the business* list of contacts to interact with the business' contact_info.type: type: string description: '*type of contact element*' contact_info.value: type: string description: '*contact displayed in SERP* example: `"+119797979736"`' contact_info.source: type: string description: '*data source*' contact_info.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' contact_info.last_updated_time: type: string description: '*date and time when the data was last updated* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2023-01-26 09:03:15 +00:00`' contact_info.first_seen: type: string description: '*date and time when our crawler found the business listing element for the first time* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2023-03-11 10:04:11 +00:00`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: categories: type: array items: type: string description: '*business categories* optional field the categories you specify are used to search for business listings; if you don’t use this field, we will return business listings found in the specified location; you can specify **up to 10 categories**' description: type: string description: '*description of the element in SERP* optional field the description of the business entity for which the results are collected; can contain up to 200 characters' title: type: string description: '*title of the element in SERP* optional field the name of the business entity for which the results are collected; can contain up to 200 characters' is_claimed: type: boolean description: '*indicates whether the business is verified by its owner on Google Maps* optional field' location_coordinate: type: string description: '*GPS coordinates of a location* optional field `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the value of *“radius”* is specified in kilometres (km) the minimum value for *“radius”*: `1` the maximum value for *“radius”*: `100000` example: `53.476225,-2.243572,200`' filters: type: array items: {} description: '*array of results filtering parameters* optional field **you can add several filters at once (8 filters maximum)** you should set a logical operator `and`, `or` between the conditions the following operators are supported: `regex`, `not_regex`, ``, `>=`, `=`, ``, `in`, `not_in`, `like`, `not_like`, `ilike`, `not_ilike`, `match`, `not_match` you can use the `%` operator with `like` and `not_like` to match any string of zero or more characters example: `["rating.value",">",3]` you can receive the list of available filters by making a separate request to `https://api.dataforseo.com/v3/business_data/business_listings/available_filters`' order_by: type: array items: type: string description: '*results sorting rules* optional field you can use the same values as in the `filters` array to sort the results possible sorting types: `asc` – results will be sorted in the ascending order `desc` – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: `["rating.value,desc"]`**note that you can set no more than three sorting rules in a single request** you should use a comma to separate several sorting rules example: `["rating.value,desc","rating.votes_count,desc"]`' limit: type: integer description: '*the maximum number of returned businesses* optional field default value: `100` maximum value: `1000`' offset: type: integer description: '*offset in the results array of returned businesses* optional field default value: `0` if you specify the `10` value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities' offset_token: type: string description: '*token for subsequent requests* optional field provided in the identical filed of the response to each request; use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request; by specifying the unique `offset_token` value from the response array, you will get the subsequent results of the initial task; `offset_token` values are unique for each subsequent task **Note:** if the `offset_token` is specified in the request, all other parameters should be identical to the previous request' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' example: - title: Starbucks location_coordinate: 35.6595,139.7005,5 limit: 1 tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/business_listings/search/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/extended_reviews/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Business Data Google Extended Reviews Results by id description: 'Retrieves queued the full Google review history for a business, past the first page the standard endpoint returns by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the depth set at submit and cannot be narrowed here.' operationId: get_dataforseo_business_google_extended_reviews_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)**' result.type: type: string description: '*search engine type in a POST array*' result.se_domain: type: string description: '*search engine domain in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.title: type: string description: '*title of the ‘reviews’ element in SERP* the name of the local establishment for which the reviews are collected' result.sub_title: type: string description: '*subtitle of the ‘reviews’ element in SERP* additional information (e.g., address) on the ‘reviews’ element for which the reviews are collected' result.rating: type: object description: '*rating of the corresponding local establishment* popularity rate based on reviews and displayed in SERP' result.rating_type: type: string description: '*type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' result.value: type: number description: '*the average rating based on all reviews*' result.votes_count: type: integer description: '*the number of votes*' result.rating_max: type: integer description: '*the maximum value for a `rating_type`*' result.feature_id: type: string description: '*the unique identifier of the ‘reviews’ element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.place_id: type: string description: '*unique identifier of a business location assigned by Google* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.cid: type: string description: '*google-defined client id* unique id of a local establishment learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.reviews_count: type: integer description: '*the total number of reviews*' result.items_count: type: integer description: '*the number of reviews items in the results array* you can get more results by using the `depth` parameter when setting a task' items: type: array items: type: string description: '*found reviews* you can get more results by using the `depth` parameter when setting a task' items.type: type: string description: '*type of element = **‘images\_element’***' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed reviews* absolute position among all reviews on the list' items.position: type: string description: '*the alignment of the review in SERP* can take the following values: `right`' items.xpath: type: string description: '*the [XPath](https://en.wikipedia.org/wiki/XPath) of the review*' items.review_text: type: string description: '*the content of the review*' items.original_review_text: type: string description: '*original content of the review* the original content of the review, no auto-translate applied' items.time_ago: type: string description: '*the time of publication* indicates the time (in the ‘time ago’ format) when the review was listed' items.timestamp: type: string description: '*date and time when a review was published* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.rating: type: object description: '*the rating score submitted by the reviewer*' items.rating_type: type: string description: '*the type of the rating* can take the following values: `Max5`, `CustomMax`' items.value: type: number description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback* indicated the number of votes the review obtained' items.rating_max: type: integer description: '*the maximum value for a `rating_type`* the maximum value for `Max5` is 5' items.reviews_count: type: integer description: '*total number of reviews submitted by the reviewer*' items.photos_count: type: integer description: '*total number of photos submitted by the reviewer*' items.local_guide: type: boolean description: '*indicates whether the reviewer has a ‘local guide’ status*' items.profile_name: type: string description: '*profile name of the reviewer*' items.profile_url: type: string description: '*URL of the reviewer’s profile*' items.review_url: type: string description: '*the URL of the review*' items.profile_image_url: type: string description: '*URL of the reviewer’s profile image*' items.owner_answer: type: string description: '*text of the owner’s response* the owner’s response to the review' items.original_owner_answer: type: string description: '*original text of the owner’s response* the original response to the review, no auto-translate applied' items.owner_time_ago: type: string description: '*publication time* indicates the time (in the ‘time ago’ format) when the owner submitted the response to the review' items.owner_timestamp: type: string description: '*date and time of the owner’s reply to the review* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.review_id: type: string description: '*the unique identifier of a review on Google* example: `ChZDSUhNMG9nS0VJQ0FnSUMxbHFyMFlnEAE`' items.images: type: array items: type: string description: '*images submitted by the reviewer*' items.alt: type: string description: '*alt tag of the image*' items.image_url: type: string description: '*URL of the image featured in the review*' items.review_highlights: type: array items: type: string description: '*review highlights* contains highlighted review criteria and assessments' items.feature: type: string description: '*reviewed feature*' items.assessment: type: string description: '*feature assessment*' items.source: type: object description: '*source of the review* contains information about the source where the review was posted' items.title: type: string description: '*name of the source where the review was posted*' items.image: type: string description: '*featured image of the source*' items.domain: type: string description: '*domain of the source where the review was posted*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/extended_reviews/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/extended_reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0045 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Business Data Google Extended Reviews Tasks description: 'Queues the full Google review history for a business, past the first page the standard endpoint returns, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_google_extended_reviews_fetch`; the shorter version is `post_dataforseo_business_google_reviews_submit`.' operationId: post_dataforseo_business_google_extended_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field if you don’t specify `cid` or `place_id`** the keyword you specify should indicate the name of the local establishment; you can specify **up to 700 characters** in the `keyword` filed; all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your `keyword`, please specify it as “%25”; if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, **the charge per task will be multiplied by 5** Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis) **Note:** if you use this field, your account will be charged **three times the standard rate** for tasks involving the [Google Reviews API](https://dataforseo.com/pricing/business-data/google-reviews-api)' cid: type: string description: '*unique, google-defined id of the business entity* **required field if you don’t specify `keyword` or `place_id`** example: `194604053573767737` learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)**Note:** if you use this field, your account will be charged **two times the standard rate** for tasks involving the [Google Reviews API](https://dataforseo.com/pricing/business-data/google-reviews-api)' place_id: type: string description: '*identifier of the business entity in Google Maps* **required field if you don’t specify `keyword` or `cid`** example: `GhIJQWDl0CIeQUARxks3icF8U8A` learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)**Note:** if you use this field, your account will be charged **two times the standard rate** for tasks involving the [Google Reviews API](https://dataforseo.com/pricing/business-data/google-reviews-api)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-reviews-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of reviews in SERP we strongly recommend setting the parsing depth in the multiples of twenty, because our systems processes twenty reviews in a row default value: `20` maximum value: `1000` **Your account will be billed per each SERP containing up to 20 results;** Setting depth above 20 may result in additional charges if the search engine returns more than 20 results; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-reviews-api "Pricing") page.' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - required: - keyword - required: - cid - required: - place_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/extended_reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/extended_reviews/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Extended Reviews Completed Tasks description: 'Lists finished the full Google review history for a business, past the first page the standard endpoint returns tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_google_extended_reviews_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.se_type: type: string description: '*type of search engine*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/extended_reviews/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_info/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Hotel Info Advanced description: 'One hotel''s Google listing: rooms, amenities, prices and the booking options Google shows. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The raw form is `post_dataforseo_business_google_hotel_info_live_html`, and the queued form `post_dataforseo_business_google_hotel_info_submit`. To find the hotel first use `post_dataforseo_business_google_hotel_searches_live`.' operationId: post_dataforseo_business_google_hotel_info_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.hotel_identifier: type: string description: '*identifier received in a POST array* this field will contain the `hotel_identifier` parameter specified when setting a task; example: `CgoI-KWyzenM_MV3EAE`' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.title: type: string description: '*title of the price offer*' result.stars: type: integer description: '*hotel class rating* class rating that ranges between 1-5 stars and displayed after review ratings in hotel summary' result.stars_description: type: string description: '*hotel class rating* class rating that ranges between 1-5 stars and displayed after review ratings in the hotel summary' result.address: type: string description: '*hotel address* physical address of the hotel' result.phone: type: string description: '*hotel phone number* contact phone number of the hotel' result.about: type: object description: '*information about the hotel*' result.description: type: string description: '*description of the hotel* the description of the hotel entity for which the results are collected' result.sub_descriptions: type: array items: type: string description: '*additional description of the hotel* details about the hotel provided in addition to the description' result.check_in_time: type: object description: '*hotel check-in time* check-in time indicated in the hotel listing' result.hour: type: integer description: '*check-out hour*' result.minute: type: integer description: '*check-out minute*' result.check_out_time: type: object description: '*hotel check-out time* check-out time indicated in the hotel listing' result.full_address: type: string description: '*full address of the hotel* address of the hotel indicated in the standardised format' result.domain: type: string description: '*third-party domain* domain of the third-party website page with pricing information' result.url: type: string description: '*url of the price offer* URL to the page of the website where price offer appears' result.amenities: type: array items: type: string description: '*hotel amenities* information about hotel amenities' result.category: type: string description: '*standardised category of the ammenity*' result.category_label: type: string description: '*label of the category*' result.items: type: array items: type: string description: '*array of items* array containing pricing details from third-party websites; possible item types: `hotel_info_price`' result.amenity: type: string description: '*standardised amenity name*' result.amenity_label: type: string description: '*displayed amenity name*' result.hint: type: string description: '*standardised details about the amenity*' result.hint_label: type: string description: '*displayed details about the amenity*' result.is_available: type: boolean description: '*indicates whether the `amenity` is available in the hotel*' result.popular_amenities: type: array items: type: string description: '*hotel amenities* information about hotel amenities labelled as “popular”' result.location: type: object description: '*information about the hotel location* information about the location where the hotel is located' result.neighborhood: type: string description: '*name of the neighborhood where the hotel is located*' result.neighborhood_description: type: string description: '*description of the neighborhood where the hotel is located*' result.maps_url: type: string description: '*url to the location of the hotel in google maps*' result.overall_score: type: number description: '*overall score of the hotel location* indicates the overall score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby things to do and restaurants, transportation, and airports; note that the criteria are not weighted equally in the overall score' result.score_by_categories: type: object description: '*category scores of the hotel location* the scores of the hotel’s location tied to the categories that indicate the proximity to nearby things to do, restaurants, transportation, and airports;' result.overall: type: number description: '*overall score of the hotel location* indicates the overall score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby things to do and restaurants, transportation, and airports; note that the criteria are not weighted equally in the overall score' result.things_to_do: type: number description: '*score relative to nearby things to do* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby things to do' result.restaurants: type: number description: '*score relative to nearby restaurants* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby restaurants' result.transit: type: number description: '*score relative to nearby transit options* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby transit options' result.airport_access: type: number description: '*score relative to nearby airports* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby airports' result.latitude: type: number description: '*hotel latitude* latitude coordinates of the hotel’s location example: `39.4806397`' result.longitude: type: number description: '*hotel longitude* latitude coordinates of the hotel’s location example: `-106.0512973`' result.location_chain: type: array items: type: string description: '*elements of the location chain* additional parameters of each element of the location chain' result.card_id: type: string description: '*card identifier*' result.feature_id: type: string description: '*feature identifier* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.cid: type: string description: '*client id* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.reviews: type: object description: '*hotel reviews by criteria* information about reviews of the hotel entity' result.value: type: number description: '*rating value* value of the rating enclosed in the review possible values: `CustomMax` – value in the range from 1 to 10 `Max5` – value in the range from 1 to 5' result.votes_count: type: integer description: '*votes count* the number of votes enclosed in the review' result.mentions: type: array items: type: string description: '*hotel mentions* information about hotel reviews by criteria' result.positive_score: type: number description: '*positive score by criterion*' result.positive_count: type: integer description: '*count of positive reviews by criterion*' result.negative_count: type: integer description: '*count of negative reviews by criterion*' result.total_count: type: integer description: '*count of all reviews by criterion*' result.visible_by_default: type: boolean description: '*element is visible by default* indicates whether the review element is visible by default' result.rating_distribution: type: object description: '*rating distribution by votes* the distribution of votes across the rating in the range from 1 to 5' result.5: type: integer description: '*votes for the 5-points rating*' result.4: type: integer description: '*votes for the 4-points rating*' result.3: type: integer description: '*votes for the 3-points rating*' result.2: type: integer description: '*votes for the 2-points rating*' result.1: type: integer description: '*votes for the 1-point rating*' result.other_sites_reviews: type: array items: type: string description: '*reviews on third-party sites* reviews from third-paty sites' result.review_text: type: string description: '*review text* text of the review' result.rating: type: object description: '*rating in the review* information about the rating enclosed in the review on a third-party site' result.rating_type: type: string description: '*rating type* the type of rating enclosed in the review possible values: `CustomMax`, `Max5`' result.rating_max: type: integer description: '*maximal value of the rating* the maximal value for the `rating_type`' result.overview_images: type: array items: type: string description: '*images displayed in the hotel overview* array containing URLs to images displayed in the hotel overview' result.prices: type: object description: '*pricing details of the hotel entity* contains information about the hotel’s prices' result.price: type: integer description: '*price per night* the price per night for staying at the hotel on a specific date' result.price_without_discount: type: integer description: '*price without discount* the price of the stay in the hotel per night, with no discount applied' result.currency: type: string description: '*price currency* example: `USD`' result.discount_text: type: string description: '*text of the discount*' result.check_in: type: string description: '*check-in date and tine* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.check_out: type: string description: '*check-out date and tine* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.visitors: type: integer description: '*number of visitors*' result.type: type: string description: '*type = **‘hotel\_info\_price\_offer’***' result.is_paid: type: boolean description: '*indicates a paid booking link* if `true`, related `hotel_info_price` item is a hotel ad if `false`, related `hotel_info_price` item is a free booking link' result.free_cancellation_until: type: string description: '*date until free cancellation is available* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” equals `null` if free cancellation is not available for the selected dates' result.offers: type: array items: type: string description: '*featured price offers*' result.max_visitors: type: integer description: '*the maximal number of visitors* the maximum number of visitors for which the price offer is valid' result.offer_images: type: array items: type: string description: '*price offer images* URLs of the images featured in the price offer' result.prices_by_dates: type: array items: type: string description: '*array of objects with hotel stay prices by dates*' result.check_in_date: type: string description: '*check-in date* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2025-05-20 12:00:00 +00:00`' result.check_out_date: type: string description: '*check-out date* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2025-05-21 12:00:00 +00:00`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: hotel_identifier: type: string description: '*unique hotel identifier* **required field** unique identifier of a hotel entity in Google search; you can obtain the value by making a request to Advanced [Google SERP API](https://docs.dataforseo.com/v3/serp/google/organic/overview.md) (enclosed in the `hotels` element of the response), or the [Hotel Searches endpoint](https://docs.dataforseo.com/v3/business_data/google/hotel_searches/task_post.md) of Business Data API example: `ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE`' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code` or `location_coordinate`** **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name` or `location_coordinate`** **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify `location_name` or `location_code`** **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude, longitude”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 **Note**: if the coordinates are used to set a location, the search will occur in the nearest settlement; example: `53.476225,-2.243572`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify `language_code`** **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify `language_name`** **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' check_in: type: string description: '*check-in date* optional field if you don’t specify this field, tomorrow’s date will be used by default; the value must not be earlier than today’s date date format: `"yyyy-mm-dd"` example: `"2019-01-15"`' check_out: type: string description: '*check-out date* optional field if you don’t specify this field, our system will apply the date of two days from now by default; **Note:** the value cannot be less than or equal to `check_in`; the range between `check_in` and `check_out` values cannot exceed 30 days date format: `"yyyy-mm-dd"` example: `"2019-01-15"`' currency: type: string description: '*currency* optional field example: `"USD"`' adults: type: integer description: '*number of adults* optional field if you don’t specify this field, two adults will be used by default example: `1`' children: type: array items: type: integer description: '*number and age of children* optional field if you don’t specify this field, no children will be included in the search; set the following value if you want to include one 14-years-old child: `[14]` set the following value if you want to include one 13-years-old child and one 8-years-old child: `[13,8]`' load_prices_by_dates: type: boolean description: '*load hotel stay prices by dates* optional field if you specify this parameter with `true`, the response will include the `prices_by_dates` array with hotel stay prices divided by dates if you use this parameter, you will be charged **double the base price for a request**' prices_start_date: type: string description: '*start date to load prices by dates* optional field to use this parameter, you must specify `load_prices_by_dates` with `true` if this parameter is not specified, the start date is set to `check_in` date date format: `yyyy-mm-dd` example: `2025-05-20`' prices_end_date: type: string description: '*end date to load prices by dates* optional field to use this parameter, you must specify `load_prices_by_dates` with `true` if this parameter is not specified, you will get prices by date for the month date format: `yyyy-mm-dd` example: `2025-05-21`' prices_date_range: type: string description: '*predefined period for retrieving daily price data* optional field to use this parameter, you must specify `load_prices_by_dates` with `true` if the `prices_start_date `is not specified, the start date is set to `check_in` date possible values: `month`, `three_months`, `six_months`, `year` default value: `month`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' required: - hotel_identifier allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_info/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_info/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Hotel Info HTML description: 'The same hotel listing as `post_dataforseo_business_google_hotel_info_live`, returned as raw HTML. ⚠️ Store-page HTML in this provider measured 2.6 MB against 83 KB parsed on the merchant family; assume the same order here and take it only to check what the parser dropped. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_business_google_hotel_info_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: array items: type: string description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*unique hotel identifier specified as `"hotel_id:$"`*' result.type: type: string description: '*type of search results* in this case, `"hotel_info"`' result.se_domain: type: string description: '*search engine domain in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.items_count: type: integer description: '*the number of results returned in the **`items`** array*' items: type: array items: type: string description: '*HTML pages*' items.page: type: integer description: '*serial number of the returned HTML page*' items.date: type: string description: '*date and time when the HTML page was scanned* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.html: type: string description: '*HTML page*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: hotel_identifier: type: string description: '*unique hotel identifier* **required field** unique identifier of a hotel entity in Google search; you can obtain the value by making a request to Advanced [Google SERP API](https://docs.dataforseo.com/v3/serp/google/organic/overview.md) (enclosed in the `hotels` element of the response), or the [Hotel Searches endpoint](https://docs.dataforseo.com/v3/business_data/google/hotel_searches/task_post.md) of Business Data API example: `ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE`' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-hotels-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code` or `location_coordinate`** **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name` or `location_coordinate`** **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify `location_name` or `location_code`** **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 **Note**: if the coordinates are used to set a location, the search will occur in the nearest settlement; example: `53.476225,-2.243572`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify `language_code`** **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify `language_name`** **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' check_in: type: string description: '*check-in date* optional field if you don’t specify this field, tomorrow’s date will be used by default; date format: `"yyyy-mm-dd"` example: `"2019-01-15"`' check_out: type: string description: '*check-out date* optional field if you don’t specify this field, our system will apply the date of two days from now by default; date format: `"yyyy-mm-dd"` example: `"2019-01-15"`' currency: type: string description: '*currency* optional field example: `"USD"`' adults: type: integer description: '*number of adults* optional field if you don’t specify this field, two adults will be used by default example: `1`' children: type: array items: type: integer description: '*number and age of children* optional field if you don’t specify this field, no children will be included in the search; set the following value if you want to include one 14-years-old child: `[14]` set the following value if you want to include one 13-years-old child and one 8-years-old child: `[13,8]`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` array of the response' required: - hotel_identifier allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_info/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_info/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Advanced Google Hotel Info Results by id description: 'Retrieves a queued hotel listing by `id`, parsed. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_business_google_hotel_info_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.hotel_identifier: type: string description: '*unique hotel identifier* this field will contain the `hotel_identifier` parameter; example: `CgoI-KWyzenM_MV3EAE`' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.title: type: string description: '*title of the price offer*' result.stars: type: integer description: '*hotel class rating* class rating that ranges between 1-5 stars and displayed after review ratings in hotel summary' result.stars_description: type: string description: '*hotel class rating* class rating that ranges between 1-5 stars and displayed after review ratings in the hotel summary' result.address: type: string description: '*hotel address* physical address of the hotel' result.phone: type: string description: '*hotel phone number* contact phone number of the hotel' result.about: type: object description: '*information about the hotel*' result.description: type: string description: '*description of the hotel* the description of the hotel entity for which the results are collected' result.sub_descriptions: type: array items: type: string description: '*additional description of the hotel* details about the hotel provided in addition to the description' result.check_in_time: type: object description: '*hotel check-in time* check-in time indicated in the hotel listing' result.hour: type: integer description: '*check-out hour*' result.minute: type: integer description: '*check-out minute*' result.check_out_time: type: object description: '*hotel check-out time* check-out time indicated in the hotel listing' result.full_address: type: string description: '*full address of the hotel* address of the hotel indicated in the standardised format' result.domain: type: string description: '*third-party domain* domain of the third-party website page with pricing information' result.url: type: string description: '*url of the price offer* URL to the page of the website where price offer appears' result.amenities: type: array items: type: string description: '*hotel amenities* information about hotel amenities' result.category: type: string description: '*standardised category of the ammenity*' result.category_label: type: string description: '*label of the category*' result.items: type: array items: type: string description: '*array of items* array containing pricing details from third-party websites; possible item types: `hotel_info_price`' result.amenity: type: string description: '*standardised amenity name*' result.amenity_label: type: string description: '*displayed amenity name*' result.hint: type: string description: '*standardised details about the amenity*' result.hint_label: type: string description: '*displayed details about the amenity*' result.is_available: type: boolean description: '*indicates whether the `amenity` is available in the hotel*' result.popular_amenities: type: array items: type: string description: '*hotel amenities* information about hotel amenities labelled as “popular”' result.location: type: object description: '*information about the hotel location* information about the location where the hotel is located' result.neighborhood: type: string description: '*name of the neighborhood where the hotel is located*' result.neighborhood_description: type: string description: '*description of the neighborhood where the hotel is located*' result.maps_url: type: string description: '*url to the location of the hotel in google maps*' result.overall_score: type: number description: '*overall score of the hotel location* indicates the overall score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby things to do and restaurants, transportation, and airports; note that the criteria are not weighted equally in the overall score' result.score_by_categories: type: object description: '*category scores of the hotel location* the scores of the hotel’s location tied to the categories that indicate the proximity to nearby things to do, restaurants, transportation, and airports;' result.overall: type: number description: '*overall score of the hotel location* indicates the overall score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby things to do and restaurants, transportation, and airports; note that the criteria are not weighted equally in the overall score' result.things_to_do: type: number description: '*score relative to nearby things to do* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby things to do' result.restaurants: type: number description: '*score relative to nearby restaurants* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby restaurants' result.transit: type: number description: '*score relative to nearby transit options* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby transit options' result.airport_access: type: number description: '*score relative to nearby airports* indicates the score of the hotel’s location in the range from 1 to 5; calculated based on data from the hotel’s proximity to nearby airports' result.latitude: type: number description: '*hotel latitude* latitude coordinates of the hotel’s location example: `39.4806397`' result.longitude: type: number description: '*hotel longitude* latitude coordinates of the hotel’s location example: `-106.0512973`' result.location_chain: type: array items: type: string description: '*elements of the location chain* additional parameters of each element of the location chain' result.card_id: type: string description: '*card identifier*' result.feature_id: type: string description: '*feature identifier* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.cid: type: string description: '*client id* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.reviews: type: object description: '*hotel reviews by criteria* information about reviews of the hotel entity' result.value: type: number description: '*rating value* value of the rating enclosed in the review possible values: `CustomMax` – value in the range from 1 to 10 `Max5` – value in the range from 1 to 5' result.votes_count: type: integer description: '*votes count* the number of votes enclosed in the review' result.mentions: type: array items: type: string description: '*hotel mentions* information about hotel reviews by criteria' result.positive_score: type: number description: '*positive score by criterion*' result.positive_count: type: integer description: '*count of positive reviews by criterion*' result.negative_count: type: integer description: '*count of negative reviews by criterion*' result.total_count: type: integer description: '*count of all reviews by criterion*' result.visible_by_default: type: boolean description: '*element is visible by default* indicates whether the review element is visible by default' result.rating_distribution: type: object description: '*rating distribution by votes* the distribution of votes across the rating in the range from 1 to 5' result.5: type: integer description: '*votes for the 5-points rating*' result.4: type: integer description: '*votes for the 4-points rating*' result.3: type: integer description: '*votes for the 3-points rating*' result.2: type: integer description: '*votes for the 2-points rating*' result.1: type: integer description: '*votes for the 1-point rating*' result.other_sites_reviews: type: array items: type: string description: '*reviews on third-party sites* reviews from third-paty sites' result.review_text: type: string description: '*review text* text of the review' result.rating: type: object description: '*rating in the review* information about the rating enclosed in the review on a third-party site' result.rating_type: type: string description: '*rating type* the type of rating enclosed in the review possible values: `CustomMax`, `Max5`' result.rating_max: type: integer description: '*maximal value of the rating* the maximal value for the `rating_type`' result.overview_images: type: array items: type: string description: '*images displayed in the hotel overview* array containing URLs to images displayed in the hotel overview' result.prices: type: object description: '*pricing details of the hotel entity* contains information about the hotel’s prices' result.price: type: integer description: '*price per night* the price per night for staying at the hotel on a specific date' result.price_without_discount: type: integer description: '*price without discount* the price of the stay in the hotel per night, with no discount applied' result.currency: type: string description: '*price currency* example: `USD`' result.discount_text: type: string description: '*text of the discount*' result.check_in: type: string description: '*check-in date and tine* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.check_out: type: string description: '*check-out date and tine* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.visitors: type: integer description: '*number of visitors*' result.type: type: string description: '*type = **‘hotel\_info\_price\_offer’***' result.is_paid: type: boolean description: '*indicates a paid booking link* if `true`, related `hotel_info_price` item is a hotel ad if `false`, related `hotel_info_price` item is a free booking link' result.free_cancellation_until: type: string description: '*date until free cancellation is available* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” equals `null` if free cancellation is not available for the selected dates' result.offers: type: array items: type: string description: '*featured price offers*' result.max_visitors: type: integer description: '*the maximal number of visitors* the maximum number of visitors for which the price offer is valid' result.offer_images: type: array items: type: string description: '*price offer images* URLs of the images featured in the price offer' result.prices_by_dates: type: array items: type: string description: '*array of objects with hotel stay prices by dates*' result.check_in_date: type: string description: '*check-in date* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2025-05-20 12:00:00 +00:00`' result.check_out_date: type: string description: '*check-out date* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2025-05-21 12:00:00 +00:00`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_info/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_info/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Advanced Google Hotel Info Results by id description: 'Retrieves a queued hotel listing by `id` as raw HTML. ⚠️ Far larger than the parsed twin `get_dataforseo_business_google_hotel_info_fetch`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_business_google_hotel_info_fetch_html parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.result_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.hotel_identifier: type: string description: '*identifier received in a POST array* this field will contain the `hotel_identifier` parameter specified when setting a task; example: `CgoI-KWyzenM_MV3EAE`' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.items_count: type: integer description: '*the number of results returned in the **`items`** array*' items: type: array items: type: string description: '*HTML pages*' items.page: type: integer description: '*serial number of the returned HTML page*' items.date: type: string description: '*date and time when the HTML page was scanned* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.html: type: string description: '*HTML page*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_info/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0016 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Hotel Info Tasks description: 'Queues a hotel listing lookup, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve parsed with `get_dataforseo_business_google_hotel_info_fetch` or raw with `get_dataforseo_business_google_hotel_info_fetch_html`.' operationId: post_dataforseo_business_google_hotel_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: hotel_identifier: type: string description: '*unique hotel identifier* **required field if you don’t specify `keyword`** **if you use this field, you don’t need to specify `keyword`** unique identifier of a hotel entity in Google search; you can obtain the value by making a request to Advanced [Google SERP API](https://docs.dataforseo.com/v3/serp/google/organic/overview.md) (enclosed in the `hotels_pack` element of the response), or the [Hotel Searches endpoint](https://docs.dataforseo.com/v3/business_data/google/hotel_searches/task_post.md) of Business Data API example: `ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE`' keyword: type: string description: '*keyword* **required field if you don’t specify `hotel_identifier`** **if you use this field, you don’t need to specify `hotel_identifier`** the keyword you specify should indicate the name of the hotel entity you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-hotels-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code` or `location_coordinate`** **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name` or `location_coordinate`** **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify `location_name` or `location_code`** **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 **Note**: if the coordinates are used to set a location, the search will occur in the nearest settlement; example: `53.476225,-2.243572`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify `language_code`** **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify `language_name`** **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' check_in: type: string description: '*check-in date* optional field if you don’t specify this field, tomorrow’s date will be used by default; the value must not be earlier than today’s date date format: `"yyyy-mm-dd"` example: `"2019-01-15"`' check_out: type: string description: '*check-out date* optional field if you don’t specify this field, our system will apply the date of two days from now by default; **Note:** the value cannot be less than or equal to `check_in`; the range between `check_in` and `check_out` values cannot exceed 30 days date format: `"yyyy-mm-dd"` example: `"2019-01-15"`' currency: type: string description: '*currency* optional field example: `"USD"`' adults: type: integer description: '*number of adults* optional field if you don’t specify this field, two adults will be used by default example: `1`' children: type: array items: type: integer description: '*number and age of children* optional field if you don’t specify this field, no children will be included in the search; set the following value if you want to include one 14-years-old child: `[14]` set the following value if you want to include one 13-years-old child and one 8-years-old child: `[13,8]`' load_prices_by_dates: type: boolean description: '*load hotel stay prices by dates* optional field if you specify this parameter with `true`, the response will include the `prices_by_dates` array with hotel stay prices divided by dates if you use this parameter, you will be charged **double the base price for a request**' prices_start_date: type: string description: '*start date to load prices by dates* optional field to use this parameter, you must specify `load_prices_by_dates` with `true` if this parameter is not specified, the start date is set to `check_in` date date format: `yyyy-mm-dd` example: `2025-05-20`' prices_end_date: type: string description: '*end date to load prices by dates* optional field to use this parameter, you must specify `load_prices_by_dates` with `true` if this parameter is not specified, you will get prices by date for the month date format: `yyyy-mm-dd` example: `2025-05-21`' prices_date_range: type: string description: '*predefined period for retrieving daily price data* optional field to use this parameter, you must specify `load_prices_by_dates` with `true` if the `prices_start_date `is not specified, the start date is set to `check_in` date possible values: `month`, `three_months`, `six_months`, `year` default value: `month`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255;* you can use this parameter to identify the task and match it with the result; you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified; you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request; example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' postback_data: type: string description: '*postback\_url datatype* **required field if you specify `postback_url`** corresponds to the datatype that will be sent to your server possible values: `advanced`, `html`' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified; you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable; we will set the necessary values before sending the request; example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - required: - hotel_identifier - required: - keyword - anyOf: - not: required: - postback_url - required: - postback_data tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_info/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Hotel Info Completed Tasks description: 'Lists finished hotel listing tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely the tool you want: a caller holds the `id` its own submit returned and can fetch that directly. This answers what is ready across the whole account, which is a different question, and it returns an empty result with status 20000 when nothing is - an empty queue, not an error.' operationId: get_dataforseo_business_google_hotel_info_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.se_type: type: string description: '*search engine specified when setting the task*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_info/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_searches/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Hotel Searches Tasks description: 'Searches Google Hotels for properties matching a query, with dates and occupancy. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. This is how to find the hotel whose `id` the info endpoints need; `post_dataforseo_business_google_hotel_info_live` is the detail view.' operationId: post_dataforseo_business_google_hotel_searches_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)**' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.items_count: type: integer description: '*item types* the number of items in the `items` array' items: type: array items: type: string description: '*encountered item types* types of search engine results encountered in the `items` array; possible item types: `hotel_search_item`' items.type: type: string description: '*type of element = **‘hotel\_search\_item’***' items.hotel_identifier: type: string description: '*unique identifier of a hotel entity in Google search* example: `CgoI-KWyzenM_MV3EAE`' items.title: type: string description: '*title of the hotel*' items.stars: type: integer description: '*hotel class rating* class rating that ranges between 1-5 stars' items.is_paid: type: boolean description: '*indicates a paid hotel listing* if `true`, related `hotel_search_item` is a paid ad if `false`, related `hotel_search_item` is an organic hotel listing' items.location: type: object description: '*GPS coordinates of the hotel’s location*' items.latitude: type: number description: '*latitude coordinate of the hotel in google maps* example: `"latitude": 51.584091`' items.longitude: type: number description: '*longitude coordinate of the hotel in google maps* example: `"longitude": -0.31365919999999997`' items.reviews: type: object description: '*hotel reviews and rating information*' items.value: type: number description: '*the average rating based on all reviews*' items.votes_count: type: integer description: '*the number of votes*' items.mentions: type: array items: type: string description: '*hotel mentions* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' items.rating_distribution: type: object description: '*rating distribution by votes* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' items.other_sites_reviews: type: array items: type: string description: '*reviews on third-party sites* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' items.overview_images: type: array items: type: string description: '*featured images for a hotel*' items.prices: type: object description: '*hotel price*' items.price: type: integer description: '*price per night*' items.price_without_discount: type: integer description: '*full price per night without a discount applied*' items.currency: type: string description: '*price currency* `USD` is applied by default, unless specified in the POST array' items.discount_text: type: string description: '*text about a discount applied*' items.check_in: type: string description: '*check-in date and time* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.check_out: type: string description: '*check-out date and time* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.visitors: type: integer description: '*number of hotel visitors for this price*' items.items: type: array items: type: string description: '*array of items* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* optional field the keyword you specify is used to search for the list of hotels; if you don’t use this field, we will return the list of hotels found in a specified location; you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”; **Note:** in order to obtain accurate search results, the location name is appended to the keyword automatically learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code` or `location_coordinate`** **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom` **Note:** in order to obtain accurate search results, the `location_name` you specify will be automatically appended to the keyword' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name` or `location_coordinate`** **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify `location_name` or `location_code`** **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 **Note**: if the coordinates are used to set a location, the search will occur in the nearest settlement example: `53.476225,-2.243572`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify `language_code`** **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify `language_name`** **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of results in Google Hotels default value: `20` organic results max value: `140` **Note:** your account will be billed per each 20 organic results regardless of paid listings in the response; thus, setting a depth above `20` may result in additional charges if Google Hotels return more than 20 results; if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance' check_in: type: string description: '*check-in date* optional field if you don’t specify this field, tomorrow’s date will be used by default; date format: `"yyyy-mm-dd"` example: `"2019-01-15"` **Note:** the value cannot precede the today’s date' check_out: type: string description: '*check-out date* optional field if you don’t specify this field, our system will apply the date of two days from now by default; date format: `"yyyy-mm-dd"` example: `"2019-01-15"` **Note:** the value cannot be less than or equal to `check_in`; the range between `check_in` and `check_out` values cannot exceed 30 days' currency: type: string description: '*currency* optional field example: `"USD"`' adults: type: integer description: '*number of adults* optional field if you don’t specify this field, the default value of `2` will be applied; **note** that you can specify up to 6 persons including both adults and children example: `1`' children: type: array items: type: integer description: '*number and age of children* optional field if you don’t specify this field, no children will be included in the search; age of child can be from `0` to `17`; **note** that you can specify up to 6 persons including both adults and children set the following value if you want to include one 14-year-old child: `[14]` set the following value if you want to include one 13-year-old child and one 8-year-old child: `[13,8]`' stars: type: array items: type: integer description: '*hotel stars* optional field set this field to `[5]` if you want to get the list of 5-star hotels only example: `[3,4,5]`' min_rating: type: number description: '*minimum rating* optional field you can use this field to specify guest rating higher than a certain value example: `2.5`' sort_by: type: string description: '*results sorting parameters* optional field you can use this field to sort the results possible types of sorting: `relevance` – sort by most relevant `lowest_price` – sort by the lowest price `highest_rating` – sort by highest rating `most_reviewed` – sort by most reviewed default value: `relevance`' min_price: type: integer description: '*minimum price per night* optional field the currency of this value depends on the `currency` field example: `100`' max_price: type: integer description: '*maximum price per night* optional field the currency of this value depends on the `currency` field example: `600`' free_cancellation: type: boolean description: '*hotels with a free cancellation* optional field set this field to `true` if you want to get the list of hotels with free cancellation of reservations default value: `false`' is_vacation_rentals: type: boolean description: '*search for vacation rentals* optional field set this field to `true` if you want to get the list of vacation rentals instead of hotels default value: `false`' amenities: type: array items: type: string description: '*hotel amenities* optional field you can use this field to specify different hotel amenities example: ` [ "free_parking", "pets_allowed" ]` possible values: `"air_conditioning","all_inclusive_available","bar","free_breakfast","fitness_center","kid_friendly","free_parking","pets_allowed","pool","restaurant","room_service","spa","free_wifi","parking","indoor_pool","outdoor_pool","wheelchair_accessible","beach_access"`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_searches/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_searches/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Hotel Searches Results by id description: 'Retrieves a queued Google Hotels search by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_business_google_hotel_searches_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character); in order to obtain accurate search results, the location name is appended to the keyword automatically' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.items_count: type: integer description: '*item types* the number of items in the `items` array' items: type: array items: type: string description: '*encountered item types* types of search engine results encountered in the `items` array; possible item types: `hotel_search_item`' items.type: type: string description: '*type of element = **‘hotel\_search\_item’***' items.hotel_identifier: type: string description: '*unique identifier of a hotel entity in Google search* example: `CgoI-KWyzenM_MV3EAE`' items.title: type: string description: '*title of the hotel*' items.stars: type: integer description: '*hotel class rating* class rating that ranges between 1-5 stars' items.is_paid: type: boolean description: '*indicates a paid hotel listing* if `true`, related `hotel_search_item` is a paid ad if `false`, related `hotel_search_item` is an organic hotel listing' items.location: type: object description: '*GPS coordinates of the hotel’s location*' items.latitude: type: number description: '*latitude coordinate of the hotel in google maps* example: `"latitude": 51.584091`' items.longitude: type: number description: '*longitude coordinate of the hotel in google maps* example: `"longitude": -0.31365919999999997`' items.reviews: type: object description: '*hotel reviews and rating information*' items.value: type: number description: '*the average rating based on all reviews*' items.votes_count: type: integer description: '*the number of votes*' items.mentions: type: array items: type: string description: '*hotel mentions* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' items.rating_distribution: type: object description: '*rating distribution by votes* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' items.other_sites_reviews: type: array items: type: string description: '*reviews on third-party sites* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' items.overview_images: type: array items: type: string description: '*featured images for a hotel*' items.prices: type: object description: '*hotel price*' items.price: type: integer description: '*price per night*' items.price_without_discount: type: integer description: '*full price per night without a discount applied*' items.currency: type: string description: '*price currency* `USD` is applied by default, unless specified in the POST array' items.discount_text: type: string description: '*text about a discount applied*' items.check_in: type: string description: '*check-in date and time* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.check_out: type: string description: '*check-out date and time* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.visitors: type: integer description: '*number of hotel visitors for this price*' items.items: type: array items: type: string description: '*array of items* **note:** this field always equals `null`; use it to facilitate integration and ensure interoperability with the [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) endpoint' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_searches/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_searches/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0016 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Hotel Searches Tasks description: 'Queues a Google Hotels search, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_google_hotel_searches_fetch`.' operationId: post_dataforseo_business_google_hotel_searches_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* optional field the keyword you specify is used to search for the list of hotels; if you don’t use this field, we will return the list of hotels found in a specified location; you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”; **Note:** in order to obtain accurate search results, the location name is appended to the keyword automatically learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-hotels-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code` or `location_coordinate`** **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom` **Note:** in order to obtain accurate search results, the `location_name` you specify will be automatically appended to the keyword' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name` or `location_coordinate`** **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify `location_name` or `location_code`** **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 **Note**: if the coordinates are used to set a location, the search will occur in the nearest settlement; example: `53.476225,-2.243572`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify `language_code`** **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify `language_name`** **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of results in Google Hotels default value: `20` organic results max value: `140` **Note:** your account will be billed per each 20 organic results regardless of paid listings in the response; thus, setting a depth above `20` may result in additional charges if Google Hotels return more than 20 results; if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance' check_in: type: string description: '*check-in date* optional field if you don’t specify this field, tomorrow’s date will be used by default; date format: `"yyyy-mm-dd"` example: `"2019-01-15"` **Note:** the value cannot precede the today’s date' check_out: type: string description: '*check-out date* optional field if you don’t specify this field, our system will apply the date of two days from now by default; date format: `"yyyy-mm-dd"` example: `"2019-01-15"` **Note:** the value cannot be less than or equal to `check_in`; the range between `check_in` and `check_out` values cannot exceed 30 days' currency: type: string description: '*currency* optional field example: `"USD"`' adults: type: integer description: '*number of adults* optional field if you don’t specify this field, the default value of `2` will be applied; **note** that you can specify up to 6 persons including both adults and children example: `1`' children: type: array items: type: integer description: '*number and age of children* optional field if you don’t specify this field, no children will be included in the search; age of child can be from `0` to `17`; **note** that you can specify up to 6 persons including both adults and children set the following value if you want to include one 14-year-old child: `[14]` set the following value if you want to include one 13-year-old child and one 8-year-old child: `[13,8]`' stars: type: array items: type: integer description: '*hotel stars* optional field set this field to `[5]` if you want to get the list of 5-star hotels only example: `[3,4,5]`' min_rating: type: number description: '*minimum rating* optional field you can use this field to specify guest rating higher than a certain value example: `2.5`' sort_by: type: string description: '*results sorting parameters* optional field you can use this field to sort the results possible types of sorting: `relevance` – sort by most relevant `lowest_price` – sort by the lowest price `highest_rating` – sort by highest rating `most_reviewed` – sort by most reviewed default value: `relevance`' min_price: type: integer description: '*minimum price per night* optional field the currency of this value depends on the `currency` field example: `100`' max_price: type: integer description: '*maximum price per night* optional field the currency of this value depends on the `currency` field example: `600`' free_cancellation: type: boolean description: '*hotels with a free cancellation* optional field set this field to `true` if you want to get the list of hotels with free cancellation of reservations default value: `false`' is_vacation_rentals: type: boolean description: '*search for vacation rentals* optional field set this field to `true` if you want to get the list of vacation rentals instead of hotels default value: `false`' amenities: type: array items: type: string description: '*hotel amenities* optional field you can use this field to specify different hotel amenities example: ` [ "free_parking", "pets_allowed" ]` possible values: `"air_conditioning","all_inclusive_available","bar","free_breakfast","fitness_center","kid_friendly","free_parking","pets_allowed","pool","restaurant","room_service","spa","free_wifi","parking","indoor_pool","outdoor_pool","wheelchair_accessible","beach_access"`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_searches/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/hotel_searches/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Hotel Searches Completed Tasks description: 'Lists finished Google Hotels search tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely the tool you want: a caller holds the `id` its own submit returned and can fetch that directly. This answers what is ready across the whole account, which is a different question, and it returns an empty result with status 20000 when nothing is - an empty queue, not an error.' operationId: get_dataforseo_business_google_hotel_searches_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.se_type: type: string description: '*search engine type*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/hotel_searches/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_info/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0108 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live Google My Business Info Tasks description: 'One Google Business Profile: name, address, phone, hours, rating, category and the attributes Google shows on the panel. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The queued twin is `post_dataforseo_business_google_gmb_info_submit`. For what the owner has posted recently use `post_dataforseo_business_google_gmb_updates_submit`, and for customer opinion `post_dataforseo_business_google_reviews_submit`.' operationId: post_dataforseo_business_google_gmb_info_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)** this field will contain the `cid` parameter if you specified it in the `keyword` field when setting a task; example: `cid:2946633002421908862` learn more about the parameter in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.se_domain: type: string description: '*search engine domain as specified in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.item_types: type: array items: type: string description: '*item types* types of search engine results encountered in the `items` array; possible item types: `google_business_info`' result.items_count: type: integer description: '*item types* the number of items in the `items` array' items: type: array items: type: string description: '*encountered item types* types of search engine results encountered in the `items` array; possible item types: `google_business_info`' items.type: type: string description: '*type of element = **‘google\_business\_info’***' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the elements*' items.position: type: string description: '*the alignment in SERP*' items.title: type: string description: '*title of the element in SERP* the name of the business entity for which the results are collected' items.original_title: type: string description: '*original title of the element* original title not translated by Google' items.description: type: string description: '*description of the element in SERP* the description of the business entity for which the results are collected' items.category: type: string description: '*business category* Google My Business general category that best describes the services provided by the business entity' items.category_ids: type: array items: type: string description: '*global category IDs* universal category IDs that do not change based on the selected country' items.additional_categories: type: array items: type: string description: '*additional business categories* additional Google My Business categories that describe the services provided by the business entity in more detail' items.cid: type: string description: '*google-defined client id* unique id of a local establishment learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.feature_id: type: string description: '*the unique identifier of the element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.address: type: string description: '*street address of the business entity*' items.address_info: type: object description: '*object containing address components of the business entity*' items.borough: type: string description: '*administrative unit or district the business entity location belongs to*' items.city: type: string description: '*name of the city where the business entity is located*' items.zip: type: string description: '*ZIP code of the business entity*' items.region: type: string description: '*DMA region of the business entity location*' items.country_code: type: string description: '*ISO country code of the business entity location*' items.place_id: type: string description: '*unique place identifier* [place id](https://developers.google.com/places/place-id) of the local establishment featured in the element learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.phone: type: string description: '*phone number of the business entity*' items.url: type: string description: '*absolute url of the business entity*' items.contact_url: type: string description: '*URL of the preferred contact page*' items.contributor_url: type: string description: '*URL of the user’s or entity’s Local Guides profile, if available*' items.book_online_url: type: string description: '*URL in the ‘book online’ button of the element* URL directing users to the online booking or order page of the business entity' items.domain: type: string description: '*domain of the business entity*' items.logo: type: string description: '*URL of the logo featured in Google My Business profile*' items.main_image: type: string description: '*URL of the main image featured in Google My Business profile*' items.total_photos: type: integer description: '*total count of images featured in Google My Business profile*' items.snippet: type: string description: '*additional information on the business entity*' items.latitude: type: number description: '*latitude coordinate of the local establishments in google maps* example: `"latitude": 51.584091`' items.longitude: type: number description: '*longitude coordinate of the local establishment in google maps* example: `"longitude": -0.31365919999999997`' items.is_claimed: type: boolean description: '*shows whether the entity is verified by its owner on Google Maps*' items.attributes: type: object description: '*service details in a form of user-reviewed checks;* service details of a business entity displayed in a form of checks and based on user feedback and business `category`' items.available_attributes: type: object description: '*available attributes* indicates attributes a business entity can offer' items.unavailable_attributes: type: object description: '*unavailable attributes* indicates attributes a business entity cannot offer' items.place_topics: type: object description: '*keywords mentioned in customer reviews* contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword example: `"place_topics": {"egg roll": 48,"birthday": 33}`' items.rating: type: object description: '*the element’s rating* the popularity rate based on reviews and displayed in SERP' items.rating_type: type: string description: '*the type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' items.value: type: integer description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback*' items.rating_max: type: integer description: '*the maximum value for a `rating_type`*' items.rating_distribution: type: object description: '*the distribution of ratings of the business entity* the object displays the number of 1-star to 5-star ratings, as reviewed by users' items.1: type: integer description: '*the number of 1-star ratings*' items.2: type: integer description: '*the number of 2-star ratings*' items.3: type: integer description: '*the number of 3-star ratings*' items.4: type: integer description: '*the number of 4-star ratings*' items.5: type: integer description: '*the number of 5-star ratings*' items.people_also_search: type: array items: type: string description: '*related business entities*' items.work_time: type: object description: '*work time details* information related to operational hours of the business entity' items.work_hours: type: object description: '*open hours* information about work hours of the local establishment' items.timetable: type: object description: '*work hours timetable*' items.sunday: type: array items: type: string description: '*work hours on Sundays*' items.open: type: object description: '*opening time*' items.hour: type: integer description: '*hours in the 24-hour format*' items.minute: type: integer description: '*minutes*' items.close: type: object description: '*closing time*' items.monday: type: array items: type: string description: '*work hours on Mondays*' items.tuesday: type: array items: type: string description: '*work hours on Tuesdays*' items.wednesday: type: array items: type: string description: '*work hours on Wednesdays*' items.thursday: type: array items: type: string description: '*work hours on Thursdays*' items.friday: type: array items: type: string description: '*work hours on Fridays*' items.saturday: type: array items: type: string description: '*work hours on Saturday*' items.current_status: type: string description: '*current status of the establishment* possible values: `opened`, `closed`, `temporarily_closed`, `closed_forever`' popular_times: type: object description: '*popular times* information related to busy hours of the business entity' popular_times.popular_times_by_days: type: object description: '*popular hours* information about busy hours of the local establishment on each day of the week' popular_times.sunday: type: array items: type: string description: '*busy hours on sunday* **can take values of the corresponding days of the week**' popular_times.time: type: object description: '*busy hours*' popular_times.hour: type: integer description: '*hours in a 24-hour format*' popular_times.minute: type: integer description: '*minutes*' popular_times.popular_index: type: integer description: '*popularity index* relative time-bound popularity index measured from `0` to `100`; higher value corresponds to a busier time of a day' local_business_links: type: array items: type: string description: '*available interactions with the business* list of options to interact with the business directly from search results' local_business_links.type: type: string description: '*type of element = **‘menu’***' local_business_links.title: type: string description: '*title of the element* domain of the online menu system' local_business_links.url: type: string description: '*URL to view the menu*' local_business_links.delivery_services: type: array items: type: string description: '*lists available delivery services*' local_business_links.is_directory_item: type: boolean description: '*business establishment is a part of the directory* indicates whether the business establishment is a part of the directory; if `true`, the item is a part of the larger directory of businesses with the same address (e.g., a mall or a business centre); **note:** if the business establishment is a parent item in the directory, the value will be `null`' directory: type: array items: type: string description: '*items of the directory* includes information about businesses that are located within the target business establishment and have the same address' directory.title: type: string description: '*title of the element in SERP* the name of the business entity' directory.items: type: array items: type: string description: '***array of directory items***' directory.type: type: string description: '*type of element = **‘maps\_search’***' directory.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from the `rank_group`' directory.rank_absolute: type: integer description: '*absolute rank among all the elements*' directory.domain: type: string description: '*domain of the business entity*' directory.url: type: string description: '*absolute url of the business entity*' directory.rating: type: object description: '*the element’s rating* the popularity rate based on reviews and displayed in SERP' directory.rating_type: type: string description: '*the type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' directory.value: type: integer description: '*the value of the rating*' directory.votes_count: type: integer description: '*the amount of feedback*' directory.rating_max: type: integer description: '*the maximum value for a `rating_type`*' directory.rating_distribution: type: object description: '*the distribution of ratings of the business entity* the object displays the number of 1-star to 5-star ratings, as reviewed by users' directory.1: type: integer description: '*the number of 1-star ratings*' directory.2: type: integer description: '*the number of 2-star ratings*' directory.3: type: integer description: '*the number of 3-star ratings*' directory.4: type: integer description: '*the number of 4-star ratings*' directory.5: type: integer description: '*the number of 5-star ratings*' directory.snippet: type: string description: '*additional information about the business entity*' directory.address: type: string description: '*street address of the business entity*' directory.address_info: type: object description: '*object containing address components of the business entity*' directory.borough: type: string description: '*administrative unit or district the business entity location belongs to*' directory.city: type: string description: '*name of the city where the business entity is located*' directory.zip: type: string description: '*ZIP code of the business entity*' directory.region: type: string description: '*DMA region of the business entity location*' directory.country_code: type: string description: '*ISO country code of the business entity location*' directory.place_id: type: string description: '*unique place identifier* [place id](https://developers.google.com/places/place-id) of the local establishment featured in the element learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' directory.phone: type: string description: '*phone number of the business entity*' directory.main_image: type: string description: '*URL of the main image featured in Google My Business profile*' directory.total_photos: type: integer description: '*total count of images featured in Google My Business profile*' directory.category: type: string description: '*business category* Google My Business general category that best describes the services provided by the business entity' directory.category_ids: type: array items: type: string description: '*global category IDs* universal category IDs that do not change based on the selected country' directory.work_hours: type: object description: '*work hours* information about work hours of the local establishment' directory.feature_id: type: string description: '*the unique identifier of the element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' directory.cid: type: string description: '*google-defined client id* unique id of a local establishment; can be used with [Google Reviews API](https://docs.dataforseo.com/v3/reviews/google/overview.md) to get a full list of reviews learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' directory.latitude: type: number description: '*latitude coordinate of the local establishments in google maps* example: `"latitude": 51.584091`' directory.longitude: type: number description: '*longitude coordinate of the local establishment in google maps* example: `"longitude": -0.31365919999999997`' directory.is_claimed: type: boolean description: '*shows whether the entity is verified by its owner on Google Maps*' directory.local_justifications: type: array items: type: string description: '*Google local justifications* snippets of text that “justify” why the business is showing up for search query' directory.is_directory_item: type: boolean description: '*business establishment is a part of the directory* indicates whether the business establishment is a part of the directory; if `true`, the item is a part of the larger directory of businesses with the same address (e.g., a mall or a business centre); **note:** if the business establishment is a parent item in the directory, the value will be `null`' directory.price_level: type: string description: '*property price level* can take values: `inexpensive`, `moderate`, `expensive`, `very_expensive` if there is no price level information, the value will be `null`' directory.hotel_rating: type: integer description: '*hotel class rating* class ratings range between 1-5 stars, [learn more](https://support.google.com/business/answer/7660515?hl=en) if there is no hotel class rating information, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate the name of the local establishment you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”; this field can also be used to pass the following parameters: `cid` – a unique, google-defined id of the business entity; `place_id` – an identifier of the business entity in Google Maps; `spp` – a unique identifier of local services featured in the `local_pack` element of Google SERP example: `cid:194604053573767737` `place_id:GhIJQWDl0CIeQUARxks3icF8U8A` `spp:CgsvZy8xdGN4cWRraBoUChIJPZDrEzLsZIgRoNrpodC5P30` learn more about the `cid` and `place_id` identifiers in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id) learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 (mm) the maximum value for *“radius”*: 199999 (mm) example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_info/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_info/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google My Business Info Results by id description: 'Retrieves a queued Google Business Profile lookup by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_business_google_gmb_info_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)** this field will contain the `cid` parameter if you specified it in the `keyword` field when setting a task; example: `cid:2946633002421908862` learn more about the parameter in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.se_domain: type: string description: '*search engine domain as specified in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.item_types: type: array items: type: string description: '*item types* types of search engine results encountered in the `items` array; possible item types: `google_business_info`' result.items_count: type: integer description: '*item types* the number of items in the `items` array' items: type: array items: type: string description: '*encountered item types* types of search engine results encountered in the `items` array; possible item types: `google_business_info`' items.type: type: string description: '*type of element = **‘google\_business\_info’***' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the elements*' items.position: type: string description: '*the alignment in SERP*' items.title: type: string description: '*title of the element in SERP* the name of the business entity for which the results are collected' items.original_title: type: string description: '*original title of the element* original title not translated by Google' items.description: type: string description: '*description of the element in SERP* the description of the business entity for which the results are collected' items.category: type: string description: '*business category* Google My Business general category that best describes the services provided by the business entity' items.category_ids: type: array items: type: string description: '*global category IDs* universal category IDs that do not change based on the selected country' items.additional_categories: type: array items: type: string description: '*additional business categories* additional Google My Business categories that describe the services provided by the business entity in more detail' items.cid: type: string description: '*google-defined client id* unique id of a local establishment learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.feature_id: type: string description: '*the unique identifier of the element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.address: type: string description: '*street address of the business entity*' items.address_info: type: object description: '*object containing address components of the business entity*' items.borough: type: string description: '*administrative unit or district the business entity location belongs to*' items.city: type: string description: '*name of the city where the business entity is located*' items.zip: type: string description: '*ZIP code of the business entity*' items.region: type: string description: '*DMA region of the business entity location*' items.country_code: type: string description: '*ISO country code of the business entity location*' items.place_id: type: string description: '*unique place identifier* [place id](https://developers.google.com/places/place-id) of the local establishment featured in the element learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' items.phone: type: string description: '*phone number of the business entity*' items.url: type: string description: '*absolute url of the business entity*' items.contact_url: type: string description: '*URL of the preferred contact page*' items.contributor_url: type: string description: '*URL of the user’s or entity’s Local Guides profile, if available*' items.book_online_url: type: string description: '*URL in the ‘book online’ button of the element* URL directing users to the online booking or order page of the business entity' items.domain: type: string description: '*domain of the business entity*' items.logo: type: string description: '*URL of the logo featured in Google My Business profile*' items.main_image: type: string description: '*URL of the main image featured in Google My Business profile*' items.total_photos: type: integer description: '*total count of images featured in Google My Business profile*' items.snippet: type: string description: '*additional information on the business entity*' items.latitude: type: number description: '*latitude coordinate of the local establishments in google maps* example: `"latitude": 51.584091`' items.longitude: type: number description: '*longitude coordinate of the local establishment in google maps* example: `"longitude": -0.31365919999999997`' items.is_claimed: type: boolean description: '*shows whether the entity is verified by its owner on Google Maps*' items.attributes: type: object description: '*service details in a form of user-reviewed checks;* service details of a business entity displayed in a form of checks and based on user feedback and business `category`' items.available_attributes: type: object description: '*available attributes* indicates attributes a business entity can offer' items.unavailable_attributes: type: object description: '*unavailable attributes* indicates attributes a business entity cannot offer' items.place_topics: type: object description: '*keywords mentioned in customer reviews* contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword example: `"place_topics": {"egg roll": 48,"birthday": 33}`' items.rating: type: object description: '*the element’s rating* the popularity rate based on reviews and displayed in SERP' items.rating_type: type: string description: '*the type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' items.value: type: integer description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback*' items.rating_max: type: integer description: '*the maximum value for a `rating_type`*' items.rating_distribution: type: object description: '*the distribution of ratings of the business entity* the object displays the number of 1-star to 5-star ratings, as reviewed by users' items.1: type: integer description: '*the number of 1-star ratings*' items.2: type: integer description: '*the number of 2-star ratings*' items.3: type: integer description: '*the number of 3-star ratings*' items.4: type: integer description: '*the number of 4-star ratings*' items.5: type: integer description: '*the number of 5-star ratings*' items.people_also_search: type: array items: type: string description: '*related business entities*' items.work_time: type: object description: '*work time details* information related to operational hours of the business entity' items.work_hours: type: object description: '*open hours* information about work hours of the local establishment' items.timetable: type: object description: '*work hours timetable*' items.sunday: type: array items: type: string description: '*work hours on Sundays*' items.open: type: object description: '*opening time*' items.hour: type: integer description: '*hours in the 24-hour format*' items.minute: type: integer description: '*minutes*' items.close: type: object description: '*closing time*' items.monday: type: array items: type: string description: '*work hours on Mondays*' items.tuesday: type: array items: type: string description: '*work hours on Tuesdays*' items.wednesday: type: array items: type: string description: '*work hours on Wednesdays*' items.thursday: type: array items: type: string description: '*work hours on Thursdays*' items.friday: type: array items: type: string description: '*work hours on Fridays*' items.saturday: type: array items: type: string description: '*work hours on Saturday*' items.current_status: type: string description: '*current status of the establishment* possible values: `opened`, `closed`, `temporarily_closed`, `closed_forever`' popular_times: type: object description: '*popular times* information related to busy hours of the business entity' popular_times.popular_times_by_days: type: object description: '*popular hours* information about busy hours of the local establishment on each day of the week' popular_times.sunday: type: array items: type: string description: '*busy hours on sunday* **can take values of the corresponding days of the week**' popular_times.time: type: object description: '*busy hours*' popular_times.hour: type: integer description: '*hours in a 24-hour format*' popular_times.minute: type: integer description: '*minutes*' popular_times.popular_index: type: integer description: '*popularity index* relative time-bound popularity index measured from `0` to `100`; higher value corresponds to a busier time of a day' local_business_links: type: array items: type: string description: '*available interactions with the business* list of options to interact with the business directly from search results' local_business_links.type: type: string description: '*type of element = **‘menu’***' local_business_links.title: type: string description: '*title of the element* domain of the online menu system' local_business_links.url: type: string description: '*URL to view the menu*' local_business_links.delivery_services: type: array items: type: string description: '*lists available delivery services*' local_business_links.is_directory_item: type: boolean description: '*business establishment is a part of the directory* indicates whether the business establishment is a part of the directory; if `true`, the item is a part of the larger directory of businesses with the same address (e.g., a mall or a business centre); **note:** if the business establishment is a parent item in the directory, the value will be `null`' directory: type: array items: type: string description: '*items of the directory* includes information about businesses that are located within the target business establishment and have the same address' directory.title: type: string description: '*title of the element in SERP* the name of the business entity' directory.items: type: array items: type: string description: '***array of directory items***' directory.type: type: string description: '*type of element = **‘maps\_search’***' directory.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from the `rank_group`' directory.rank_absolute: type: integer description: '*absolute rank among all the elements*' directory.domain: type: string description: '*domain of the business entity*' directory.url: type: string description: '*absolute url of the business entity*' directory.rating: type: object description: '*the element’s rating* the popularity rate based on reviews and displayed in SERP' directory.rating_type: type: string description: '*the type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' directory.value: type: integer description: '*the value of the rating*' directory.votes_count: type: integer description: '*the amount of feedback*' directory.rating_max: type: integer description: '*the maximum value for a `rating_type`*' directory.rating_distribution: type: object description: '*the distribution of ratings of the business entity* the object displays the number of 1-star to 5-star ratings, as reviewed by users' directory.1: type: integer description: '*the number of 1-star ratings*' directory.2: type: integer description: '*the number of 2-star ratings*' directory.3: type: integer description: '*the number of 3-star ratings*' directory.4: type: integer description: '*the number of 4-star ratings*' directory.5: type: integer description: '*the number of 5-star ratings*' directory.snippet: type: string description: '*additional information about the business entity*' directory.address: type: string description: '*street address of the business entity*' directory.address_info: type: object description: '*object containing address components of the business entity*' directory.borough: type: string description: '*administrative unit or district the business entity location belongs to*' directory.city: type: string description: '*name of the city where the business entity is located*' directory.zip: type: string description: '*ZIP code of the business entity*' directory.region: type: string description: '*DMA region of the business entity location*' directory.country_code: type: string description: '*ISO country code of the business entity location*' directory.place_id: type: string description: '*unique place identifier* [place id](https://developers.google.com/places/place-id) of the local establishment featured in the element learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' directory.phone: type: string description: '*phone number of the business entity*' directory.main_image: type: string description: '*URL of the main image featured in Google My Business profile*' directory.total_photos: type: integer description: '*total count of images featured in Google My Business profile*' directory.category: type: string description: '*business category* Google My Business general category that best describes the services provided by the business entity' directory.category_ids: type: array items: type: string description: '*global category IDs* universal category IDs that do not change based on the selected country' directory.work_hours: type: object description: '*work hours* information about work hours of the local establishment' directory.feature_id: type: string description: '*the unique identifier of the element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' directory.cid: type: string description: '*google-defined client id* unique id of a local establishment; can be used with [Google Reviews API](https://docs.dataforseo.com/v3/reviews/google/overview.md) to get a full list of reviews learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' directory.latitude: type: number description: '*latitude coordinate of the local establishments in google maps* example: `"latitude": 51.584091`' directory.longitude: type: number description: '*longitude coordinate of the local establishment in google maps* example: `"longitude": -0.31365919999999997`' directory.is_claimed: type: boolean description: '*shows whether the entity is verified by its owner on Google Maps*' directory.local_justifications: type: array items: type: string description: '*Google local justifications* snippets of text that “justify” why the business is showing up for search query' directory.is_directory_item: type: boolean description: '*business establishment is a part of the directory* indicates whether the business establishment is a part of the directory; if `true`, the item is a part of the larger directory of businesses with the same address (e.g., a mall or a business centre); **note:** if the business establishment is a parent item in the directory, the value will be `null`' directory.price_level: type: string description: '*property price level* can take values: `inexpensive`, `moderate`, `expensive`, `very_expensive` if there is no price level information, the value will be `null`' directory.hotel_rating: type: integer description: '*hotel class rating* class ratings range between 1-5 stars, [learn more](https://support.google.com/business/answer/7660515?hl=en) if there is no hotel class rating information, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_info/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.003 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google My Business Info Tasks description: 'Queues a Google Business Profile lookup, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin `post_dataforseo_business_google_gmb_info_live` answers immediately and is simpler for a single profile; queue when the batch is large.' operationId: post_dataforseo_business_google_gmb_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate the name of the local establishment you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”; this field can also be used to pass the following parameters: `cid` – a unique, google-defined id of the business entity; `place_id` – an identifier of the business entity in Google Maps; `spp` – a unique identifier of local services featured in the `local_pack` element of Google SERP example: `cid:194604053573767737` `place_id:GhIJQWDl0CIeQUARxks3icF8U8A` `spp:CgsvZy8xdGN4cWRraBoUChIJPZDrEzLsZIgRoNrpodC5P30` learn more about the `cid` and `place_id` identifiers in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id) learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 (mm) the maximum value for *“radius”*: 199999 (mm) example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_info/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google My Business Info Completed Tasks description: 'Lists finished Google Business Profile tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_google_gmb_info_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.se_type: type: string description: '*search engine specified when setting the task*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_info/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_updates/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google My Business Updates Results by id description: 'Retrieves queued Google Business Profile updates by `id`: each post with its text, media and date. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_business_google_gmb_updates_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)** this field will contain the `cid` parameter if you specified it in the `keyword` field when setting a task; example: `cid:2946633002421908862` learn more about the parameter in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.se_domain: type: string description: '*search engine domain as specified in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.business_updates_id: type: string description: '*identifier of the business updates element in SERP*' result.cid: type: string description: '*google-defined client id* unique id of a local establishment learn more about the `cid` identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.feature_id: type: string description: '*the unique identifier of the element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.item_types: type: array items: type: string description: '*item types* types of search engine results encountered in the `items` array; possible item types: `google_business_post`' result.items_count: type: integer description: '*item types* the number of items in the `items` array' items: type: array items: type: string description: '*encountered item types* types of search engine results encountered in the `items` array; possible item types: `google_business_post`' items.type: type: string description: '*type of a link element* can take the following values: `link_element`' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed updates* absolute position among all present elements' items.position: type: string description: '*the alignment of the element in SERP* can take the following values: `right`' items.xpath: type: string description: '*the [XPath](https://en.wikipedia.org/wiki/XPath) of the element*' items.author: type: string description: '*author of the post*' items.snippet: type: string description: '*additional content of a post*' items.post_text: type: string description: '*main content of a post*' items.url: type: string description: '*url of a page the link is pointing at*' items.images_url: type: string description: '*url of an image included in the post*' items.post_date: type: string description: '*date when a post was published* in the following format: `"mm/dd/yyyy hh:mm:ss"`' items.timestamp: type: string description: '*time when a post was published* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00' items.links: type: array items: type: string description: '*links included in the post*' items.title: type: string description: '*anchor text*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_updates/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_updates/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0045 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google My Business Updates Tasks description: 'Queues the posts a business has published to its Google Business Profile, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. There is no live variant - updates always queue. The profile itself is `post_dataforseo_business_google_gmb_info_live`.' operationId: post_dataforseo_business_google_gmb_updates_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate the name of the local establishment you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”;this field can also be used to pass `cid` (unique, google-defined id of the business entity) or `place_id` (identifier of the business entity in Google Maps) parameters example: `cid:194604053573767737` `place_id:GhIJQWDl0CIeQUARxks3icF8U8A`learn more about the `cid` and `place_id` identifiers in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of updates in SERP we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten updates in a row **please note that Google returns 4490 updates maximum** default value: `10`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_updates/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/my_business_updates/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google My Business Updates Completed Tasks description: 'Lists finished Google Business Profile update tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely the tool you want: a caller holds the `id` its own submit returned and can fetch that directly. This answers what is ready across the whole account, which is a different question, and it returns an empty result with status 20000 when nothing is - an empty queue, not an error.' operationId: get_dataforseo_business_google_gmb_updates_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.se_type: type: string description: '*search engine type*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/my_business_updates/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/questions_and_answers/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0108 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Live Google My Business Questions and Answers Tasks description: 'The questions and answers on a Google Business Profile, found by `keyword` and `location_code`. Returns `keyword`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `cid`, `feature_id` and `item_types`. Measured at $0.0054. ⚠️ **A miss still bills**: a keyword matching no business answered `status_code` 40102, `No Search Results.`, and was charged anyway - so confirm the business exists with `post_dataforseo_business_listings_search_live` before asking. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_business_google_qa_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)** this field will contain the `cid` parameter if you specified it in the `keyword` field when setting a task; example: `cid:2946633002421908862` learn more about the parameter in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.se_domain: type: string description: '*search engine domain as specified in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.cid: type: string description: '*google-defined client id* unique id of a local establishment; learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.feature_id: type: string description: '*unique identifier of the SERP feature*' result.item_types: type: array items: type: string description: '*item types* types of search engine results encountered in the `items` array; possible item types: `google_business_question_item`' items_without_answers: type: array items: type: string description: '*array of google business question items without answers*' items_without_answers.type: type: string description: '*type of element = **‘google\_business\_question\_item’***' items_without_answers.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items_without_answers.rank_absolute: type: integer description: '*absolute rank among all the elements*' items_without_answers.question_id: type: string description: '*ID of the question*' items_without_answers.url: type: string description: '*URL of the question*' items_without_answers.profile_image_url: type: string description: '*URL of the user’s profile image*' items_without_answers.profile_url: type: string description: '*URL of the user’s profile*' items_without_answers.profile_name: type: string description: '*displayed name of the user*' items_without_answers.question_text: type: string description: '*current text of the question*' items_without_answers.original_question_text: type: string description: '*original text of the question*' items_without_answers.time_ago: type: string description: '*estimated time when the question was posted*' items_without_answers.timestamp: type: string description: '*exact time when the question was posted*' items_without_answers.items: type: array items: type: string description: '*array of items* items within `google_business_question_item`' items_without_answers.items_count: type: integer description: '*the number of items in the `items` array*' items: type: array items: type: string description: '*array of google business question items with answers* possible item types: `google_business_question_item`' items.type: type: string description: '*type of the element = **‘google\_business\_answer\_element’***' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the elements*' items.question_id: type: string description: '*ID of the question*' items.url: type: string description: '*URL of the question*' items.profile_image_url: type: string description: '*URL of the user’s profile image*' items.profile_url: type: string description: '*URL of the user’s profile*' items.profile_name: type: string description: '*displayed name of the user*' items.question_text: type: string description: '*current text of the question*' items.original_question_text: type: string description: '*original text of the question*' items.time_ago: type: string description: '*estimated time when the answer was posted*' items.timestamp: type: string description: '*exact time when the answer was posted*' items.items: type: array items: type: string description: '*array of items within `google_business_question_item`* contains answers to the google business questions; possible item types `google_business_answer_element`' items.answer_id: type: string description: '*ID of the answer*' items.answer_text: type: string description: '*current text of the answer*' items.original_answer_text: type: string description: '*original text of the answer*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate the name of the local establishment you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”; this field can also be used to pass the following parameters: `cid` – a unique, google-defined id of the business entity; `place_id` – an identifier of the business entity in Google Maps; `spp` – a unique identifier of local services featured in the `local_pack` element of Google SERP example: `cid:194604053573767737` `place_id:GhIJQWDl0CIeQUARxks3icF8U8A` `spp:CgsvZy8xdGN4cWRraBoUChIJPZDrEzLsZIgRoNrpodC5P30` learn more about the `cid` and `place_id` identifiers in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id) learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 (mm) the maximum value for *“radius”*: 199999 (mm) example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of results in SERP default value: `20` max value: `100` **Your account will be billed per each SERP containing up to 20 results;** Setting depth above 20 may result in additional charges if the search engine returns more than 20 results; If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-questions-and-answers-api-pricing "Pricing") page.' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/questions_and_answers/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/questions_and_answers/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google My Business Questions and Answers Results by id description: 'Retrieves queued Google Business Profile questions and answers by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ The response size was fixed by the `depth` or limit set at submit time and cannot be narrowed here; if it is too large, resubmit smaller rather than paging.' operationId: get_dataforseo_business_google_qa_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)** this field will contain the `cid` parameter if you specified it in the `keyword` field when setting a task; example: `cid:2946633002421908862` learn more about the parameter in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.se_domain: type: string description: '*search engine domain as specified in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.cid: type: string description: '*google-defined client id* unique id of a local establishment; learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.feature_id: type: string description: '*unique identifier of the SERP feature*' result.item_types: type: array items: type: string description: '*item types* types of search engine results encountered in the `items` array; possible item types: `google_business_question_item`' items_without_answers: type: array items: type: string description: '*array of google business question items without answers*' items_without_answers.type: type: string description: '*type of element = **‘google\_business\_question\_item’***' items_without_answers.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items_without_answers.rank_absolute: type: integer description: '*absolute rank among all the elements*' items_without_answers.question_id: type: string description: '*ID of the question*' items_without_answers.url: type: string description: '*URL of the question*' items_without_answers.profile_image_url: type: string description: '*URL of the user’s profile image*' items_without_answers.profile_url: type: string description: '*URL of the user’s profile*' items_without_answers.profile_name: type: string description: '*displayed name of the user*' items_without_answers.question_text: type: string description: '*current text of the question*' items_without_answers.original_question_text: type: string description: '*original text of the question*' items_without_answers.time_ago: type: string description: '*estimated time when the question was posted*' items_without_answers.timestamp: type: string description: '*exact time when the question was posted*' items_without_answers.items: type: array items: type: string description: '*array of items* items within `google_business_question_item`' items_without_answers.items_count: type: integer description: '*the number of items in the `items` array*' items: type: array items: type: string description: '*array of google business question items with answers* possible item types: `google_business_question_item`' items.type: type: string description: '*type of the element = **‘google\_business\_answer\_element’***' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the elements*' items.question_id: type: string description: '*ID of the question*' items.url: type: string description: '*URL of the question*' items.profile_image_url: type: string description: '*URL of the user’s profile image*' items.profile_url: type: string description: '*URL of the user’s profile*' items.profile_name: type: string description: '*displayed name of the user*' items.question_text: type: string description: '*current text of the question*' items.original_question_text: type: string description: '*original text of the question*' items.time_ago: type: string description: '*estimated time when the answer was posted*' items.timestamp: type: string description: '*exact time when the answer was posted*' items.items: type: array items: type: string description: '*array of items within `google_business_question_item`* contains answers to the google business questions; the maximum number of answers returned for each question: `5` possible item types `google_business_answer_element`' items.answer_id: type: string description: '*ID of the answer*' items.answer_text: type: string description: '*current text of the answer*' items.original_answer_text: type: string description: '*original text of the answer*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/questions_and_answers/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/questions_and_answers/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google My Business Questions and Answers Tasks description: 'Queues the questions and answers on a Google Business Profile, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Same as the live twin: a keyword that matches nothing is still charged.' operationId: post_dataforseo_business_google_qa_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate the name of the local establishment you can specify **up to 700 characters** in the `keyword` filed **all %## will be decoded (plus character ‘+’ will be decoded to a space character)** if you need to use the “%” character for your `keyword`, please specify it as “%25”; this field can also be used to pass the following parameters: `cid` – a unique, google-defined id of the business entity; `place_id` – an identifier of the business entity in Google Maps; `spp` – a unique identifier of local services featured in the `local_pack` element of Google SERP example: `cid:194604053573767737` `place_id:GhIJQWDl0CIeQUARxks3icF8U8A` `spp:CgsvZy8xdGN4cWRraBoUChIJPZDrEzLsZIgRoNrpodC5P30` learn more about the `cid` and `place_id` identifiers in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id) learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-questions-and-answers-api-pricing "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 (mm) the maximum value for *“radius”*: 199999 (mm) example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of question rows in the result default value: `20` max value: `700` **Your account will be billed per each SERP containing up to 20 results;** Setting depth above 20 may result in additional charges if the search engine returns more than 20 results; If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-questions-and-answers-api-pricing "Pricing") page.' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23` learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/questions_and_answers/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/questions_and_answers/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google My Business Questions and Answers Completed Tasks description: 'Lists finished Google Business Profile Q&A tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely the tool you want: a caller holds the `id` its own submit returned and can fetch that directly. This answers what is ready across the whole account, which is a different question, and it returns an empty result with status 20000 when nothing is - an empty queue, not an error.' operationId: get_dataforseo_business_google_qa_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se_type: type: string description: '*search engine type*' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/questions_and_answers/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/reviews/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Business Data Google Reviews Results by id description: 'Retrieves queued Google Business Profile reviews by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the depth set at submit and cannot be narrowed here.' operationId: get_dataforseo_business_google_reviews_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* **keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)**' result.type: type: string description: '*search engine type in a POST array*' result.se_domain: type: string description: '*search engine domain in a POST array*' result.location_code: type: integer description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.title: type: string description: '*title of the ‘reviews’ element in SERP* the name of the local establishment for which the reviews are collected' result.sub_title: type: string description: '*subtitle of the ‘reviews’ element in SERP* additional information (e.g., address) on the ‘reviews’ element for which the reviews are collected' result.rating: type: object description: '*rating of the corresponding local establishment* popularity rate based on reviews and displayed in SERP' result.rating_type: type: string description: '*type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' result.value: type: number description: '*the average rating based on all reviews*' result.votes_count: type: integer description: '*the number of votes*' result.rating_max: type: integer description: '*the maximum value for a `rating_type`*' result.feature_id: type: string description: '*the unique identifier of the ‘reviews’ element in SERP* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.place_id: type: string description: '*unique identifier of a business location assigned by Google* learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.cid: type: string description: '*google-defined client id* unique id of a local establishment learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' result.reviews_count: type: integer description: '*the total number of reviews*' result.items_count: type: integer description: '*the number of reviews items in the results array* you can get more results by using the `depth` parameter when setting a task' items: type: array items: type: string description: '*found reviews* you can get more results by using the `depth` parameter when setting a task' items.type: type: string description: '*type of element = **‘images\_element’***' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed reviews* absolute position among all reviews on the list' items.position: type: string description: '*the alignment of the review in SERP* can take the following values: `right`' items.xpath: type: string description: '*the [XPath](https://en.wikipedia.org/wiki/XPath) of the review*' items.review_text: type: string description: '*the content of the review*' items.original_review_text: type: string description: '*original content of the review* the original content of the review, no auto-translate applied' items.time_ago: type: string description: '*the time of publication* indicates the time (in the ‘time ago’ format) when the review was listed' items.timestamp: type: string description: '*date and time when a review was published* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.rating: type: object description: '*the rating score submitted by the reviewer*' items.rating_type: type: string description: '*the type of the rating* can take the following values: `Max5`' items.value: type: number description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback* indicated the number of votes the review obtained' items.rating_max: type: integer description: '*the maximum value for a `rating_type`* the maximum value for `Max5` is 5' items.reviews_count: type: integer description: '*total number of reviews submitted by the reviewer*' items.photos_count: type: integer description: '*total number of photos submitted by the reviewer*' items.local_guide: type: boolean description: '*indicates whether the reviewer has a ‘local guide’ status*' items.profile_name: type: string description: '*profile name of the reviewer*' items.profile_url: type: string description: '*URL of the reviewer’s profile*' items.review_url: type: string description: '*the URL of the review*' items.profile_image_url: type: string description: '*URL of the reviewer’s profile image*' items.owner_answer: type: string description: '*text of the owner’s response* the owner’s response to the review' items.original_owner_answer: type: string description: '*original text of the owner’s response* the original response to the review, no auto-translate applied' items.owner_time_ago: type: string description: '*publication time* indicates the time (in the ‘time ago’ format) when the owner submitted the response to the review' items.owner_timestamp: type: string description: '*date and time of the owner’s reply to the review* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.review_id: type: string description: '*the unique identifier of a review on Google* example: `ChZDSUhNMG9nS0VJQ0FnSUMxbHFyMFlnEAE`' items.images: type: array items: type: string description: '*images submitted by the reviewer*' items.alt: type: string description: '*alt tag of the image*' items.url: type: string description: '*relevant image URL from Google*' items.image_url: type: string description: '*URL of the image featured in the review*' items.review_highlights: type: array items: type: string description: '*review highlights* contains highlighted review criteria and assessments' items.feature: type: string description: '*reviewed feature*' items.assessment: type: string description: '*feature assessment*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/reviews/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Business Data Google Reviews Tasks description: 'Queues Google Business Profile reviews, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_google_reviews_fetch`; the profile itself is `post_dataforseo_business_google_gmb_info_live`.' operationId: post_dataforseo_business_google_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field if you don’t specify `cid` or `place_id`** the keyword you specify should indicate the name of the local establishment; you can specify **up to 700 characters** in the `keyword` filed; all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your `keyword`, please specify it as “%25”; if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, **the charge per task will be multiplied by 5** Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' cid: type: string description: '*unique, google-defined id of the business entity* **required field if you don’t specify `keyword` or `place_id`** example: `194604053573767737` learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' place_id: type: string description: '*identifier of the business entity in Google Maps* **required field if you don’t specify `keyword` or `cid`** example: `GhIJQWDl0CIeQUARxks3icF8U8A` learn more about the identifier in [this help center article](https://dataforseo.com/help-center/what-is-cid-place-id-feature-id)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-reviews-api "Pricing") page.' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify** `location_code` or `location_coordinate` **if you use this field, you don’t need to specify `location_code` or `location_coordinate`** you can receive the list of available locations with `location_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify** `location_name` or `location_coordinate` **if you use this field, you don’t need to specify `location_name` or `location_coordinate`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/locations` example: `2840`' location_coordinate: type: string description: '*GPS coordinates of a location* **required field if you don’t specify** `location_name` or `location_code` **if you use this field, you don’t need to specify `location_name` or `location_code`** `location_coordinate` parameter should be specified in the *“latitude,longitude,radius”* format the maximum number of decimal digits for *“latitude”* and *“longitude”*: 7 the minimum value for *“radius”*: 199.9 example: `53.476225,-2.243572,200`' language_name: type: string description: '*full name of search engine language* **required field if you don’t specify** `language_code` **if you use this field, you don’t need to specify `language_code`** you can receive the list of available languages with `language_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/languages` example: `English`' language_code: type: string description: '*search engine language code* **required field if you don’t specify** `language_name` **if you use this field, you don’t need to specify `language_name`** you can receive the list of available languages with their `language_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/google/languages` example: `en`' depth: type: integer description: '*parsing depth* optional field number of reviews in SERP we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row default value: `10` maximum value: `4490` **Your account will be billed per each SERP containing up to 10 results;** Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/google-reviews-api "Pricing") page.' sort_by: type: string description: '*results sorting parameters* optional field you can use this field to sort the results possible types of sorting: `newest` – sort by newest first `highest_rating` – sort by highest rating `lowest_rating` – sort by lowest rating `relevant` – sort by relevance default value: `relevant`' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' allOf: - anyOf: - required: - location_name - required: - location_code - required: - location_coordinate - anyOf: - required: - language_name - required: - language_code - anyOf: - required: - keyword - required: - cid - required: - place_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/google/reviews/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Reviews Completed Tasks description: 'Lists finished Google Business Profile reviews tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_google_reviews_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `google`' result.se_type: type: string description: '*type of search engine*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/google/reviews/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/social_media/pinterest/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 8.0e-05 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Social Media Pinterest Tasks description: 'How many times each of `targets` has been pinned on Pinterest. Returns `type`, `page_url` and `pins_count` per URL. Measured at 546 bytes and **$0.00004 upstream - the cheapest endpoint measured anywhere in this provider**, three hundred times under the flat rate billed. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Takes a list, so check a whole site''s pages in one call. For Pinterest content rather than counts, the pinterest server reads the platform directly.' operationId: post_dataforseo_business_social_media_pinterest_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.type: type: string description: '*type of element = **‘social\_media\_pinterest\_item’***' result.page_url: type: string description: '*URL of the page the data is provided for* corresponding URL you specified in the `targets` array when setting a task' result.pins_count: type: integer description: '*number of pins for the related `page_url`* [pins on Pinterest](https://help.pinterest.com/en/business/article/build-a-pin) correspond to content saves; this field shows the number of content saves made from the related `page_url` using the [Pinterest Save Button](https://developers.pinterest.com/docs/widgets/save/?)' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: '*target URLs* **required field** target page should be specified with its absolute URL (including http:// or https://) example: `https://dataforseo.com/`**Note:** you can specify 10 targets maximum. You will be charged per earch URL you specify in this array' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/social_media/pinterest/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/social_media/reddit/live: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Social Media Reddit Tasks description: 'Intended to return Reddit sharing counts for `targets`. 🔴 **Currently unavailable upstream**: it answers `status_code` 50304, `This function temporarily unavailable. Please contact support`, with no `tasks` array at all - the failure is at the top level of the envelope, not inside a task. Measured 2026-08-25. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The Pinterest sibling `post_dataforseo_business_social_media_pinterest_live` works and costs almost nothing; for Reddit content itself, the reddit server reads the platform directly.' operationId: post_dataforseo_business_social_media_reddit_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.type: type: string description: '*type of element = **‘social\_media\_reddit\_item’***' result.page_url: type: string description: '*URL of the page the data is provided for* corresponding URL you specified in the `targets` array when setting a task' result.reddit reviews: type: array items: type: string description: '*reddit reviews for the page\_url*' result.subreddit: type: string description: '*the name of the subreddit*' result.author_name: type: string description: '*nickname of the author* nicknname of the user who published the post in the subreddit and shared the URL' result.title: type: string description: '*title of the subreddit post*' result.permalink: type: string description: '*URL to the subreddit post*' result.subreddit_members: type: integer description: '*number of subreddit members*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: targets: type: array items: type: string description: '*target URLs* **required field** target page should be specified with its absolute URL (including http:// or https://) example: `https://dataforseo.com/` **Note:** you can specify 10 targets maximum. You will be charged per earch URL you specify in this array' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' required: - targets tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/social_media/reddit/live source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/tripadvisor/reviews/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Business Data Tripadvisor Reviews Results by id description: 'Retrieves queued Tripadvisor reviews for one property by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the depth set at submit and cannot be narrowed here.' operationId: get_dataforseo_business_tripadvisor_reviews_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.url_path: type: string description: '*URL path received in a POST array*' result.type: type: string description: '*search engine type in a POST array*' result.se_domain: type: string description: '*search engine domain in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.title: type: string description: '*title of the ‘reviews’ element in SERP* the name of the local establishment for which the reviews are collected' result.location: type: string description: '*location of the local establishment* address of the local establishment for which the reviews are collected' result.reviews_count: type: integer description: '*the total number of reviews*' result.rating: type: object description: '*rating of the corresponding local establishment* popularity rate based on reviews and displayed in SERP' result.rating_type: type: string description: '*type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' result.value: type: number description: '*the average rating based on all reviews*' result.votes_count: type: integer description: '*the number of votes*' result.rating_max: type: integer description: '*the maximum value for a `rating_type`*' result.rating_distribution: type: object description: '*rating distribution by votes* the distribution of votes across the rating in the range from 1 to 5' result.1: type: integer description: '*votes for the 1-point rating*' result.2: type: integer description: '*votes for the 2-points rating*' result.3: type: integer description: '*votes for the 3-points rating*' result.4: type: integer description: '*votes for the 4-points rating*' result.5: type: integer description: '*votes for the 5-points rating*' result.items_count: type: integer description: '*the number of reviews items in the results array* you can get more results by using the `depth` parameter when setting a task' items: type: array items: type: string description: '*found reviews* you can get more results by using the `depth` parameter when setting a task' items.type: type: string description: '*the review’s type* possible review types: `"tripadvisor_review_search"`' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed reviews* absolute position among all reviews on the list' items.position: type: string description: '*the alignment of the review in SERP* can take the following values: `right`' items.url: type: string description: '*URL of the reviewer’s profile*' items.rating: type: object description: '*the rating score submitted by the reviewer*' items.rating_type: type: string description: '*the type of the rating* can take the following values: `Max5`' items.value: type: number description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback* in this case, the value will be `null`' items.rating_max: type: integer description: '*the maximum value for a `rating_type`* the maximum value for `Max5` is 5' items.date_of_visit: type: string description: '*date of the reviewer’s visit to the local establishment* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.timestamp: type: string description: '*date and time when the response was published* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.review_id: type: string description: '*ID of the review*' items.title: type: string description: '*title of the owner’s response* indicates the owner’s name' items.review_text: type: string description: '*content of the review*' items.language: type: string description: '*language of the response text*' items.original_language: type: string description: '*language of the untranslated review text*' items.review_images: type: array items: type: string description: '*contains URLs of the images used in the review*' items.user_profile: type: object description: '*information from the reviewer’s profile*' items.name: type: string description: '*reviewer’s profile name*' items.image_url: type: string description: '*URL of the reviewer’s profile image*' items.location: type: string description: '*URL of the reviewer’s profile image*' items.reviews_count: type: string description: '*total number of reviews submitted by the reviewer*' items.responses: type: array items: type: string description: '*contains information about the owner’s response*' items.text: type: string description: '*text of the owner’s response*' items.response_id: type: string description: '*ID of the response*' items.review_highlights: type: array items: type: string description: '*review highlights* contains highlighted review criteria and assessments' items.feature: type: string description: '*reviewed feature*' items.assessment: type: string description: '*feature assessment*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/tripadvisor/reviews/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/tripadvisor/reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.003 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Business Data Tripadvisor Reviews Tasks description: 'Queues Tripadvisor reviews for one property, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_tripadvisor_reviews_fetch`; the Trustpilot equivalent is `post_dataforseo_business_trustpilot_reviews_submit`.' operationId: post_dataforseo_business_tripadvisor_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: url_path: type: string description: '*URL path of the business entity* **required field if you do not specify `keyword`** URL path to the Tripadvisor page of the business entity; examples: `Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html` `https://www.tripadvisor.com/Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html`' keyword: type: string description: '*keyword* **required field if you do not specify `url_path`** the keyword you specify should indicate a name of an existing business or prominent place on Tripadvisor; you can specify up to 700 characters in the `keyword` filed; all %## will be decoded (plus character ‘+’ will be decoded to a space character); if you need to use the “%” character for your `keyword`, please specify it as “%25”' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code` or `url_path`** you can receive the list of available locations with `location_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/tripadvisor/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name` or `url_path`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/tripadvisor/locations` example: `1003854`' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-tripadvisor-pricing "Pricing") page.' language_name: type: string description: '*full name of search engine language* optional field **if you use this field, your account will be charged for one extra request** you can receive the list of available languages with `language_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/tripadvisor/languages` example: `English` You will be additionally charged for setting a language parameter in this endpoint. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-tripadvisor-pricing "Pricing") page.' language_code: type: string description: '*search engine language code* optional field **if you use this field, your account will be charged for one extra request** you can receive the list of available languages with `language_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/tripadvisor/languages` example: `en` You will be additionally charged for setting a language parameter in this endpoint. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-tripadvisor-pricing "Pricing") page.' depth: type: integer description: '*parsing depth* optional field number of reviews in SERP; we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row; default value: `10`; max value: `4490` **Your account will be billed per each SERP containing up to 10 results;** Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-tripadvisor-pricing "Pricing") page.' ratings: type: array items: type: string description: '*Tripadvisor traveler rating for a place of interest* optional field rating based on the written reviews by a traveler after they visited a place. possible values: `excellent`, `very_good`, `average`, `poor`, `terrible` you can specify several values at once' visit_type: type: array items: type: string description: '*filter by type of travelers who left a review* optional field possible values: `families`, `couples`, `solo`, `business`, `friends` you can specify several values at once' months: type: array items: type: string description: '*filter by months when a traveler made a visit* optional field possible values: `january`, `february`, `march`, `april`, `may`, `april`, `june`, `july`, `august`, `september`, `october`, `november`, `december` you can specify several values at once' search_reviews_keyword: type: string description: '*search reviews containing a specified keyword* example: `dessert`' sort_by: type: string description: '*results sorting parameters* optional field you can use this field to sort the results; possible types of sorting: `most_recent` `detailed_reviews`' translate_reviews: type: boolean description: '*translate reviews according to the URL path* optional field if set to `true`, returned reviews will be translated to the language matching the specified `url_path`; for example, if `url_path` contains `tripadvisor.it` and `translate_reviews` is `true`, reviews will be translated to the Italian language; default value: `true` you can learn more about how reviews are translated in [this Help Center article](https://dataforseo.com/help-center/how-to-translate-reviews-in-tripadvisor-business-data-api)' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' allOf: - anyOf: - required: - url_path - required: - keyword - anyOf: - required: - url_path - required: - location_name - required: - location_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/tripadvisor/reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/tripadvisor/reviews/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Tripadvisor Reviews Completed Tasks description: 'Lists finished Tripadvisor reviews for one property tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_tripadvisor_reviews_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `tripadvisor`' result.se_type: type: string description: '*search engine type*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/tripadvisor/reviews/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/tripadvisor/search/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Business Data Tripadvisor Search Results by id description: 'Retrieves queued Tripadvisor properties matching a query - how to find the id the reviews endpoint needs by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the depth set at submit and cannot be narrowed here.' operationId: get_dataforseo_business_tripadvisor_search_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword received in a POST array* this field will contain the `alias` parameter if it was specified in a POST array' result.se_domain: type: string description: '*search engine domain in a POST array*' result.location_code: type: string description: '*location code in a POST array*' result.language_code: type: string description: '*language code in a POST array*' result.check_url: type: string description: '*direct URL to Tripadvisor results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.item_types: type: array items: type: string description: '*item types encountered in the result* possible item types: `tripadvisor_search_organic`' result.se_results_count: type: integer description: '*the total number of results*' result.items_count: type: integer description: '*the number of items in the results array* you can get more results by using the `depth` parameter when setting a task' items: type: array items: type: string description: '*Tripadvisor search listing results* you can get more results by using the `depth` parameter when setting a task' items.type: type: string description: '*type of Tripadvisor search result* possible types: `tripadvisor_search_organic`' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed results* absolute position among all reviews on the list' items.title: type: string description: '*name of the business entity*' items.url_path: type: string description: '*URL path of the business entity* URL path to the Tripadvisor page of the business entity you can use this identifier to collect reviews for the business entity using [Tripadvisor Reviews](https://docs.dataforseo.com/v3/business_data/tripadvisor/reviews/task_post.md)' items.is_sponsored: type: boolean description: '*indicates a sponsored placement* if `true`, related `tripadvisor_search_organic` item is a paid advertising on Tripadvisor' items.reviews_count: type: integer description: '*the total number of reviews*' items.category: type: string description: '*place category*' items.price_rate: type: string description: '*average price rate*' items.rating: type: object description: '*the rating score of the establishment submitted by the reviewers*' items.rating_type: type: string description: '*the type of the rating* can take the following values: `Max5`' items.value: type: number description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback* indicates the number of votes the establishment obtained' items.rating_max: type: integer description: '*the maximum value for a `rating_type`* the maximum value for `Max5` is 5' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/tripadvisor/search/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/tripadvisor/search/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Business Data Tripadvisor Search Tasks description: 'Queues Tripadvisor properties matching a query - how to find the id the reviews endpoint needs, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_tripadvisor_search_fetch`; reviews come from `post_dataforseo_business_tripadvisor_reviews_submit`.' operationId: post_dataforseo_business_tripadvisor_search_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate a business category, company name, or a prominent place; you can specify up to 700 characters in the `keyword` filed; all %## will be decoded (plus character ‘+’ will be decoded to a space character); if you need to use the “%” character for your `keyword`, please specify it as “%25” learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' location_name: type: string description: '*full name of search engine location* **required field if you don’t specify `location_code`** you can receive the list of available locations with `location_name` by making a separate request to the `https://api.dataforseo.com/v3/business_data/tripadvisor/locations` example: `London,England,United Kingdom`' location_code: type: integer description: '*search engine location code* **required field if you don’t specify `location_name`** you can receive the list of available locations with `location_code` by making a separate request to the `https://api.dataforseo.com/v3/business_data/tripadvisor/locations` example: `1003854`' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-tripadvisor-search-pricing "Pricing") page.' depth: type: integer description: '*parsing depth* optional field number of search results to be returned from the API response we strongly recommend setting the parsing depth in the multiples of thirty because our systems processes thirty search results in a row; default value: `30`; maximum value: `210` **Your account will be billed per each SERP containing up to 30 results;** Setting depth above 30 may result in additional charges if the search engine returns more than 30 results; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-tripadvisor-search-pricing "Pricing") page.' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' required: - keyword allOf: - anyOf: - required: - location_name - required: - location_code tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/tripadvisor/search/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/tripadvisor/search/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Tripadvisor Search Completed Tasks description: 'Lists finished Tripadvisor properties matching a query tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_tripadvisor_search_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `tripadvisor`' result.se_type: type: string description: '*search engine type*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/tripadvisor/search/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/trustpilot/reviews/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Business Data Trustpilot Reviews Results by id description: 'Retrieves queued Trustpilot reviews for one business by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the depth set at submit and cannot be narrowed here.' operationId: get_dataforseo_business_trustpilot_reviews_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.domain: type: string description: '*domain of the business entity*' result.type: type: string description: '*search engine type in a POST array*' result.se_domain: type: string description: '*search engine domain in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.title: type: string description: '*title of the ‘reviews’ element on Trustpilot* the name of the business entity for which the reviews are collected' result.location: type: string description: '*location of the business entity as specified on Trustpilot* address of the business entity for which the reviews are collected' result.reviews_count: type: integer description: '*the total number of reviews*' result.rating: type: object description: '*rating of the corresponding business entity* popularity rate based on reviews and displayed in SERP' result.rating_type: type: string description: '*type of rating* here you can find the following elements: `Max5`, `Percents`, `CustomMax`' result.value: type: number description: '*the average rating based on all reviews*' result.votes_count: type: integer description: '*the number of votes*' result.rating_max: type: integer description: '*the maximum value for a `rating_type`*' result.items_count: type: integer description: '*the number of items in the results array* you can get more results by using the `depth` parameter when setting a task' items: type: array items: type: string description: '*found reviews* you can get more results by using the `depth` parameter when setting a task' items.type: type: string description: '*the review’s type* possible review types: `"trustpilot_review_search"`' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed reviews* absolute position among all reviews on the list' items.position: type: string description: '*the alignment of the review in SERP* can take the following values: `right`' items.url: type: string description: '*URL to the reviewer’s profile*' items.rating: type: object description: '*the rating score submitted by the reviewer*' items.rating_type: type: string description: '*the type of the rating* can take the following values: `Max5`' items.value: type: number description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback* indicated the number of votes the review obtained' items.rating_max: type: integer description: '*the maximum value for a `rating_type`* the maximum value for `Max5` is 5' items.verified: type: boolean description: '*indicates whether the review has the “Verified” mark*' items.language: type: boolean description: '*the language of the review*' items.timestamp: type: string description: '*date and time when the response was published* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' items.title: type: string description: '*title of the owner’s response*' items.review_text: type: string description: '*the content of the review*' items.review_images: type: array items: type: string description: '*images submitted by the reviewer* displays URLs to the images provided by the author of the review; **please note** that Trustpilot doesn’t allow adding images to reviews, so the `review_images` parameter will always equal `null`' items.user_profile: type: object description: '*user profile of the reviewer*' items.name: type: string description: '*the name of the reviewer*' items.image_url: type: string description: '*URL to the reviewer’s profile picture*' items.location: type: string description: '*country of the reviewer*' items.reviews_count: type: integer description: '*total number of reviews submitted by the reviewer*' items.responses: type: array items: type: string description: '*owner’s response to the submitted review*' items.text: type: string description: '*text of the owner’s response*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/trustpilot/reviews/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/trustpilot/reviews/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Business Data Trustpilot Reviews Tasks description: 'Queues Trustpilot reviews for one business, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_trustpilot_reviews_fetch`; the Tripadvisor equivalent is `post_dataforseo_business_tripadvisor_reviews_submit`.' operationId: post_dataforseo_business_trustpilot_reviews_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: domain: type: string description: '*domain of the local establishment* **required field** domain of the local establishment on Trustpilot; you can find the domain in the URL of every business listed on Trustpilot example: `www.thepearlsource.com` `https://www.trustpilot.com/review/www.thepearlsource.com`' sort_by: type: string description: '*results sorting parameter* optional field you can use this field to sort the results; possible sorting parameters: `recency` — most recent reviews first; `relevance` — most relevant reviews first; default value: `relevance`' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-trustpilot-reviews-pricing "Pricing") page.' depth: type: integer description: '*parsing depth* optional field number of reviews to be returned from the API response we strongly recommend setting the parsing depth in the multiples of twenty, because our system processes twenty reviews in a row default value: `20` maximum value: `200` **Your account will be billed per each SERP containing up to 20 results;** Setting depth above 20 may result in additional charges if the search engine returns more than 20 results; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-trustpilot-reviews-pricing "Pricing") page.' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' required: - domain tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/trustpilot/reviews/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/trustpilot/reviews/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Trustpilot Reviews Completed Tasks description: 'Lists finished Trustpilot reviews for one business tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_trustpilot_reviews_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `trustpilot`' result.se_type: type: string description: '*search engine type*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/trustpilot/reviews/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/trustpilot/search/task_get/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Business Data Trustpilot Search Results by id description: 'Retrieves queued Trustpilot businesses matching a query - how to find the id the reviews endpoint needs by `id`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Size scales with the depth set at submit and cannot be narrowed here.' operationId: get_dataforseo_business_trustpilot_search_fetch parameters: - name: id in: path required: true schema: type: string description: DataForSEO task ID. responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total *tasks* cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array that were returned an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results*' result.keyword: type: string description: '*keyword in a POST array*' result.se_domain: type: string description: '*search engine domain in a POST array*' result.check_url: type: string description: '*direct URL to search engine results* you can use it to make sure that we provided accurate results' result.datetime: type: string description: '*date and time when the result was received* in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`' result.items_count: type: integer description: '*the number of items in the results array* you can get more results by using the `depth` parameter when setting a task' items: type: array items: type: string description: '*found reviews* you can get more results by using the `depth` parameter when setting a task' items.type: type: string description: '*the result’s type* possible result types: `"trustpilot_search_organic"`' items.rank_group: type: integer description: '*position within a group of elements with identical `type` values* positions of elements with different `type` values are omitted from `rank_group`' items.rank_absolute: type: integer description: '*absolute rank among all the listed reviews* absolute position among all reviews on the list' items.title: type: string description: '*title of the establishment*' items.domain: type: string description: '*domain of the establishment*' items.url: type: string description: '*URL to the establishment*' items.reviews_count: type: integer description: '*the total number of reviews*' items.rating: type: object description: '*the rating score of the establishment submitted by reviewers*' items.rating_type: type: string description: '*the type of the rating* can take the following values: `Max5`' items.value: type: number description: '*the value of the rating*' items.votes_count: type: integer description: '*the amount of feedback* indicates the number of votes the establishment obtained' items.rating_max: type: integer description: '*the maximum value for a `rating_type`* the maximum value for `Max5` is 5' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/trustpilot/search/task_get/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/trustpilot/search/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0015 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Business Data Trustpilot Search Tasks description: 'Queues Trustpilot businesses matching a query - how to find the id the reviews endpoint needs, returning a task `id`. Asynchronous: submit returns a task `id` in `tasks[0].id`, fetch returns the result once ready, and the charge lands on the submit - fetching is free, including re-fetching. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. Retrieve with `get_dataforseo_business_trustpilot_search_fetch`; reviews come from `post_dataforseo_business_trustpilot_reviews_submit`.' operationId: post_dataforseo_business_trustpilot_search_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`**array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*unique task identifier in our system* in the [Universally unique identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) format' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000' tasks.status_message: type: string description: '*informational message of the task*' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the same parameters that you specified in the POST request*' result: type: array items: type: string description: '*array of results* in this case, the value will be `null`' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: '*keyword* **required field** the keyword you specify should indicate a business category or company name; you can specify up to 700 characters in the `keyword` filed; all %## will be decoded (plus character ‘+’ will be decoded to a space character); if you need to use the “%” character for your `keyword`, please specify it as “%25” learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis)' priority: type: integer description: '*task priority* optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority You will be additionally charged for the tasks with high execution priority. The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-trustpilot-search-pricing "Pricing") page.' depth: type: integer description: '*parsing depth* optional field number of search results to be returned from the API response we strongly recommend setting the parsing depth in the multiples of twenty because our systems processes twenty search results in a row; default value: `10`; maximum value: `140` **Your account will be billed per each SERP containing up to 10 results;** Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the [Pricing](https://dataforseo.com/pricing/business-data/business-data-api-trustpilot-search-pricing "Pricing") page.' tag: type: string description: '*user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response' postback_url: type: string description: '*return URL for sending task results* optional field once the task is completed, we will send a POST request with its results compressed in the `gzip` format to the `postback_url` you specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/postbackscript?id=$id` `http://your-server.com/postbackscript?id=$id&tag=$tag` **Note:** special characters in `postback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' pingback_url: type: string description: '*notification URL of a completed task* optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a `$id` variable and ‘$tag’ as urlencoded `$tag` variable. We will set the necessary values before sending the request. example: `http://your-server.com/pingscript?id=$id` `http://your-server.com/pingscript?id=$id&tag=$tag` **Note:** special characters in `pingback_url` will be urlencoded; i.a., the `#` character will be encoded into `%23`learn more on our [Help Center](https://dataforseo.com/help-center/pingbacks-postbacks-with-dataforseo-api)' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/trustpilot/search/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/business_data/trustpilot/search/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Trustpilot Search Completed Tasks description: 'Lists finished Trustpilot businesses matching a query tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. A caller that holds its own task `id` can fetch directly and skip this.' operationId: get_dataforseo_business_trustpilot_search_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: '*the current version of the API*' version.status_code: type: integer description: '*general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions' version.status_message: type: string description: '*general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' version.time: type: string description: '*execution time, seconds*' version.cost: type: number description: '*total tasks cost, USD*' version.tasks_count: type: integer description: '*the number of tasks in the **`tasks`** array*' version.tasks_error: type: integer description: '*the number of tasks in the **`tasks`** array returned with an error*' tasks: type: array items: type: string description: '*array of tasks*' tasks.id: type: string description: '*task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' tasks.status_code: type: integer description: '*status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.status_message: type: string description: '*informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md)' tasks.time: type: string description: '*execution time, seconds*' tasks.cost: type: number description: '*cost of the task, USD*' tasks.result_count: type: integer description: '*number of elements in the `result` array*' tasks.path: type: array items: type: string description: '*URL path*' tasks.data: type: object description: '*contains the parameters passed in the request’s URL*' result: type: array items: type: string description: '*array of results*' result.id: type: string description: '*task identifier of the completed task* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format**' result.se: type: string description: '*search engine specified when setting the task* can take the following values: `trustpilot`' result.se_type: type: string description: '*search engine type*' result.date_posted: type: string description: '*date when the task was posted (in the UTC format)*' result.tag: type: string description: '*user-defined task identifier*' result.endpoint: type: string description: '*URL for collecting the results of the task*' '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/business_data/trustpilot/search/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 p50: 0.012 p95: 0.0861 max: 0.12 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Organic SERP Tasks description: 'Queues the ranked results for a keyword on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Total tasks cost in USD tasks_count: type: integer description: Number of tasks in the request tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Task cost tasks[].result_count: type: integer description: Number of result elements '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code location_coordinate: type: string description: GPS coordinates of a location language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code depth: type: integer description: Parsing depth, default 100, max 700 max_crawl_pages: type: integer description: Page crawl limit, max 100 device: type: string description: 'Device type: desktop or mobile' os: type: string description: Device operating system group_organic_results: type: boolean description: Display related results as grouped organic results calculate_rectangles: type: boolean description: Calculate pixel rankings for SERP elements in advanced results postback_url: type: string description: Postback URL for completed task results pingback_url: type: string description: Pingback URL for task completion notification postback_data: type: string description: Postback payload type tag: type: string description: User-defined task identifier required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Organic SERP Results by id description: 'Retrieves a queued Google organic result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_organic_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Task cost in USD tasks_count: type: integer description: Number of tasks returned tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of task objects tasks[].id: type: string description: Task identifier tasks[].result: type: string description: Result array for the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 p50: 0.0021 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Organic SERP Advanced Results by id description: 'Retrieves a queued Google organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Task cost in USD tasks_count: type: integer description: Number of tasks returned tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of task objects tasks[].id: type: string description: Task identifier tasks[].result: type: string description: Advanced result array for the task '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Organic HTML Results by id description: 'Retrieves a queued Google organic result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_organic_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Task cost in USD tasks: type: string description: Array of task objects tasks[].id: type: string description: Task identifier tasks[].result: type: string description: Result array containing HTML pages tasks[].result[].items: type: string description: HTML page items tasks[].result[].items[].html: type: string description: Raw HTML page content '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished Google organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Request cost in USD tasks_count: type: integer description: Number of tasks returned tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of task objects tasks[].result: type: string description: Completed task list tasks[].result[].id: type: string description: Completed task identifier tasks[].result[].endpoint_regular: type: string description: Regular results endpoint tasks[].result[].endpoint_advanced: type: string description: Advanced results endpoint tasks[].result[].endpoint_html: type: string description: HTML results endpoint '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/live/regular: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.05 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Organic SERP Regular description: 'Returns the ranked results for a keyword on Google, synchronously. The lighter parse: measured at 4.8 KB against 57 KB for `advanced`, carrying the ranked list without the surrounding SERP features. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_organic_live_regular responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Request cost in USD tasks_count: type: integer description: Number of tasks returned tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of live task objects tasks[].id: type: string description: Task identifier tasks[].result: type: string description: Live SERP regular results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code location_coordinate: type: string description: GPS coordinates of a location language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type: desktop or mobile' os: type: string description: Device operating system depth: type: integer description: Parsing depth, default 100, max 700 max_crawl_pages: type: integer description: Page crawl limit, max 100 tag: type: string description: User-defined task identifier required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/live/regular source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.031 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Organic SERP Advanced description: 'Returns the ranked results for a keyword on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_organic_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Request cost in USD tasks_count: type: integer description: Number of tasks returned tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of live task objects tasks[].id: type: string description: Task identifier tasks[].result: type: string description: Live SERP advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code location_coordinate: type: string description: GPS coordinates of a location language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type: desktop or mobile' os: type: string description: Device operating system depth: type: integer description: Parsing depth, default 100, max 700 max_crawl_pages: type: integer description: Page crawl limit, max 100 calculate_rectangles: type: boolean description: Calculate pixel rankings for SERP elements tag: type: string description: User-defined task identifier required: - keyword example: - keyword: best accounting software for startups location_name: United States language_code: en depth: 10 max_crawl_pages: 1 tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/organic/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Organic SERP HTML description: 'Returns the ranked results for a keyword on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_organic_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: API version status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time cost: type: number description: Request cost in USD tasks_count: type: integer description: Number of tasks returned tasks_error: type: integer description: Number of tasks returned with an error tasks: type: string description: Array of live task objects tasks[].id: type: string description: Task identifier tasks[].result: type: string description: Result array containing HTML pages tasks[].result[].items: type: string description: HTML page items tasks[].result[].items[].html: type: string description: Raw HTML page content '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: url: type: string description: Direct URL of the search query location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code location_coordinate: type: string description: GPS coordinates of a location language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type: desktop or mobile' os: type: string description: Device operating system se_domain: type: string description: Custom search engine domain depth: type: integer description: Parsing depth, default 100, max 700 max_crawl_pages: type: integer description: Page crawl limit, max 100 search_param: type: string description: Additional parameters of the search query load_async_ai_overview: type: boolean description: Load asynchronous AI overview expand_ai_overview: type: boolean description: Expand AI overview item tag: type: string description: User-defined task identifier keyword: type: string description: Keyword to search for. tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/organic/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google AI Mode Languages for SERP description: 'Returns Google''s AI Mode answer for a query, with the sources it cites on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_ai_mode_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available languages tasks[].result[].language_name: type: string description: Language name tasks[].result[].language_code: type: string description: Language code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google AI Mode SERP Tasks description: 'Queues Google''s AI Mode answer for a query, with the sources it cites on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_ai_mode_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword; you can specify up to 700 characters location_code: type: integer description: Search engine location code; required if location_name or location_coordinate is not specified location_name: type: string description: Full name of search engine location; required if location_code or location_coordinate is not specified location_coordinate: type: string description: GPS coordinates of a location; required if location_name or location_code is not specified language_name: type: string description: Full name of search engine language; required if language_code is not specified language_code: type: string description: Search engine language code; required if language_name is not specified priority: type: integer description: 'Task priority: 1 normal (default), 2 high' device: type: string description: 'Device type: desktop or mobile' pingback_url: type: string description: Notification URL of a completed task postback_url: type: string description: URL for sending task results postback_data: type: string description: 'Postback URL datatype; required if postback_url is specified; possible values: advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Ai Mode SERP Completed Tasks description: 'Lists finished Google ai mode tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_ai_mode_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].time: type: string description: Execution time, seconds tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].path: type: array items: type: string description: URL path tasks[].data: type: object description: Contains the parameters passed in the request URL tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting SERP HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0024 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google AI Mode SERP Advanced Results by id description: 'Retrieves a queued Google ai mode result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_ai_mode_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].time: type: string description: Execution time, seconds tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].path: type: array items: type: string description: URL path tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of SERP results tasks[].result[].keyword: type: string description: Keyword received in the POST array tasks[].result[].type: type: string description: Search engine type in the POST array tasks[].result[].check_url: type: string description: Search URL with refinement parameters tasks[].result[].item_types: type: array items: type: string description: Types of search results found in SERP tasks[].result[].se_results_count: type: integer description: Total number of results in SERP tasks[].result[].items_count: type: integer description: Number of results returned in the items array tasks[].result[].items: type: array items: type: string description: Elements of search results found in SERP tasks[].result[].items[].type: type: string description: Type of element, such as ai_overview tasks[].result[].items[].markdown: type: string description: Content of the element in markdown format '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Ai Mode HTML Results by id description: 'Retrieves a queued Google ai mode result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_ai_mode_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].time: type: string description: Execution time, seconds tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].path: type: array items: type: string description: URL path tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google AI Mode SERP description: 'Returns Google''s AI Mode answer for a query, with the sources it cites on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_ai_mode_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results tasks[].result[].keyword: type: string description: Keyword received in the POST array tasks[].result[].type: type: string description: Search engine type in the POST array tasks[].result[].se_domain: type: string description: Search engine domain in the POST array tasks[].result[].location_code: type: integer description: Location code in the POST array tasks[].result[].language_code: type: string description: Language code in the POST array tasks[].result[].check_url: type: string description: Search URL with refinement parameters tasks[].result[].item_types: type: array items: type: string description: Types of search results found in SERP tasks[].result[].items_count: type: integer description: Number of results returned in the items array tasks[].result[].items: type: array items: type: string description: Elements of search results found in SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword; you can specify up to 700 characters location_code: type: integer description: Search engine location code; required if location_name or location_coordinate is not specified location_name: type: string description: Full name of search engine location; required if location_code or location_coordinate is not specified location_coordinate: type: string description: GPS coordinates of a location; required if location_name or location_code is not specified language_name: type: string description: Full name of search engine language; required if language_code is not specified language_code: type: string description: Search engine language code; required if language_name is not specified device: type: string description: 'Device type: desktop or mobile' calculate_rectangles: type: boolean description: Enable pixel ranking calculations for elements in SERP browser_screen_width: type: integer description: Custom browser screen width browser_screen_height: type: integer description: Custom browser screen height browser_screen_resolution_ratio: type: number description: Screen resolution ratio for rectangle calculations required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ai_mode/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Ai Mode SERP HTML description: 'Returns Google''s AI Mode answer for a query, with the sources it cites on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_ai_mode_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].time: type: string description: Execution time, seconds tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].path: type: array items: type: string description: URL path tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of HTML results tasks[].result[].keyword: type: string description: Keyword received in the POST array tasks[].result[].type: type: string description: Search engine type in the POST array tasks[].result[].se_domain: type: string description: Search engine domain in the POST array tasks[].result[].location_code: type: integer description: Location code in the POST array tasks[].result[].language_code: type: string description: Language code in the POST array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword; you can specify up to 700 characters location_name: type: string description: Full name of search engine location; required if location_code or location_coordinate is not specified location_code: type: integer description: Search engine location code; required if location_name or location_coordinate is not specified location_coordinate: type: string description: GPS coordinates of a location; required if location_name or location_code is not specified language_name: type: string description: Full name of search engine language; required if language_code is not specified language_code: type: string description: Search engine language code; required if language_name is not specified device: type: string description: 'Device type: desktop or mobile' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ai_mode/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/maps/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Maps SERP Tasks description: 'Queues the map pack for a local query, with each business''s rating, address and place id on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_maps_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/maps/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/maps/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Maps SERP Completed Tasks description: 'Lists finished Google maps tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_maps_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/maps/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/maps/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Maps SERP Advanced Results by id description: 'Retrieves a queued Google maps result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_maps_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/maps/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/maps/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Maps SERP description: 'Returns the map pack for a local query, with each business''s rating, address and place id on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_maps_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language depth: type: integer description: Parsing depth required: - keyword example: - keyword: sushi near Shibuya Station location_name: Tokyo,Japan language_code: en depth: 10 tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/maps/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/local_finder/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Local Finder SERP Tasks description: 'Queues the expanded local results Google shows when a query is clearly local on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_local_finder_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language depth: type: integer description: Parsing depth postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; possible values include advanced and html required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/local_finder/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/local_finder/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Local Finder SERP Completed Tasks description: 'Lists finished Google local finder tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_local_finder_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting SERP HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/local_finder/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/local_finder/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Local Finder SERP Advanced Results by id description: 'Retrieves a queued Google local finder result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_local_finder_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/local_finder/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/local_finder/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Local Finder HTML Results by id description: 'Retrieves a queued Google local finder result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_local_finder_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/local_finder/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/local_finder/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Local Finder SERP description: 'Returns the expanded local results Google shows when a query is clearly local on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_local_finder_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language min_rating: type: number description: Minimum rating filter time_filter: type: string description: Time filter required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/local_finder/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/local_finder/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Local Finder SERP HTML description: 'Returns the expanded local results Google shows when a query is clearly local on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_local_finder_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/local_finder/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/news/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google News SERP Tasks description: 'Queues the news results for a keyword on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_news_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; possible values include advanced and html required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/news/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/news/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get News SERP Completed Tasks description: 'Lists finished Google news tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_news_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting SERP HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/news/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/news/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google News SERP Advanced Results by id description: 'Retrieves a queued Google news result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_news_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/news/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/news/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google News HTML Results by id description: 'Retrieves a queued Google news result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_news_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/news/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/news/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.024 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google News SERP description: 'Returns the news results for a keyword on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_news_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language depth: type: integer description: Parsing depth required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/news/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/news/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google News SERP HTML description: 'Returns the news results for a keyword on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_news_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/news/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/events/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Events Locations for SERP API description: 'Returns the events Google surfaces for a query on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_events_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/events/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/events/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Events SERP Tasks description: 'Queues the events Google surfaces for a query on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_events_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/events/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/events/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Events SERP Completed Tasks description: 'Lists finished Google events tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_events_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/events/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/events/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Events SERP Advanced Results by id description: 'Retrieves a queued Google events result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_events_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/events/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/events/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Events SERP Advanced description: 'Returns the events Google surfaces for a query on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_events_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/events/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/images/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Images SERP Tasks description: 'Queues the image results for a keyword on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_images_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language device: type: string description: 'Device type: desktop or mobile' priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; possible values include regular, advanced, html required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/images/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/images/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Images SERP Completed Tasks description: 'Lists finished Google images tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_images_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_regular: type: string description: URL for collecting SERP results tasks[].result[].endpoint_html: type: string description: URL for collecting SERP HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/images/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/images/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Images SERP Results by id description: 'Retrieves a queued Google images result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_images_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/images/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/images/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Images HTML Results by id description: 'Retrieves a queued Google images result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_images_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/images/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/images/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Images SERP description: 'Returns the image results for a keyword on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_images_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language device: type: string description: 'Device type: desktop or mobile' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/images/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/images/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Images SERP HTML description: 'Returns the image results for a keyword on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_images_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language device: type: string description: 'Device type: desktop or mobile' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/images/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/search_by_image/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Search By Image SERP Tasks description: 'Queues the pages Google finds for an image URL on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_search_by_image_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: image_url: type: string description: Publicly accessible image URL used as the search input location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; possible values include advanced and html required: - image_url tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/search_by_image/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/search_by_image/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Search By Image SERP Completed Tasks description: 'Lists finished Google search by image tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_search_by_image_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting SERP HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/search_by_image/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/search_by_image/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Search By Image SERP Advanced Results by id description: 'Retrieves a queued Google search by image result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_search_by_image_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/search_by_image/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/search_by_image/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Search By Image HTML Results by id description: 'Retrieves a queued Google search by image result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_search_by_image_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/search_by_image/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/jobs/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Jobs Locations for SERP API description: 'Returns the job listings Google surfaces for a query on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_jobs_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/jobs/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/jobs/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Jobs Tasks description: 'Queues the job listings Google surfaces for a query on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_jobs_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_code: type: integer description: Search engine location code location_name: type: string description: Full name of search engine location location_coordinate: type: string description: GPS coordinates of a location language_code: type: string description: Search engine language code language_name: type: string description: Full name of search engine language priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; possible values include advanced and html required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/jobs/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/jobs/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Jobs SERP Completed Tasks description: 'Lists finished Google jobs tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_jobs_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].se: type: string description: Search engine specified when setting the task tasks[].result[].se_type: type: string description: Type of search engine tasks[].result[].date_posted: type: string description: Date when the task was posted in UTC format tasks[].result[].tag: type: string description: User-defined task identifier tasks[].result[].endpoint_advanced: type: string description: URL for collecting SERP Advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting SERP HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/jobs/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/jobs/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Jobs Advanced Results by id description: 'Retrieves a queued Google jobs result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_jobs_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/jobs/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/jobs/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Jobs HTML Results by id description: 'Retrieves a queued Google jobs result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_jobs_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/jobs/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/autocomplete/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Autocomplete Tasks description: 'Queues the suggestions Google offers as a query is typed on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_autocomplete_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to get autocomplete suggestions for client: type: string description: Search client for autocomplete, such as chrome, chrome-omni, gws-wiz, safari, firefox, img, or youtube location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/autocomplete/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/autocomplete/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Autocomplete SERP Completed Tasks description: 'Lists finished Google autocomplete tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_autocomplete_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/autocomplete/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/autocomplete/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Autocomplete Advanced Results by id description: 'Retrieves a queued Google autocomplete result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_autocomplete_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/autocomplete/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/autocomplete/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.004 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Autocomplete Advanced description: 'Returns the suggestions Google offers as a query is typed on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_autocomplete_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to get autocomplete suggestions for client: type: string description: Search client for autocomplete location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/autocomplete/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_search/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Dataset Search Tasks description: 'Queues datasets matching a query in Google Dataset Search on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_dataset_search_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search datasets for language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code os: type: string description: Device operating system, such as windows or macos last_updated: type: string description: Last time the dataset was updated, such as 1m, 1y, or 3y file_formats: type: array items: type: string description: Dataset file formats, such as other, archive, text, image, document, or tabular usage_rights: type: string description: Usage rights, such as commercial or noncommercial priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_search/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_search/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Dataset Search SERP Completed Tasks description: 'Lists finished Google dataset search tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_dataset_search_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_search/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_search/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Dataset Search Advanced Results by id description: 'Retrieves a queued Google dataset search result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_dataset_search_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_search/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_search/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Dataset Search Advanced description: 'Returns datasets matching a query in Google Dataset Search on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_dataset_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search datasets for language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code os: type: string description: Device operating system last_updated: type: string description: Last updated filter file_formats: type: array items: type: string description: Dataset file formats usage_rights: type: string description: Usage rights filter required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_search/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Dataset Info Tasks description: 'Queues one dataset''s record in Google Dataset Search on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_dataset_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: dataset_id: type: string description: ID of the dataset; you can find it in the dataset URL or in a Google Dataset Search result language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type; possible value: desktop' priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' required: - dataset_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_info/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Dataset Info SERP Completed Tasks description: 'Lists finished Google dataset info tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_dataset_info_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_info/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_info/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Dataset Info Advanced Results by id description: 'Retrieves a queued Google dataset info result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_dataset_info_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_info/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/dataset_info/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Dataset Info Advanced description: 'Returns one dataset''s record in Google Dataset Search on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_dataset_info_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: dataset_id: type: string description: ID of the dataset language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type; possible value: desktop' required: - dataset_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/dataset_info/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_advertisers/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Ads Advertisers Locations for SERP API description: 'Returns the advertisers matching a query in Google''s ads transparency data on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_gads_advertisers_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].country_iso_code: type: string description: Country ISO code tasks[].result[].location_type: type: string description: Location type '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_advertisers/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_advertisers/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Ads Advertisers SERP Tasks description: 'Queues the advertisers matching a query in Google''s ads transparency data on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_gads_advertisers_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search advertisers for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; only advanced is supported required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_advertisers/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_advertisers/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Ads Advertisers SERP Completed Tasks description: 'Lists finished Google ads advertisers tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_gads_advertisers_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_advertisers/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_advertisers/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Ads Advertisers Advanced Results by id description: 'Retrieves a queued Google ads advertisers result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_gads_advertisers_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].result: type: array items: type: string description: Array of advanced SERP results tasks[].result[].items: type: array items: type: string description: Array of advertisers or domains returned in SERP '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_advertisers/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_advertisers/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Ads Advertisers Advanced description: 'Returns the advertisers matching a query in Google''s ads transparency data on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_gads_advertisers_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search advertisers for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_advertisers/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_search/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Google Ads Search Locations for SERP API description: 'Returns the ads running against a keyword on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_gads_search_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_search/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_search/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Ads Search SERP Tasks description: 'Queues the ads running against a keyword on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_gads_search_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: advertiser_ids: type: array items: type: string description: Advertiser identifiers; required if target is not specified target: type: string description: Domain name associated with an advertiser account; required if advertiser_ids is not specified location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code location_coordinate: type: string description: GPS coordinates of a location priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: Postback datatype; only advanced is supported anyOf: - required: - advertiser_ids - required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_search/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_search/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Ads Search SERP Completed Tasks description: 'Lists finished Google ads search tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_gads_search_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_search/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_search/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Ads Search Advanced Results by id description: 'Retrieves a queued Google ads search result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_gads_search_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_search/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/ads_search/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Ads Search Advanced description: 'Returns the ads running against a keyword on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_gads_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: advertiser_ids: type: array items: type: string description: Advertiser identifiers; required if target is not specified target: type: string description: Domain name associated with an advertiser account; required if advertiser_ids is not specified location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code location_coordinate: type: string description: GPS coordinates of a location anyOf: - required: - advertiser_ids - required: - target tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/ads_search/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_explore/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Finance Explore SERP Tasks description: 'Queues the instruments Google Finance groups under a theme on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_finance_explore_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type; possible value: desktop' priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: advanced, html' tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_explore/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_explore/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Finance Explore SERP Completed Tasks description: 'Lists finished Google finance explore tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_finance_explore_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_explore/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_explore/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Explore Advanced Results by id description: 'Retrieves a queued Google finance explore result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_explore_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_explore/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_explore/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Explore HTML Results by id description: 'Retrieves a queued Google finance explore result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_explore_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_explore/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_explore/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.004 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Explore Advanced description: 'Returns the instruments Google Finance groups under a theme on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_explore_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type; possible value: desktop' tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_explore/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_explore/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.004 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Explore SERP HTML description: 'Returns the instruments Google Finance groups under a theme on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_explore_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: false content: application/json: schema: type: array items: type: object properties: location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: 'Device type; possible value: desktop' tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_explore/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_markets/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.0012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Finance Markets SERP Tasks description: 'Queues the market indexes and movers Google Finance lists on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_finance_markets_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code market_type: type: string description: Market type for the Markets tab priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: advanced, html' required: - market_type tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_markets/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_markets/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0 max: 0.0 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Finance Markets SERP Completed Tasks description: 'Lists finished Google finance markets tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_finance_markets_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_markets/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_markets/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.0012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Markets Advanced Results by id description: 'Retrieves a queued Google finance markets result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_markets_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_markets/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_markets/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0 max: 0.0 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Markets HTML Results by id description: 'Retrieves a queued Google finance markets result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_markets_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_markets/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_markets/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Markets Advanced description: 'Returns the market indexes and movers Google Finance lists on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_markets_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code market_type: type: string description: Market type for the Markets tab required: - market_type tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_markets/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_markets/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Markets SERP HTML description: 'Returns the market indexes and movers Google Finance lists on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_markets_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code market_type: type: string description: Market type for the Markets tab required: - market_type tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_markets/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_quote/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Finance Quote SERP Tasks description: 'Queues a ticker''s quote as Google Finance shows it on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_finance_quote_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Ticker or stock symbol location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code os: type: string description: Device operating system window: type: string description: Time window for the quote graph, such as 1D, 5D, 1M, 6M, YTD, 1Y, 5Y, or MAX priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_quote/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_quote/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Finance Quote SERP Completed Tasks description: 'Lists finished Google finance quote tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_finance_quote_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_quote/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_quote/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Quote Advanced Results by id description: 'Retrieves a queued Google finance quote result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_quote_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_quote/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_quote/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Quote HTML Results by id description: 'Retrieves a queued Google finance quote result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_quote_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_quote/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_quote/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Quote Advanced description: 'Returns a ticker''s quote as Google Finance shows it on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_quote_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Ticker or stock symbol location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code os: type: string description: Device operating system window: type: string description: Time window for the quote graph required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_quote/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_quote/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Quote SERP HTML description: 'Returns a ticker''s quote as Google Finance shows it on Google, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_quote_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Ticker or stock symbol location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code os: type: string description: Device operating system window: type: string description: Time window for the quote graph required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_quote/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_ticker_search/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Google Finance Ticker Search Tasks description: 'Queues tickers matching a query in Google Finance on Google, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_google_finance_ticker_search_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Company or financial instrument name location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_ticker_search/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_ticker_search/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Finance Ticker Search SERP Completed Tasks description: 'Lists finished Google finance ticker search tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_google_finance_ticker_search_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_ticker_search/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_ticker_search/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Google Finance Ticker Search Results by id description: 'Retrieves a queued Google finance ticker search result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_google_finance_ticker_search_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_ticker_search/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/google/finance_ticker_search/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Google Finance Ticker Search Advanced description: 'Returns tickers matching a query in Google Finance on Google, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_google_finance_ticker_search_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Company or financial instrument name location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/google/finance_ticker_search/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Bing Locations for SERP description: 'The locations the Bing SERP endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 42 MB on the YouTube list, and the Google-side catalogues elsewhere in this provider run 40-46 MB** - every city and region on earth. Do not call this from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s documentation. Free upstream, so nothing bills and nothing warns before it lands.' operationId: get_dataforseo_serp_bing_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Bing Languages for SERP description: 'The languages the Bing SERP endpoints accept, as `language_name` and `language_code`. Free: upstream cost is 0. Reference data - fetch once and reuse. The location list for Bing is far larger and should not be fetched at all; see its own description.' operationId: get_dataforseo_serp_bing_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available languages tasks[].result[].language_name: type: string description: Language name tasks[].result[].language_code: type: string description: Language code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Bing Organic SERP Tasks description: 'Queues the ranked results for a keyword on Bing, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_bing_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: regular, advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished Bing organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_bing_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_regular: type: string description: URL for collecting regular results tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Bing Organic SERP Results by id（regular） description: 'Retrieves a queued Bing organic result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_bing_organic_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Bing Organic SERP Results by id（advanced） description: 'Retrieves a queued Bing organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_bing_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Bing Organic HTML Results by id description: 'Retrieves a queued Bing organic result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_bing_organic_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Bing Organic SERP HTML description: 'Returns the ranked results for a keyword on Bing, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_bing_organic_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/live/regular: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Bing Organic SERP Regular description: 'Returns the ranked results for a keyword on Bing, synchronously. The lighter parse: measured at 4.8 KB against 57 KB for `advanced`, carrying the ranked list without the surrounding SERP features. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_bing_organic_live_regular responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/live/regular source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/bing/organic/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Bing Organic SERP Advanced description: 'Returns the ranked results for a keyword on Bing, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_bing_organic_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/bing/organic/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Youtube Locations for SERP description: 'The locations the YouTube SERP endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 42 MB on the YouTube list, and the Google-side catalogues elsewhere in this provider run 40-46 MB** - every city and region on earth. Do not call this from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s documentation. Free upstream, so nothing bills and nothing warns before it lands.' operationId: get_dataforseo_serp_youtube_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Youtube Languages for SERP description: 'The languages the YouTube SERP endpoints accept, as `language_name` and `language_code`. Free: upstream cost is 0. Reference data - fetch once and reuse. The location list for YouTube is far larger and should not be fetched at all; see its own description.' operationId: get_dataforseo_serp_youtube_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available languages tasks[].result[].language_name: type: string description: Language name tasks[].result[].language_code: type: string description: Language code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_info/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0036 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting YouTube Video Info Tasks description: 'Queues one YouTube video''s metadata on YouTube, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_youtube_video_info_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: video_id: type: string description: ID of the video location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type; only desktop is supported priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' required: - video_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_info/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_info/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Video Info SERP Completed Tasks description: 'Lists finished YouTube video info tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_youtube_video_info_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_info/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_info/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0036 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get YouTube Video Info Results by id description: 'Retrieves a queued YouTube video info result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_youtube_video_info_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_info/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_info/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live YouTube Video Info Advanced description: 'Returns one YouTube video''s metadata on YouTube, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_youtube_video_info_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: video_id: type: string description: ID of the video location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type; only desktop is supported required: - video_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_info/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting YouTube Organic Tasks description: 'Queues the ranked results for a keyword on YouTube, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_youtube_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished YouTube organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_youtube_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get YouTube Organic Results by id description: 'Retrieves a queued YouTube organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_youtube_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/organic/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live YouTube Organic Advanced description: 'Returns the ranked results for a keyword on YouTube, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_youtube_organic_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/organic/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_subtitles/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0036 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting YouTube Subtitles Tasks description: 'Queues one YouTube video''s subtitle track on YouTube, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_youtube_video_subtitles_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: video_id: type: string description: ID of the video language_code: type: string description: YouTube interface language code, for example en. Provide this or language_name. priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' location_code: type: integer description: YouTube location code, for example 2840. Provide this or location_name. location_name: type: string description: YouTube location name, for example United States. Provide this or location_code. language_name: type: string description: YouTube interface language name, for example English. Provide this or language_code. required: - video_id allOf: - anyOf: - required: - location_code - required: - location_name - anyOf: - required: - language_code - required: - language_name - anyOf: - not: required: - postback_url - required: - postback_data example: - language_code: en video_id: aircAruvnKk location_code: 2840 tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_subtitles/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_subtitles/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Video Subtitles SERP Completed Tasks description: 'Lists finished YouTube video subtitles tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_youtube_video_subtitles_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_subtitles/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_subtitles/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0036 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get YouTube Subtitles Results by id description: 'Retrieves a queued YouTube video subtitles result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_youtube_video_subtitles_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_subtitles/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_subtitles/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live YouTube Subtitles Advanced description: 'Returns one YouTube video''s subtitle track on YouTube, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_youtube_video_subtitles_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: video_id: type: string description: ID of the video language_code: type: string description: YouTube interface language code, for example en. Provide this or language_name. location_code: type: integer description: YouTube location code, for example 2840. Provide this or location_name. location_name: type: string description: YouTube location name, for example United States. Provide this or location_code. language_name: type: string description: YouTube interface language name, for example English. Provide this or language_code. required: - video_id allOf: - anyOf: - required: - location_code - required: - location_name - anyOf: - required: - language_code - required: - language_name example: - language_code: en video_id: aircAruvnKk location_code: 2840 tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_subtitles/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_comments/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting YouTube Comments Tasks description: 'Queues the comments on one YouTube video on YouTube, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_youtube_video_comments_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: video_id: type: string description: ID of the video priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible value: advanced' location_code: type: integer description: YouTube location code, for example 2840. Provide this or location_name. location_name: type: string description: YouTube location name, for example United States. Provide this or location_code. language_code: type: string description: YouTube interface language code, for example en. Provide this or language_name. language_name: type: string description: YouTube interface language name, for example English. Provide this or language_code. required: - video_id allOf: - anyOf: - required: - location_code - required: - location_name - anyOf: - required: - language_code - required: - language_name - anyOf: - not: required: - postback_url - required: - postback_data example: - video_id: aircAruvnKk location_code: 2840 language_code: en tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_comments/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_comments/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Video Comments SERP Completed Tasks description: 'Lists finished YouTube video comments tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_youtube_video_comments_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_comments/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_comments/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get YouTube Comments Results by id description: 'Retrieves a queued YouTube video comments result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_youtube_video_comments_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_comments/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/youtube/video_comments/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live YouTube Comments Advanced description: 'Returns the comments on one YouTube video on YouTube, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_youtube_video_comments_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of live SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: video_id: type: string description: ID of the video location_code: type: integer description: YouTube location code, for example 2840. Provide this or location_name. location_name: type: string description: YouTube location name, for example United States. Provide this or location_code. language_code: type: string description: YouTube interface language code, for example en. Provide this or language_name. language_name: type: string description: YouTube interface language name, for example English. Provide this or language_code. required: - video_id allOf: - anyOf: - required: - location_code - required: - location_name - anyOf: - required: - language_code - required: - language_name example: - video_id: aircAruvnKk location_code: 2840 language_code: en tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/youtube/video_comments/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Baidu Locations for SERP description: 'The locations the Baidu SERP endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 42 MB on the YouTube list, and the Google-side catalogues elsewhere in this provider run 40-46 MB** - every city and region on earth. Do not call this from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s documentation. Free upstream, so nothing bills and nothing warns before it lands.' operationId: get_dataforseo_serp_baidu_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Baidu Languages for SERP description: 'The languages the Baidu SERP endpoints accept, as `language_name` and `language_code`. Free: upstream cost is 0. Reference data - fetch once and reuse. The location list for Baidu is far larger and should not be fetched at all; see its own description.' operationId: get_dataforseo_serp_baidu_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available languages tasks[].result[].language_name: type: string description: Language name tasks[].result[].language_code: type: string description: Language code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Baidu Organic SERP Tasks description: 'Queues the ranked results for a keyword on Baidu, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_baidu_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: regular, advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished Baidu organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_baidu_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_regular: type: string description: URL for collecting regular results tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/organic/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Baidu Organic SERP Results by id（regular） description: 'Retrieves a queued Baidu organic result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_baidu_organic_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/organic/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Baidu Organic SERP Advanced Results by id description: 'Retrieves a queued Baidu organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_baidu_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/baidu/organic/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Baidu Organic HTML Results by id description: 'Retrieves a queued Baidu organic result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_baidu_organic_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/baidu/organic/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Yahoo Locations for SERP description: 'The locations the Yahoo SERP endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 42 MB on the YouTube list, and the Google-side catalogues elsewhere in this provider run 40-46 MB** - every city and region on earth. Do not call this from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s documentation. Free upstream, so nothing bills and nothing warns before it lands.' operationId: get_dataforseo_serp_yahoo_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Yahoo Languages for SERP description: 'The languages the Yahoo SERP endpoints accept, as `language_name` and `language_code`. Free: upstream cost is 0. Reference data - fetch once and reuse. The location list for Yahoo is far larger and should not be fetched at all; see its own description.' operationId: get_dataforseo_serp_yahoo_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available languages tasks[].result[].language_name: type: string description: Language name tasks[].result[].language_code: type: string description: Language code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0021 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Yahoo Organic SERP Tasks description: 'Queues the ranked results for a keyword on Yahoo, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_yahoo_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: regular, advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished Yahoo organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_yahoo_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_regular: type: string description: URL for collecting regular results tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0021 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Yahoo Organic SERP Advanced Results by id description: 'Retrieves a queued Yahoo organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_yahoo_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Yahoo Organic HTML Results by id description: 'Retrieves a queued Yahoo organic result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_yahoo_organic_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Yahoo Organic SERP Results by id（regular） description: 'Retrieves a queued Yahoo organic result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_yahoo_organic_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/live/regular: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Yahoo Organic SERP Regular description: 'Returns the ranked results for a keyword on Yahoo, synchronously. The lighter parse: measured at 4.8 KB against 57 KB for `advanced`, carrying the ranked list without the surrounding SERP features. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_yahoo_organic_live_regular responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/live/regular source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/live/advanced: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Yahoo Organic SERP Advanced description: 'Returns the ranked results for a keyword on Yahoo, synchronously. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Measured at 57 KB for a ten-result Google query. ⚠️ Three result depths exist for the same query and differ by two orders of magnitude: `regular` measured 4.8 KB, `advanced` 57 KB, and `html` **2.4 MB**. `advanced` is the default choice; take `regular` when only the ranked list matters and `html` only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_yahoo_organic_live responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/live/advanced source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/yahoo/organic/live/html: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.004 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Live Yahoo Organic SERP HTML description: 'Returns the ranked results for a keyword on Yahoo, synchronously. Raw page source rather than parsed results. 🔴 **Measured at 2.4 MB for a ten-result Google query, against 57 KB parsed** - take it only to check what the parser dropped. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_yahoo_organic_live_html responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/yahoo/organic/live/html source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/locations: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Seznam Locations for SERP description: 'The locations the Seznam SERP endpoints accept, as `location_code`, `location_name`, `location_code_parent`, `country_iso_code` and `location_type`. 🔴 **Measured at 42 MB on the YouTube list, and the Google-side catalogues elsewhere in this provider run 40-46 MB** - every city and region on earth. Do not call this from an agent: `location_code` 2840 is the United States, and other codes belong in DataForSEO''s documentation. Free upstream, so nothing bills and nothing warns before it lands.' operationId: get_dataforseo_serp_seznam_locations responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available locations tasks[].result[].location_code: type: integer description: Location code tasks[].result[].location_name: type: string description: Location name tasks[].result[].location_code_parent: type: integer description: Parent location code tasks[].result[].country_iso_code: type: string description: Country ISO code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/locations source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/languages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: List of Seznam Languages for SERP description: 'The languages the Seznam SERP endpoints accept, as `language_name` and `language_code`. Free: upstream cost is 0. Reference data - fetch once and reuse. The location list for Seznam is far larger and should not be fetched at all; see its own description.' operationId: get_dataforseo_serp_seznam_languages responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of available languages tasks[].result[].language_name: type: string description: Language name tasks[].result[].language_code: type: string description: Language code '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/languages source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Seznam Organic SERP Tasks description: 'Queues the ranked results for a keyword on Seznam, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_seznam_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: regular, advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0 max: 0.0 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished Seznam organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_seznam_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_regular: type: string description: URL for collecting regular results tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/organic/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Seznam Organic SERP Results by id（regular） description: 'Retrieves a queued Seznam organic result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_seznam_organic_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/organic/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Seznam Organic SERP Advanced Results by id description: 'Retrieves a queued Seznam organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_seznam_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/seznam/organic/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Seznam Organic HTML Results by id description: 'Retrieves a queued Seznam organic result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_seznam_organic_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/seznam/organic/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/naver/organic/task_post: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Setting Naver Organic SERP Tasks description: 'Queues the ranked results for a keyword on Naver, returning a task `id` in `tasks[0].id`. The charge lands here; fetching is free, including re-fetching. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. The live twin answers immediately and is simpler for a single query; queue when the batch would outlast a tool call.' operationId: post_dataforseo_serp_naver_organic_submit responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of task objects tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].cost: type: number description: Cost of the task, USD tasks[].result_count: type: integer description: Number of elements in the result array '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: keyword: type: string description: Keyword to search for location_name: type: string description: Full name of search engine location location_code: type: integer description: Search engine location code language_name: type: string description: Full name of search engine language language_code: type: string description: Search engine language code device: type: string description: Device type os: type: string description: Device operating system depth: type: integer description: Parsing depth priority: type: integer description: Task priority postback_url: type: string description: URL for sending task results pingback_url: type: string description: Notification URL of a completed task postback_data: type: string description: 'Postback datatype; possible values: regular, advanced, html' required: - keyword tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/naver/organic/task_post source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/naver/organic/tasks_ready: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Organic SERP Completed Tasks description: 'Lists finished Naver organic tasks awaiting collection. Free. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Rarely needed: a caller holds the `id` its own submit returned and can fetch directly. This answers what is ready across the whole account.' operationId: get_dataforseo_serp_naver_organic_ready responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of completed task references tasks[].result[].id: type: string description: Task identifier of the completed task tasks[].result[].endpoint_regular: type: string description: URL for collecting regular results tasks[].result[].endpoint_advanced: type: string description: URL for collecting advanced results tasks[].result[].endpoint_html: type: string description: URL for collecting HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/naver/organic/tasks_ready source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/naver/organic/task_get/regular/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Naver Organic SERP Results by id（regular） description: 'Retrieves a queued Naver organic result by `id`, lightly parsed - measured at 4.8 KB against 57 KB for the advanced form. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_naver_organic_fetch_regular parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of regular SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/naver/organic/task_get/regular/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/naver/organic/task_get/advanced/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.0012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Naver Organic SERP Advanced Results by id description: 'Retrieves a queued Naver organic result by `id`. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_naver_organic_fetch parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of advanced SERP results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/naver/organic/task_get/advanced/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/naver/organic/task_get/html/{id}: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Get Naver Organic HTML Results by id description: 'Retrieves a queued Naver organic result by `id` as raw HTML. 🔴 Measured at 2.4 MB against 57 KB parsed on the Google organic pair. Free - the charge was on the submit. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: get_dataforseo_serp_naver_organic_fetch_html parameters: - name: id in: path required: true schema: type: string description: Task identifier in UUID format responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total tasks cost, USD tasks_count: type: integer description: The number of tasks in the tasks array tasks_error: type: integer description: The number of tasks in the tasks array returned with an error tasks: type: array items: type: string description: Array of tasks tasks[].result: type: array items: type: string description: Array of HTML results '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/naver/organic/task_get/html/{id} source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/ai_summary: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.02 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: SERP API AI Summary description: 'Returns the AI overview Google shows above the results for a query on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_ai_summary responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total task cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].path: type: array items: type: string description: URL path tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of results tasks[].result[].items_count: type: integer description: Number of items in the result array tasks[].result[].items: type: array items: type: string description: Items array tasks[].result[].items[].summary: type: string description: Generated summary '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: task_id: type: string description: Unique identifier of the associated task in UUID format; can be used within 30 days prompt: type: string description: Additional AI prompt; maximum 2000 characters support_extra: type: boolean description: Whether to consider extra SERP features such as answer_box, knowledge_graph, and featured_snippet; default true fetch_content: type: boolean description: Whether to fetch content from pages in SERPs; default false include_links: type: boolean description: Whether to include source links in the summary; default false required: - task_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/ai_summary source: https://github.com/AIsa-team/aisa-proxy /dataforseo/serp/screenshot: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.008 max: 0.012 cost_drivers: - param: result/task count effect: charge scales with number of results/tasks the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: SERP API Page Screenshot description: 'Returns a rendered screenshot of a search result page on Google. Returns `keyword`, `type`, `se_domain`, `location_code`, `language_code`, `check_url`, `datetime`, `spell`, `refinement_chips`, `item_types`, `items_count` and `items`. 💰 Measured at $0.002 upstream against the $0.012 billed - this family is the cheapest source of search data here, six times under the flat rate. Wrapped in DataForSEO''s envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200.' operationId: post_dataforseo_serp_screenshot responses: '200': description: Successful response content: application/json: schema: type: object properties: version: type: string description: The current version of the API status_code: type: integer description: General status code status_message: type: string description: General informational message time: type: string description: Execution time, seconds cost: type: number description: Total task cost, USD tasks: type: array items: type: string description: Array of tasks tasks[].id: type: string description: Task identifier in UUID format tasks[].status_code: type: integer description: Task status code tasks[].status_message: type: string description: Task status message tasks[].result_count: type: integer description: Number of elements in the result array tasks[].path: type: array items: type: string description: URL path tasks[].data: type: object description: Contains the same parameters specified in the POST request tasks[].result: type: array items: type: string description: Array of results tasks[].result[].items_count: type: integer description: Number of items in the results array tasks[].result[].items: type: array items: type: string description: Items array tasks[].result[].items[].image: type: string description: URL of the page screenshot on DataForSEO storage '400': description: Bad request '401': description: Unauthorized '429': description: Rate limit exceeded '500': description: Internal server error requestBody: required: true content: application/json: schema: type: array items: type: object properties: task_id: type: string description: Unique identifier of the associated task in UUID format; can be used within 7 days browser_preset: type: string description: 'Browser resolution preset: desktop, tablet, or mobile' browser_screen_width: type: integer description: Browser resolution width; range 240-9999 browser_screen_height: type: integer description: Browser resolution height; range 240-9999 browser_screen_scale_factor: type: number description: Browser scale factor; range 0.5-3 page: type: integer description: SERP page number to screenshot; default 1 required: - task_id tags: - SEO & Search Data x-x402: path: /apis/v2/dataforseo/serp/screenshot source: https://github.com/AIsa-team/aisa-proxy /edinet/documents.json: get: x-aisa-pricing: model: per_request currency: USD price_usd: 1.0e-05 cost_tier: low summary: List EDINET documents description: Lists every disclosure filed with Japan's EDINET on one date. date is required (YYYY-MM-DD). type=2 returns the filings under results — docID, filerName, secCode, JCN, docTypeCode, docDescription, submitDateTime, periodStart and periodEnd per filing — while type=1 returns metadata only, with the day's count under metadata.resultset.count and no results array. Measured at 612 KB for a typical business day (648 filings), and there are no filter parameters, so type=2 always returns the whole day; check the count with type=1 first when in doubt. About two thirds of filings carry a secCode (listed companies), the rest are funds and unlisted filers. A filing's docID feeds get_edinet_document_download. operationId: get_edinet_documents tags: - Financial Data parameters: - name: date in: query required: true schema: type: string format: date examples: - '2026-07-23' description: File date in YYYY-MM-DD format. - name: type in: query required: false schema: type: integer enum: - 1 - 2 default: 1 description: 'Response mode: 1 for metadata only, 2 for metadata plus filing list.' responses: '200': description: EDINET document-list response. content: application/json: schema: type: object properties: metadata: type: object description: Metadata object with title, request parameter echo, result count, processDateTime, status, and message. results: type: array description: Filing document objects when type=2. items: type: object properties: seqNumber: type: integer docID: type: string filerName: type: string docTypeCode: type: string submitDateTime: type: string '400': description: Invalid request parameters. '401': description: Invalid or missing AIsa API key. '429': description: Rate limit exceeded. '500': description: Gateway or upstream failure. x-aisa-path: /apis/v1/edinet/documents.json x-provider-cost-micros-usd: 0 x-customer-pricing: normal: 1.0e-05 x-x402: path: /apis/v2/edinet/documents.json source: https://github.com/AIsa-team/aisa-proxy /edinet/documents/{docID}: get: x-aisa-pricing: model: per_request currency: USD price_usd: 1.0e-05 cost_tier: low summary: Download an EDINET document description: 'Downloads one filing by docID, taken from get_edinet_documents. The success response is a binary file, not JSON: type=1 returns the filing body and audit report as a ZIP archive (measured 11.9 KB, content-type application/octet-stream), type=2 the PDF (measured 15.0 KB, application/pdf). Errors still come back as JSON, so check the response content type before parsing. Because a tool result cannot usefully carry a binary payload, this endpoint stays REST-only: over MCP, stop at the docID from get_edinet_documents and fetch the file over REST.' operationId: get_edinet_document_download tags: - Financial Data parameters: - name: docID in: path required: true schema: type: string examples: - S1000000 description: Document management identifier from the document list API. - name: type in: query required: true schema: type: integer enum: - 1 - 2 - 3 - 4 - 5 description: 'File type to download: 1 for filing body and audit report ZIP, 2 for PDF, 3 for alternate document and attachments ZIP, 4 for English document ZIP, 5 for CSV ZIP converted from XBRL.' responses: '200': description: Binary ZIP/PDF file content or JSON error payload depending on Content-Type. content: application/octet-stream: schema: type: string format: binary application/pdf: schema: type: string format: binary application/json: schema: type: object properties: message: type: string '400': description: Invalid request parameters. '401': description: Invalid or missing AIsa API key. '404': description: Document not found. '429': description: Rate limit exceeded. '500': description: Gateway or upstream failure. x-aisa-path: /apis/v1/edinet/documents/{docID} x-provider-cost-micros-usd: 0 x-customer-pricing: normal: 1.0e-05 x-x402: path: /apis/v2/edinet/documents/{docID} source: https://github.com/AIsa-team/aisa-proxy /exa/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.08 observed_usd: min: 0.007 p50: 0.007 p95: 0.08 max: 0.1 cost_drivers: - param: numResults / contents effect: charge scales with number of results and content pulls returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Run a neural semantic web search. description: 'Search the web by meaning rather than by keyword. `query` is required; narrow with `category`, `includeDomains`, `excludeDomains`, `startPublishedDate`, `endPublishedDate`, and set `numResults`. Returns `requestId`, `resolvedSearchType`, `searchTime`, `costDollars` and `results[]` with `id`, `title` and `url`. **`id` is the URL**, and it is what `post_exa_contents` takes. Measured at 1.4 seconds — the fastest search here. Billed a flat $0.08 per successful request. ⚠️ Results carry **no page text** unless you ask: pass `contents`, or follow up with `post_exa_contents`. Choose it over `post_tavily_search` when the query is a description rather than keywords; choose Tavily when you want the text in the same call, and `post_exa_answer` when you want a written answer rather than a list.' requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: The natural-language search query. example: latest evaluation frameworks for AI agents type: type: string enum: - auto - fast - instant - deep-lite - deep - deep-reasoning default: auto description: Search mode. auto lets Exa choose; the deep modes trade latency for higher-quality retrieval. numResults: type: integer minimum: 1 maximum: 100 default: 10 description: Number of results to return. category: type: string enum: - company - research paper - news - personal site - financial report - people description: Optional hint about the kind of pages to prioritize. includeDomains: type: array items: type: string description: Only return results from these domains. excludeDomains: type: array items: type: string description: Exclude results from these domains. startPublishedDate: type: string format: date-time description: Only return results published on or after this ISO 8601 date. endPublishedDate: type: string format: date-time description: Only return results published on or before this ISO 8601 date. contents: type: object description: Content options to return alongside each result. properties: text: type: boolean description: Return the full page text. highlights: type: boolean description: Return highlighted relevant snippets. summary: type: boolean description: Return an AI-generated summary of the page. outputSchema: type: object description: JSON Schema used to synthesize a structured output from the results. systemPrompt: type: string description: Instruction that guides how the structured output is generated. required: - query responses: '200': description: Search completed successfully. content: application/json: schema: type: object properties: requestId: type: string description: Exa request identifier. results: type: array description: Ranked search results. items: type: object properties: title: type: string url: type: string publishedDate: type: string author: type: string id: type: string output: description: Structured output, present only when outputSchema was supplied. nullable: true costDollars: description: Upstream Exa cost breakdown. Informational only; customer billing is the flat $0.08. nullable: true operationId: post_exa_search x-x402: path: /apis/v2/exa/search source: https://github.com/AIsa-team/aisa-proxy /exa/contents: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.08 observed_usd: min: 0.001 p50: 0.1 p95: 0.1 max: 0.1 cost_drivers: - param: numResults / contents effect: charge scales with number of results and content pulls returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Extract full page contents for a set of URLs. description: Fetch page text and metadata for URLs you already have. `ids` is required and takes the `id` values from `post_exa_search` — which are plain URLs, so any URL works. Toggle `text`, `highlights`, `summary`, `subpages` and `livecrawl`. Returns `results[]` with `id`, `title`, `url`, `author` and `text`, plus a **`statuses[]` array giving per-URL `status` and `source`** — read it, because a URL that could not be fetched is reported there rather than raising. Cached results are served instantly; a miss falls back to a live crawl. Measured at 1.2 seconds. Billed a flat $0.08 per successful request. For a whole site rather than a URL list, `post_firecrawl_crawl`. requestBody: required: true content: application/json: schema: type: object properties: ids: type: array items: type: string description: The URLs (or Exa result ids) to fetch contents for. example: - https://example.com/article text: type: boolean description: Return the full page text. highlights: type: boolean description: Return highlighted relevant snippets. summary: type: boolean description: Return an AI-generated summary of the page. subpages: type: integer description: Number of linked subpages to also fetch. livecrawl: type: string enum: - always - fallback - never description: 'Freshness policy: always live-crawl, fall back to live crawl on cache miss, or never live-crawl.' required: - ids responses: '200': description: Contents fetched successfully. content: application/json: schema: type: object properties: requestId: type: string results: type: array items: type: object properties: title: type: string url: type: string publishedDate: type: string author: type: string id: type: string text: type: string highlights: type: array items: type: string summary: type: string operationId: post_exa_contents x-x402: path: /apis/v2/exa/contents source: https://github.com/AIsa-team/aisa-proxy /exa/answer: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.08 observed_usd: min: 0.005 p50: 0.005 p95: 0.1 max: 0.1 cost_drivers: - param: numResults / contents effect: charge scales with number of results and content pulls returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Get a direct, cited answer to a question. description: 'Ask a question and get a written answer with citations. `query` is required; `text` includes the source text and `outputSchema` shapes a structured reply. Returns `requestId`, `answer` as prose, `citations[]` with `id`, `title` and `url`, and `costDollars`. Measured at 2.1 seconds with 8 citations. Billed a flat $0.08 per successful request. It sits between a search and a research run: faster and cheaper than `post_exa_agent_runs`, and more direct than reading `post_exa_search` results yourself. `post_perplexity_sonar` answers the same shape of question for $0.012 — reach for Exa when the retrieval needs to be semantic.' requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: The question to answer. example: Which manufacturers had the top three global EV sales in 2025? text: type: boolean description: Include the full page text of each citation. type: type: string enum: - auto - fast - instant - deep-lite - deep - deep-reasoning description: Retrieval mode used to gather sources before answering. outputSchema: type: object description: JSON Schema for a structured answer output. required: - query responses: '200': description: Answer generated successfully. content: application/json: schema: type: object properties: requestId: type: string answer: description: The generated answer. A string, or a structured object when outputSchema was supplied. nullable: true citations: type: array description: Sources supporting the answer. items: type: object properties: id: type: string url: type: string title: type: string author: type: string publishedDate: type: string text: type: string costDollars: description: Upstream Exa cost breakdown. Informational only; customer billing is the flat $0.08. nullable: true operationId: post_exa_answer x-x402: path: /apis/v2/exa/answer source: https://github.com/AIsa-team/aisa-proxy /exa/agent/runs: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.1 cost_tier: med tags: - Other summary: Submit an asynchronous research Agent run. description: Hand a research task to an agent that works in the background. `query` and an `Idempotency-Key` are required; `effort` trades depth against time, `outputSchema` shapes the result, `dataSources` restricts where it looks, and `previousRunId` continues an earlier run. Asynchronous. Submitting returns HTTP 202 and a job envelope — `id`, `object`, `endpoint`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error` — with `output` still null. Poll `get_exa_agent_run` until terminal; `output` then carries `text`, `structured` and `grounding`. A one-sentence question completed in well under a minute. Billed a flat $0.10 per run — `pricing.billingMode` is `fixed_request`, so unlike a Firecrawl crawl the price does not grow with what it finds. Use it when a report is the deliverable. For an answer you read in one sitting, `post_exa_answer` returns in about two seconds. Send a fresh `Idempotency-Key` per distinct task. parameters: - in: header name: Idempotency-Key required: true schema: type: string maxLength: 191 description: Unique key (1 to 191 characters) that makes the submit idempotent. Re-submitting with the same key and request fingerprint returns the original run. requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: The natural-language research query. example: Summarize the main changes in RAG evaluation methods over the past year as a bullet list. outputSchema: type: object description: JSON Schema used to validate the structured output. input: type: object description: 'Row-processing input: rows to process and exclusions.' properties: data: type: array items: {} description: Input rows for the run. exclusion: description: Items to exclude from processing. effort: type: string description: Compute/depth tier for the run. previousRunId: type: string description: Continue from a previously completed run. dataSources: type: array items: {} description: Third-party data sources (Exa Connect) the Agent is granted access to. required: - query responses: '202': description: Research run accepted. The Location header points at the job resource; poll it until terminal. headers: Location: schema: type: string description: Path of the created job resource, e.g. /apis/v1/exa/agent/runs/{jobId}. content: application/json: schema: $ref: '#/components/schemas/AsyncJob' '409': description: idempotency_conflict — the same Idempotency-Key was reused with a different request body. operationId: post_exa_agent_runs x-x402: path: /apis/v2/exa/agent/runs source: https://github.com/AIsa-team/aisa-proxy /exa/agent/runs/{jobId}: get: tags: - Other summary: Poll a research Agent run. description: Fetch an Agent run submitted by `post_exa_agent_runs`, by its `jobId`. Returns the same envelope — `id`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error`. Repeat until `status` is `completed`, `failed` or `cancelled`; on success `output` carries `text`, `structured` and `grounding`. Reads a run only; it cannot start one. parameters: - in: path name: jobId required: true schema: type: string description: The job id returned by the submit call. responses: '200': description: The current state of the research run. content: application/json: schema: $ref: '#/components/schemas/AsyncJob' operationId: get_exa_agent_run x-x402: path: /apis/v2/exa/agent/runs/{jobId} source: https://github.com/AIsa-team/aisa-proxy /firecrawl/scrape: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 4.66853 nominal_usd: 0.005 observed_usd: min: 0.0011 p50: 0.005 p95: 0.005 max: 0.005 cost_drivers: - param: pages/results scraped effect: charge scales with number of pages/results the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Scrape a single page and return its main content as markdown. description: 'Fetch one URL and get its main content back as markdown. `url` and `proxy` are both required — `proxy` must be `basic` on the metered profile — and `formats` selects the output. Returns `success` and `data` with `markdown` plus a large `metadata` object carrying the page''s og: and twitter: tags, `statusCode`, `sourceURL` and `language`. Measured at about 10 seconds for one page. ⚠️ The URL must be HTTPS and must not point at a PDF; both are rejected rather than best-effort. Use it when you have the URL and want the text. For several URLs at once `post_firecrawl_batch_scrape` runs them as one background job, and `post_tavily_extract` does a small batch synchronously. To find URLs first, `post_firecrawl_map`.' requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: The HTTPS URL to scrape. PDF URLs are not supported on the metered profile. example: https://docs.firecrawl.dev proxy: type: string enum: - basic description: Proxy tier. Must be explicitly set to "basic" on the metered profile. example: basic formats: type: array items: type: string enum: - markdown description: Optional output formats. When present it must be exactly ["markdown"]. example: - markdown required: - url - proxy responses: '200': description: Scrape completed successfully. content: application/json: schema: type: object properties: success: type: boolean description: True when the scrape succeeded. data: type: object properties: markdown: type: string description: The scraped page content in markdown. metadata: type: object description: Page metadata such as title, description, source URL, and HTTP status. properties: title: type: string description: type: string sourceURL: type: string statusCode: type: integer creditsUsed: type: integer description: Firecrawl credits consumed by the request (1 per page). operationId: post_firecrawl_scrape x-x402: path: /apis/v2/firecrawl/scrape source: https://github.com/AIsa-team/aisa-proxy /firecrawl/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 4.66853 nominal_usd: 0.005 observed_usd: min: 0.0022 p50: 0.01 p95: 0.01 max: 0.01 cost_drivers: - param: pages/results scraped effect: charge scales with number of pages/results the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Run a web search and return ranked results. description: 'Search the web and get back ranked results. `query` is required; `limit` sets how many. Returns `success`, `creditsUsed`, a request `id`, and `data.web[]` with `url`, `title`, `description` and `position` — **titles and snippets only, no page text**. Measured at about 15 seconds for 2 results, the slowest of the search tools here. Billed per Firecrawl credit, roughly `ceil(limit / 10) * 2`. On the AIsa metered profile only the web source is supported; `scrapeOptions`, enterprise mode and non-web sources are rejected. Reach for something else when: you want the page text in the same call — `post_tavily_search` returns it and answers in a third of the time; you already know the URLs — `post_firecrawl_scrape`; you want relevance judged by meaning rather than keywords — `post_exa_search`.' requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: The search query. Must be non-empty and at most 500 characters. maxLength: 500 example: firecrawl web scraping api limit: type: integer default: 10 minimum: 1 maximum: 100 description: Maximum number of results to return. required: - query responses: '200': description: Search completed successfully. content: application/json: schema: type: object properties: success: type: boolean description: True when the search succeeded. data: type: object properties: web: type: array description: Ranked web search results. items: type: object properties: title: type: string description: Result title. url: type: string description: Result URL. description: type: string description: Result snippet. creditsUsed: type: integer description: Firecrawl credits consumed (about 2 per 10 results). operationId: post_firecrawl_search x-x402: path: /apis/v2/firecrawl/search source: https://github.com/AIsa-team/aisa-proxy /firecrawl/map: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 4.66853 nominal_usd: 0.005 observed_usd: min: 0.0011 p50: 0.025 p95: 0.5 max: 2.47 cost_drivers: - param: pages/results scraped effect: charge scales with number of pages/results the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Discover the URLs on a website. description: List the URLs reachable from a starting page, without fetching any content. `url` and `limit` are both required (limit 1 to 100000). Returns `success`, a request `id`, and `links[]` with `url` and `title` — note these are **objects with a title**, unlike `post_tavily_map` which returns bare strings. Measured at about 9 seconds. Billed 1 credit per discovered link, so `limit` is a cost control, not just a page control. Use it to size a site before paying to crawl it, then fetch only what matters with `post_firecrawl_scrape`. When you want content and structure in one pass, `post_firecrawl_crawl`. requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: The HTTPS URL to map. example: https://docs.firecrawl.dev limit: type: integer minimum: 1 maximum: 100000 description: Maximum number of links to discover. Required on the metered profile. example: 100 required: - url - limit responses: '200': description: Map completed successfully. content: application/json: schema: type: object properties: success: type: boolean description: True when the map succeeded. links: type: array description: Discovered links. items: type: object properties: url: type: string description: A discovered URL. title: type: string description: Title of the discovered page, when available. creditsUsed: type: integer description: Firecrawl credits consumed (1 per discovered link). operationId: post_firecrawl_map x-x402: path: /apis/v2/firecrawl/map source: https://github.com/AIsa-team/aisa-proxy /firecrawl/parse: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 4.66853 nominal_usd: 0.005 observed_usd: min: 0.0011 max: 0.005 cost_drivers: - param: pages/results scraped effect: charge scales with number of pages/results the provider returns cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Parse an uploaded HTML file into markdown. description: 'Parse an HTML file you upload and get markdown back. This is `multipart/form-data` with two fields: `file` (an HTML upload that must carry a `text/html` content type or an `.html`/`.htm` filename) and `options` (a JSON string that must set `proxy` to `basic`, may additionally set `formats` to `["markdown"]`, and is capped at 64 KB). Returns `success` and `data.markdown` with `metadata`. Billed 1 Firecrawl credit. ⚠️ **Not available as an MCP tool.** A tool call carries JSON, so the file arrives as a plain form field with no filename and upstream rejects it — verified. Over MCP use `post_firecrawl_scrape` with a URL instead. This endpoint is for HTTP clients that hold an actual file.' requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The HTML/HTM file to parse. Must have a text/html content type or an .html/.htm filename. options: type: string description: JSON string of parse options. Must include proxy="basic"; may additionally include formats=["markdown"]. No other keys are allowed. example: '{"proxy":"basic","formats":["markdown"]}' required: - file - options responses: '200': description: Parse completed successfully. content: application/json: schema: type: object properties: success: type: boolean description: True when the parse succeeded. data: type: object properties: markdown: type: string description: The parsed content in markdown. creditsUsed: type: integer description: Firecrawl credits consumed (1). operationId: post_firecrawl_parse x-x402: path: /apis/v2/firecrawl/parse source: https://github.com/AIsa-team/aisa-proxy /firecrawl/crawl: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost (metered per result unit) nominal_usd: 0.005 observed_usd: min: 0.0011 max: 0.25 cost_drivers: - param: pages/results returned effect: charge scales with provider-reported units (pages/results); metered_result billing cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Submit an asynchronous crawl job. description: Crawl a whole site rooted at `url` and return the content of every page it keeps. `url`, `limit` and an `Idempotency-Key` are required; steer it with `includePaths`, `excludePaths`, `maxDiscoveryDepth`, `crawlEntireDomain`, `allowSubdomains`, `delay` and `maxConcurrency`. Asynchronous. Submitting returns HTTP 202 and a job envelope — `id`, `object`, `endpoint`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error` — with `output` still null. Poll `get_firecrawl_crawl_job` until `status` is `completed`, `failed` or `cancelled`; `output` is then an array of pages, each with `markdown` and `metadata`. A 3-page crawl measured 43 KB and finished in under a minute, and `pricing.billingMode` is `metered_result`, so **cost scales with what it finds** — set `limit`. Send a fresh `Idempotency-Key` per distinct crawl; reusing one returns the earlier job instead of starting a new one. For a handful of known URLs `post_firecrawl_batch_scrape` is cheaper, and for structure alone `post_firecrawl_map` costs far less. parameters: - in: header name: Idempotency-Key required: true schema: type: string maxLength: 191 description: Unique key (1 to 191 characters) that makes the submit idempotent. Re-submitting with the same key returns the original job. requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: The HTTPS root URL to crawl. PDF URLs are not supported. example: https://docs.firecrawl.dev limit: type: integer minimum: 1 maximum: 1000 description: Maximum number of pages to crawl. example: 50 includePaths: type: array items: type: string maxLength: 256 maxItems: 20 description: Only crawl URLs whose path matches one of these patterns. excludePaths: type: array items: type: string maxLength: 256 maxItems: 20 description: Skip URLs whose path matches one of these patterns. maxDiscoveryDepth: type: integer minimum: 0 maximum: 10 description: Maximum link-discovery depth from the root URL. sitemap: type: string enum: - skip - include - only description: How the site's sitemap is used during discovery. ignoreQueryParameters: type: boolean description: Treat URLs that differ only by query string as the same page. crawlEntireDomain: type: boolean description: Crawl the whole domain rather than only the subtree under the root URL. allowExternalLinks: type: boolean description: Follow links to external domains. allowSubdomains: type: boolean description: Follow links into subdomains of the root domain. delay: type: number minimum: 0 maximum: 30 description: Delay in seconds between requests (0 to 30). maxConcurrency: type: integer minimum: 1 maximum: 20 description: Maximum number of concurrent page fetches (1 to 20). scrapeOptions: type: object description: Per-page scrape options applied while crawling. On the metered profile output is always markdown. properties: onlyMainContent: type: boolean description: Return only the main content of each page. default: true includeTags: type: array items: type: string maxLength: 128 maxItems: 50 description: HTML tags/selectors to keep. excludeTags: type: array items: type: string maxLength: 128 maxItems: 50 description: HTML tags/selectors to drop. maxAge: type: integer minimum: 0 maximum: 31536000000 description: Maximum acceptable cache age in milliseconds. minAge: type: integer minimum: 0 maximum: 31536000000 description: Minimum cache age in milliseconds before a page is refetched. timeout: type: integer minimum: 1000 maximum: 300000 description: Per-page timeout in milliseconds. required: - url - limit responses: '202': description: Crawl job accepted. The Location header points at the job resource; poll it until terminal. headers: Location: schema: type: string description: Path of the created job resource, e.g. /apis/v1/firecrawl/crawl/{jobId}. content: application/json: schema: $ref: '#/components/schemas/AsyncJob' operationId: post_firecrawl_crawl x-x402: path: /apis/v2/firecrawl/crawl source: https://github.com/AIsa-team/aisa-proxy /firecrawl/crawl/{jobId}: get: tags: - Other summary: Poll a crawl job. description: Fetch a crawl job submitted by `post_firecrawl_crawl`, by its `jobId`. Returns the same envelope the submission returned — `id`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error`. Repeat until `status` is `completed`, `failed` or `cancelled`; on success `output` is an array of pages with `markdown` and `metadata`. Polling is cheap and fast, measured under a second. This tool only reads a job — it cannot start one. parameters: - in: path name: jobId required: true schema: type: string description: The job id returned by the submit call. responses: '200': description: The current state of the crawl job. content: application/json: schema: $ref: '#/components/schemas/AsyncJob' operationId: get_firecrawl_crawl_job x-x402: path: /apis/v2/firecrawl/crawl/{jobId} source: https://github.com/AIsa-team/aisa-proxy /firecrawl/batch-scrape: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost (metered per result unit) nominal_usd: 0.005 observed_usd: min: 0.0011 max: 0.015 cost_drivers: - param: pages/results returned effect: charge scales with provider-reported units (pages/results); metered_result billing cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Other summary: Submit an asynchronous batch scrape job. description: Scrape many URLs as one background job. `urls` and an `Idempotency-Key` are required; `maxConcurrency`, `onlyMainContent`, `includeTags`, `excludeTags`, `maxAge`, `minAge` and `timeout` tune it. Asynchronous. Submitting returns HTTP 202 and a job envelope — `id`, `object`, `endpoint`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error` — with `output` still null. Poll `get_firecrawl_batch_scrape_job` until terminal; `output` is then an array of documents with `markdown` and `metadata`. Use it when you have a list of URLs and do not need them immediately. When you do need them immediately, `post_tavily_extract` returns a small batch synchronously in about a second; for a single page `post_firecrawl_scrape`. Send a fresh `Idempotency-Key` per distinct batch. parameters: - in: header name: Idempotency-Key required: true schema: type: string maxLength: 191 description: Unique key (1 to 191 characters) that makes the submit idempotent. Re-submitting with the same key returns the original job. requestBody: required: true content: application/json: schema: type: object properties: urls: type: array items: type: string format: uri minItems: 1 maxItems: 1000 description: 1 to 1000 unique HTTPS URLs to scrape. PDF URLs are not supported. example: - https://docs.firecrawl.dev - https://docs.firecrawl.dev/introduction maxConcurrency: type: integer minimum: 1 maximum: 20 description: Maximum number of concurrent scrapes (1 to 20). onlyMainContent: type: boolean description: Return only the main content of each page. default: true includeTags: type: array items: type: string maxLength: 128 maxItems: 50 description: HTML tags/selectors to keep. excludeTags: type: array items: type: string maxLength: 128 maxItems: 50 description: HTML tags/selectors to drop. maxAge: type: integer minimum: 0 maximum: 31536000000 description: Maximum acceptable cache age in milliseconds. minAge: type: integer minimum: 0 maximum: 31536000000 description: Minimum cache age in milliseconds before a page is refetched. timeout: type: integer minimum: 1000 maximum: 300000 description: Per-page timeout in milliseconds. required: - urls responses: '202': description: Batch scrape job accepted. The Location header points at the job resource; poll it until terminal. headers: Location: schema: type: string description: Path of the created job resource, e.g. /apis/v1/firecrawl/batch-scrape/{jobId}. content: application/json: schema: $ref: '#/components/schemas/AsyncJob' operationId: post_firecrawl_batch_scrape x-x402: path: /apis/v2/firecrawl/batch-scrape source: https://github.com/AIsa-team/aisa-proxy /firecrawl/batch-scrape/{jobId}: get: tags: - Other summary: Poll a batch scrape job. description: Fetch a batch scrape job submitted by `post_firecrawl_batch_scrape`, by its `jobId`. Returns the same envelope — `id`, `status`, `createdAt`, `completedAt`, `pricing`, `output`, `error`. Repeat until `status` is terminal; on success `output` is an array of documents with `markdown` and `metadata`. Reads a job only; it cannot start one. parameters: - in: path name: jobId required: true schema: type: string description: The job id returned by the submit call. responses: '200': description: The current state of the batch scrape job. content: application/json: schema: $ref: '#/components/schemas/AsyncJob' operationId: get_firecrawl_batch_scrape_job x-x402: path: /apis/v2/firecrawl/batch-scrape/{jobId} source: https://github.com/AIsa-team/aisa-proxy /models/{model}:generateContent: post: summary: Generate content using a Gemini-compatible AIsa model operationId: generateContent parameters: - name: model in: path required: true schema: type: string example: gemini-3.5-flash description: 'The AIsa model ID to use, for example: gemini-3.5-flash.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenerateContentRequest' responses: '200': description: Successful content generation content: application/json: schema: $ref: '#/components/schemas/GenerateContentResponse' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] tags: - AI Models servers: - url: https://api.aisa.one/v1beta /instagram/profile: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_profile summary: Profile description: Returns the full public profile for an Instagram handle, forwarded from Instagram's own web API. Counts sit under data.user.edge_followed_by.count and data.user.edge_follow.count, alongside biography, bio_links, external_url, full_name, is_verified, is_private, highlight_reel_count, the numeric id, and the twelve most recent posts under data.user.edge_owner_to_timeline_media.edges. Measured at about 380 KB; trim=true saves under one percent, so do not rely on it to shrink the payload. When the numeric id is already known, get_instagram_basic_profile returns the same headline numbers in about 4 KB. parameters: - name: handle in: query required: true description: Instagram handle schema: type: string example: jane - name: trim in: query required: false description: Set to true to get a trimmed response schema: type: boolean responses: '200': description: Successful response content: application/json: example: success: true data: user: biography: Building example.com | The easiest way to get public social media data at scale bio_links: - title: AIsa lynx_url: https://l.instagram.com/?u=https%3A%2F%2Fx.com%2Fadrian_horning_&e=AT0KAd0qSCzNTxgxhgbcBgpBfjdbmbmY2tBez0k8r-ykg_husVDislRpwV7hphrBf5oKxgE2JMWF43ZAkx4abc9zz8HfISec url: https://x.com/adrian_horning_ link_type: external biography_with_entities: raw_text: Building example.com | The easiest way to get public social media data at scale entities: [] external_url: https://x.com/adrian_horning_ edge_followed_by: count: 24555 fbid: '17841402777077586' edge_follow: count: 110 full_name: Adrian Horning id: '2700692569' is_business_account: true is_professional_account: true business_address_json: city_name: Austin, Texas city_id: 106224666074625 latitude: 30.26759 longitude: -97.74299 street_address: null zip_code: null category_name: Entrepreneur is_private: false is_verified: false profile_pic_url: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-19/430086429_362220943449758_2621012714660517106_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=RhIwCIipKVUQ7kNvwFpvyAL&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfPuXR8boR4S5dkEzAKuAxTDy2CiDHtblOt2xdmEYwUqdw&oe=685A08E9&_nc_sid=8b3546 profile_pic_url_hd: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-19/430086429_362220943449758_2621012714660517106_n.jpg?stp=dst-jpg_s320x320_tt6&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=RhIwCIipKVUQ7kNvwFpvyAL&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfONiKUtNB0AmfUKY78zqJc2wM8GVdfgKdx2t0-0HqIx_A&oe=685A08E9&_nc_sid=8b3546 username: adrianhorning edge_felix_video_timeline: count: 0 page_info: has_next_page: false end_cursor: null edges: [] edge_owner_to_timeline_media: count: 90 page_info: has_next_page: true end_cursor: QVFCY2E4Q1ZqQVBHdnBsUGMtVWlZZ2I3Qm9uOFdSSlZLS0NvdWVuQ05TQzR5T1hkSDM4cXVjTThsM1lQcXhsaWVyM2hQX0VoUzVYaHN3MmdRdmJGU0hENw== edges: - node: __typename: GraphVideo id: '3622533050035914969' shortcode: DJF0p2ygMjZ dimensions: height: 1136 width: 640 display_url: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=dst-jpg_e15_tt6&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfN3JWSxHXGRcVbzi4bEP0e42CF-gmZRTwPGLuprdlJGuQ&oe=685A1889&_nc_sid=8b3546 edge_media_to_tagged_user: edges: [] fact_check_overall_rating: null fact_check_information: null gating_info: null sharing_friction_info: should_have_sharing_friction: false bloks_app_url: null media_overlay_info: null media_preview: ABgqg3Uu4VPbGMZz94np6emPlbr3q+EBGQB+Y/H/AJZ1I7GK8bSHlsL6Dr+JorQuDGw+U/MDjp29+B/kmigCOaBUAJGM+/rUcOxuMnK56nj8PX8K0LrEsZUDOR+XfP4VjwI8hCngZ5/wHpmk0VFlqWMrGzr1AyKK0pY8oyj0IopkkoI/SoBGkblh1HI/z61Gh+X8KWTqfwqhCtJgg/gfzoqo3Q/570UAf//Z owner: id: '2700692569' username: adrianhorning is_video: true has_upcoming_event: false accessibility_caption: null dash_info: is_dash_eligible: true video_dash_manifest: | https://scontent-lga3-2.cdninstagram.com/o1/v/t2/f2/m367/AQMCx4WpbdanxcifQp6aX3v2DGfI_Eq6RsU_Z2c5TrAR2tTM-UKGtsQpsziJEKSndBazbOHwwFDtPp6ojDLuN-uC3CEena8AuyQTh2I.mp4?_nc_cat=100&_nc_sid=9ca052&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_ohc=tdWu2qgzCFkQ7kNvwGISPjP&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLmNsaXBzLmMyLUMzLmRhc2hfcjJldmV2cDktcjFnZW4ydnA5X3E2MCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjo3MDQzMTg2MzIwNTA1NTgsInZpX3VzZWNhc2VfaWQiOjEwMDk5LCJkdXJhdGlvbl9zIjozOCwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_zt=28&oh=00_AfNHBvnXH6I9I4qga7OQo8I8bbX8Xt-beirwEr5cwi225w&oe=685A17C9https://scontent-lga3-3.cdninstagram.com/o1/v/t2/f2/m367/AQPzbfKcje1byrDvq8YR4AvduiVvNKxRwuW5eXcXb6B60mKOOZSq2S2G1G763vWRFSgYc4j3WfK69rUDY2H3Qsw9_yB33-gvjwaaQrU.mp4?_nc_cat=104&_nc_sid=9ca052&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_ohc=OKOnrKt5yNcQ7kNvwEHQTMa&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLmNsaXBzLmMyLUMzLmRhc2hfcjJldmV2cDktcjFnZW4ydnA5X3E3MCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjo3MDQzMTg2MzIwNTA1NTgsInZpX3VzZWNhc2VfaWQiOjEwMDk5LCJkdXJhdGlvbl9zIjozOCwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_zt=28&oh=00_AfO6gvz9F5m4B40F4xCWw8epgaulUF3aIpKOHw3YQyDKdA&oe=685A16C9https://scontent-lga3-3.cdninstagram.com/o1/v/t2/f2/m367/AQNKeV8ZzKEUh6GtiHZ4h2GHrWMG8klq-rNb-om-3WsZqFVCqBUChpttUn0VdtI-kb1HTSt-mqd-IUpda-e-1Ct5WQVjgGBUFKqZW6k.mp4?_nc_cat=108&_nc_sid=9ca052&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_ohc=cAAJI8QKF3cQ7kNvwGPPIEp&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLmNsaXBzLmMyLUMzLmRhc2hfcjJldmV2cDktcjFnZW4ydnA5X3E4MCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjo3MDQzMTg2MzIwNTA1NTgsInZpX3VzZWNhc2VfaWQiOjEwMDk5LCJkdXJhdGlvbl9zIjozOCwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_zt=28&oh=00_AfM3ZUHT7P7kDHSnQWdmkMNAZev3DqVh-ogoric6mwTCfw&oe=685A2039https://scontent-lga3-3.cdninstagram.com/o1/v/t2/f2/m367/AQNKBhbA4fJfoUsBrS5L9rvBcEEYPsiDNkpGhHUTAsvNz9FVH3sFq-5BGCTrhXqE-9OOrf6ZXcYgc1ZyeyjkIhKhwPqXulbXwQhETiE.mp4?_nc_cat=106&_nc_sid=9ca052&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_ohc=hR5K7-pJIjYQ7kNvwG0KIvy&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLmNsaXBzLmMyLUMzLmRhc2hfcjJldmV2cDktcjFnZW4ydnA5X3E5MCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjo3MDQzMTg2MzIwNTA1NTgsInZpX3VzZWNhc2VfaWQiOjEwMDk5LCJkdXJhdGlvbl9zIjozOCwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_zt=28&oh=00_AfN0FumICc3gocLrtUbwpD0S_CL9_j6VWpruUTggbVZPxg&oe=685A2BA3https://scontent-lga3-2.cdninstagram.com/o1/v/t16/f2/m69/AQPlt9RDt-DmGSWZPircoX-bty88IKciKTjgMgf8ncmxMLLWPx6KfyLS34HDZXRixrrFEW5_P-TAoR7vL97OV22_.mp4?strext=1&_nc_cat=107&_nc_sid=9ca052&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_ohc=opLE557_YjcQ7kNvwGzrtJj&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLmNsaXBzLmMyLUMzLmRhc2hfbG5faGVhYWNfdmJyM19hdWRpbyIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjo3MDQzMTg2MzIwNTA1NTgsInZpX3VzZWNhc2VfaWQiOjEwMDk5LCJkdXJhdGlvbl9zIjozOCwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_zt=28&oh=00_AfP99wtyKoO-gqUnlUW2zh_xfD_6sc1CVQsK6EKHlSTD1g&oe=685A0A05 number_of_qualities: 4 has_audio: true tracking_token: eyJ2ZXJzaW9uIjo1LCJwYXlsb2FkIjp7ImlzX2FuYWx5dGljc190cmFja2VkIjp0cnVlLCJ1dWlkIjoiNDQzYjgyZjVhNmExNDY5Mjk3NzUwYTFiNDgxNDFhYjAzNjIyNTMzMDUwMDM1OTE0OTY5In0sInNpZ25hdHVyZSI6IiJ9 video_url: https://scontent-lga3-3.cdninstagram.com/o1/v/t16/f2/m86/AQOtWzDoaQkqcah0vnQQ9OiZsZO_7DqXWlZS98KgVeme4ytLMOPYmhG9xprV3izReal1QXGlLQJHeYZPpucgpGowYKulh3AmomTiECc.mp4?stp=dst-mp4&efg=eyJxZV9ncm91cHMiOiJbXCJpZ193ZWJfZGVsaXZlcnlfdnRzX290ZlwiXSIsInZlbmNvZGVfdGFnIjoidnRzX3ZvZF91cmxnZW4uY2xpcHMuYzIuNzIwLmJhc2VsaW5lIn0&_nc_cat=110&vs=1123914736090327_2004971061&_nc_vs=HBksFQIYUmlnX3hwdl9yZWVsc19wZXJtYW5lbnRfc3JfcHJvZC8xNzRGRTM0NzIzQUVFNDBENTVGQUVEOTdCM0MzQUU4NV92aWRlb19kYXNoaW5pdC5tcDQVAALIARIAFQIYOnBhc3N0aHJvdWdoX2V2ZXJzdG9yZS9HRERLYVIydGxzaGYwMWtIQUdyaE5SaWZ3ZFFIYnFfRUFBQUYVAgLIARIAKAAYABsAFQAAJtLPi%2FW6684%2FFQIoAkMzLBdAQwztkWhysBgSZGFzaF9iYXNlbGluZV8xX3YxEQB1%2Fgdl5p0BAA%3D%3D&_nc_rid=443b81e6a9&ccb=9-4&oh=00_AfMg9NUoS_RCVGxJzHIQeppcVco4FTbXjoq5xaS5i5o3AA&oe=685632F7&_nc_sid=8b3546 video_view_count: 1870 edge_media_to_caption: edges: [] edge_media_to_comment: count: 14 comments_disabled: false taken_at_timestamp: 1746059630 edge_liked_by: count: 131 edge_media_preview_like: count: 131 location: null nft_asset_info: null thumbnail_src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_tt6&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfPtuS1pX4lCrFcqaqf28LYqOKhm388RGITip3ezIQa3xg&oe=685A1889&_nc_sid=8b3546 thumbnail_tall_src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=dst-jpg_e15_tt6&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfN3JWSxHXGRcVbzi4bEP0e42CF-gmZRTwPGLuprdlJGuQ&oe=685A1889&_nc_sid=8b3546 thumbnail_resources: - src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6ImltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4Lm5mcmFtZV9jb3Zlcl9mcmFtZSJ9&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfMTtR_qbPhnbuudBcbRh_hbPXzrNUyY2-bhqZ85cQrazA&oe=685A1889&_nc_sid=8b3546 config_width: 150 config_height: 150 - src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_s240x240_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6ImltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4Lm5mcmFtZV9jb3Zlcl9mcmFtZSJ9&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfNRkH10wSAf-1v4_p9lzWmsvBBmZSDAGZUriikU87ZjoA&oe=685A1889&_nc_sid=8b3546 config_width: 240 config_height: 240 - src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_s320x320_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6ImltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4Lm5mcmFtZV9jb3Zlcl9mcmFtZSJ9&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfM4_oFn-y-n-R9WgA10Ltmy3A3weV0m6JGaUfQ5Nx72dA&oe=685A1889&_nc_sid=8b3546 config_width: 320 config_height: 320 - src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_s480x480_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6ImltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4Lm5mcmFtZV9jb3Zlcl9mcmFtZSJ9&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfOj-8tYyymreaxMKp97bJF-iOIKkJLDBgik_bbBcF9dRg&oe=685A1889&_nc_sid=8b3546 config_width: 480 config_height: 480 - src: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_9680674652022458_2870310738491256504_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6ImltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4Lm5mcmFtZV9jb3Zlcl9mcmFtZSJ9&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=102&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=3VMXYLESR9UQ7kNvwHFuMDk&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfPtuS1pX4lCrFcqaqf28LYqOKhm388RGITip3ezIQa3xg&oe=685A1889&_nc_sid=8b3546 config_width: 640 config_height: 640 felix_profile_grid_crop: null tall_profile_grid_crop: null profile_grid_thumbnail_fitting_style: UNSET coauthor_producers: [] pinned_for_users: [] viewer_can_reshare: true like_and_view_counts_disabled: false product_type: clips clips_music_attribution_info: artist_name: adrianhorning song_name: Original audio uses_original_audio: true should_mute_audio: false should_mute_audio_reason: '' audio_id: '1052522106930425' edge_media_collections: count: 0 page_info: has_next_page: false end_cursor: null edges: [] edge_related_profiles: edges: - node: id: '66873381803' full_name: ally krinsky is_private: false is_verified: false profile_pic_url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/465249338_1115706923297633_2956285260068952346_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=105&_nc_oc=Q6cZ2QHGD17MFSxvG6A4al-hcbMWJBsese4bMwMX39i8kBtCx0S4j1OYDyxMqJNJrP1lEEI&_nc_ohc=Tsg6TtnhEjYQ7kNvwGMqyjy&_nc_gid=SOClLZ7awnLvrffwVXt_dA&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AfMROscsMYIyI5Fk8bU4J0EDI0TAVDiLmama26HDm3Sb5g&oe=685A28B1&_nc_sid=8b3546 username: itsallykrinsky schema: $ref: '#/components/schemas/InstagramProfileResponse' x-x402: path: /apis/v2/instagram/profile source: https://github.com/AIsa-team/aisa-proxy /instagram/basic-profile: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_basic_profile summary: Basic Profile description: 'Returns a compact public profile for a numeric Instagram user id, about 4 KB against the 380 KB of get_instagram_profile. Flat, already-normalised fields: username, full_name, biography, follower_count, following_count, is_verified, is_private, category, profile_pic_url, hd_profile_pic_url_info, bio_links, external_url and pk. Prefer this endpoint whenever the id is in hand; obtain it from data.user.id in get_instagram_profile, from id in get_instagram_search_profiles, or from the owner of any post. Use get_instagram_profile only when a handle is all that is available.' parameters: - name: userId in: query required: false description: Instagram user id schema: type: string example: '314216' responses: '200': description: Successful response content: application/json: example: friendship_status: null gating: null is_memorialized: false is_private: false has_story_archive: null supervision_info: null is_regulated_c18: false regulated_news_in_locations: [] bio_links: [] linked_fb_info: null text_post_app_badge_label: zuck show_text_post_app_badge: true username: zuck text_post_new_post_count: null pk: '314216' live_broadcast_visibility: null live_broadcast_id: null profile_pic_url: https://instagram.fpoz4-1.fna.fbcdn.net/v/t51.2885-19/550234512_18532404670058217_8758519395071163708_n.jpg?stp=dst-jpg_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=instagram.fpoz4-1.fna.fbcdn.net&_nc_cat=1&_nc_oc=Q6cZ2QENWmroLq0Z2oxDXF-wYN4Txpcg88E2n5GZTMYtQgXKAlUWi1gMsQQilbgL7mYspgA&_nc_ohc=vS_PAWzWFjcQ7kNvwEe9m50&_nc_gid=AOVYXTTsY5VI85UshvRoHA&edm=ALGbJPMBAAAA&ccb=7-5&oh=00_AfcUDbyLkAcHCLaaiVpvfv4AvlKuZUdsos_eZmuWHS02NQ&oe=68EB29FB&_nc_sid=7d3ac5 hd_profile_pic_url_info: url: https://instagram.fpoz4-1.fna.fbcdn.net/v/t51.2885-19/550234512_18532404670058217_8758519395071163708_n.jpg?efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=instagram.fpoz4-1.fna.fbcdn.net&_nc_cat=1&_nc_oc=Q6cZ2QENWmroLq0Z2oxDXF-wYN4Txpcg88E2n5GZTMYtQgXKAlUWi1gMsQQilbgL7mYspgA&_nc_ohc=vS_PAWzWFjcQ7kNvwEe9m50&_nc_gid=AOVYXTTsY5VI85UshvRoHA&edm=ALGbJPMBAAAA&ccb=7-5&oh=00_AfcBW_k3ngIbA43oUKKZ9SPx-FtlrQSSbOWg8npnXGqCcg&oe=68EB29FB&_nc_sid=7d3ac5 is_unpublished: false latest_reel_media: 0 has_profile_pic: null profile_pic_genai_tool_info: [] biography: I build stuff full_name: Mark Zuckerberg is_verified: true show_account_transparency_details: true account_type: 3 follower_count: 16101999 mutual_followers_count: null profile_context_links_with_user_ids: null address_street: null city_name: null is_business: false zip: null biography_with_entities: entities: [] category: null should_show_category: false account_badges: [] ai_agent_type: null external_lynx_url: null external_url: '' pronouns: [] transparency_label: null transparency_product: null has_chaining: null remove_message_entrypoint: null fbid_v2: '17841401746480004' is_embeds_disabled: false is_professional_account: null following_count: 617 media_count: 409 total_clips_count: 1 latest_besties_reel_media: null reel_media_seen_timestamp: null id: '314216' schema: $ref: '#/components/schemas/InstagramBasicProfileResponse' x-x402: path: /apis/v2/instagram/basic-profile source: https://github.com/AIsa-team/aisa-proxy /instagram/user/posts: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_user_posts summary: User Posts description: Returns one page of a public account's timeline, reels and photos and carousels alike, as raw Instagram media objects under items. Page with next_max_id and stop on more_available; num_results reports the page size. Each item carries media_type, code, caption, like_count, comment_count, taken_at, image_versions2 and video_versions among roughly two hundred internal flags. Measured at 632 KB per page, the largest response in this API, and trim=true only reduces it to 523 KB. For reels alone use get_instagram_user_reels, and for one known post use get_instagram_post; both return the same raw shape, so neither is a way to get a smaller payload. parameters: - name: handle in: query required: true description: Instagram handle schema: type: string - name: next_max_id in: query required: false description: Cursor to get next page of results. schema: type: string - name: trim in: query required: false description: Set to true to get a trimmed response schema: type: boolean responses: '200': description: Successful response content: application/json: example: items: - id: '3644028144127958689_59042353222' code: DKSMEpKRd6h media_type: 2 taken_at: 1748622051 caption: bit_flags: 0 created_at: 1748622053 created_at_utc: 1748622053 did_report_as_spam: false is_ranked_comment: false pk: '17916912093071427' share_enabled: false content_type: comment media_id: '3644028144127958689' status: Active type: 1 user_id: '59042353222' strong_id__: '17916912093071427' text: 5 best college baseball regional plays for day 1 user: pk: '59042353222' pk_id: '59042353222' id: '59042353222' full_name: Carson Szeder is_private: false is_unpublished: false strong_id__: '59042353222' fbid_v2: '17841459076660294' username: carsoncantcode is_verified: true profile_pic_id: '3318246086567523250_59042353222' profile_pic_url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfP_ozLRxIquMfrVuFJ1MP_CwqFycc2hoq8Xc9x89Tyx_g&oe=685A4097&_nc_sid=ee9879 is_covered: false private_reply_status: 0 play_count: 2647 ig_play_count: 2643 comment_count: 7 like_count: 29 display_uri: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/502710192_1957567931446141_1822523212661288021_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=101&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=ng-epM2kdRMQ7kNvwHHDPMi&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfOIfw4eK3gmQ8rB8XmU3AgCiDHwFyd4oi4o_VEuOBoWOg&oe=685A1A4E&_nc_sid=ee9879 user: fbid_v2: '17841459076660294' feed_post_reshare_disabled: false full_name: Carson Szeder id: '59042353222' is_private: false is_unpublished: false pk: '59042353222' pk_id: '59042353222' show_account_transparency_details: true strong_id__: '59042353222' third_party_downloads_enabled: 1 account_type: 3 account_badges: [] fan_club_info: autosave_to_exclusive_highlight: null connected_member_count: null fan_club_id: null fan_club_name: null has_created_ssc: null has_enough_subscribers_for_ssc: null is_fan_club_gifting_eligible: null is_fan_club_referral_eligible: null is_free_trial_eligible: null largest_public_bc_id: null subscriber_count: null fan_consideration_page_revamp_eligiblity: null has_anonymous_profile_picture: false hd_profile_pic_url_info: height: 633 url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfMSK6EX4bRxpdThMOgOdvKaORBx3RCo1QjtMxsbHx813A&oe=685A4097&_nc_sid=ee9879 width: 633 hd_profile_pic_versions: - height: 320 url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?stp=dst-jpg_s320x320_tt6&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfNOvmXHru1CI6pJxyfmTlcl9UwzjKz6kH-b_YFGsvKQ9g&oe=685A4097&_nc_sid=ee9879 width: 320 is_verified: true profile_pic_id: '3318246086567523250_59042353222' profile_pic_url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfP_ozLRxIquMfrVuFJ1MP_CwqFycc2hoq8Xc9x89Tyx_g&oe=685A4097&_nc_sid=ee9879 transparency_product_enabled: false username: carsoncantcode is_embeds_disabled: false eligible_for_text_app_activation_badge: false owner: fbid_v2: '17841459076660294' feed_post_reshare_disabled: false full_name: Carson Szeder id: '59042353222' is_private: false is_unpublished: false pk: '59042353222' pk_id: '59042353222' show_account_transparency_details: true strong_id__: '59042353222' third_party_downloads_enabled: 1 can_see_quiet_post_attribution: true account_type: 3 account_badges: [] fan_club_info: autosave_to_exclusive_highlight: null connected_member_count: null fan_club_id: null fan_club_name: null has_created_ssc: null has_enough_subscribers_for_ssc: null is_fan_club_gifting_eligible: null is_fan_club_referral_eligible: null is_free_trial_eligible: null largest_public_bc_id: null subscriber_count: null fan_consideration_page_revamp_eligiblity: null has_anonymous_profile_picture: false hd_profile_pic_url_info: height: 633 url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfMSK6EX4bRxpdThMOgOdvKaORBx3RCo1QjtMxsbHx813A&oe=685A4097&_nc_sid=ee9879 width: 633 hd_profile_pic_versions: - height: 320 url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?stp=dst-jpg_s320x320_tt6&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfNOvmXHru1CI6pJxyfmTlcl9UwzjKz6kH-b_YFGsvKQ9g&oe=685A4097&_nc_sid=ee9879 width: 320 is_verified: true profile_pic_id: '3318246086567523250_59042353222' profile_pic_url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfP_ozLRxIquMfrVuFJ1MP_CwqFycc2hoq8Xc9x89Tyx_g&oe=685A4097&_nc_sid=ee9879 transparency_product_enabled: false username: carsoncantcode is_embeds_disabled: false eligible_for_text_app_activation_badge: false image_versions2: additional_candidates: first_frame: height: 1136 url: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/502608920_587032841104047_520039248454188749_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4LmFkZGl0aW9uYWxfY292ZXJfZnJhbWUifQ&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=103&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=UmnNszq3yrMQ7kNvwFrKy8f&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfPXJLoL0tbpHfbhYLn-UBI1wjXiWeybU6nGob9Db-fQLQ&oe=685A1308&_nc_sid=ee9879 width: 640 igtv_first_frame: height: 1136 url: https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/502608920_587032841104047_520039248454188749_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4LmFkZGl0aW9uYWxfY292ZXJfZnJhbWUifQ&_nc_ht=scontent-lga3-1.cdninstagram.com&_nc_cat=103&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=UmnNszq3yrMQ7kNvwFrKy8f&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfPXJLoL0tbpHfbhYLn-UBI1wjXiWeybU6nGob9Db-fQLQ&oe=685A1308&_nc_sid=ee9879 width: 640 smart_frame: null candidates: - height: 1136 url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/502710192_1957567931446141_1822523212661288021_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4Lm5mcmFtZV9jb3Zlcl9mcmFtZSJ9&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=101&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=ng-epM2kdRMQ7kNvwHHDPMi&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&ig_cache_key=MzY0NDAyODE0NDEyNzk1ODY4OQ%3D%3D.3-ccb7-5&oh=00_AfM7Qh-4MOEJSG5Ml_l1YzF9CHN6QizTM5-4Xc3UZo-bxw&oe=685A1A4E&_nc_sid=ee9879 width: 640 scrubber_spritesheet_info_candidates: default: file_size_kb: 388 max_thumbnails_per_sprite: 105 rendered_width: 96 sprite_height: 1246 sprite_urls: - https://scontent-lga3-3.cdninstagram.com/v/t51.2885-15/502708871_1436358334024784_3923116580658609450_n.jpg?_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=108&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=_rnw_74a7UEQ7kNvwGAMYFD&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfMZ8xKy_7T16FYamhGQYxtJkUm_Hypo3pCrDXPWzWTYdQ&oe=685A1A2A&_nc_sid=ee9879 sprite_width: 1500 thumbnail_duration: 0.6866666666666666 thumbnail_height: 178 thumbnail_width: 100 thumbnails_per_row: 15 total_thumbnail_num_per_sprite: 105 video_length: 72.1 product_type: clips music_metadata: null is_paid_partnership: false video_sticker_locales: - en video_versions: - bandwidth: null height: 852 type: 101 url: https://scontent-lga3-1.cdninstagram.com/o1/v/t16/f2/m86/AQMBOiKBGQDTEPcTzw51q2K7ixLiwkfCual2hfLfJ11K3C6bAOlgqWAEIP4284QXb_Uk-TXekJvIUeAfv--ZX6PWX0s1LbCaDn13iD0.mp4?stp=dst-mp4&efg=eyJxZV9ncm91cHMiOiJbXCJpZ193ZWJfZGVsaXZlcnlfdnRzX290ZlwiXSIsInZlbmNvZGVfdGFnIjoidnRzX3ZvZF91cmxnZW4uY2xpcHMuYzIuNzIwLmJhc2VsaW5lIn0&_nc_cat=111&vs=1201779154524089_749549050&_nc_vs=HBksFQIYUmlnX3hwdl9yZWVsc19wZXJtYW5lbnRfc3JfcHJvZC84MzQ5RTk3QjExQ0JFNzI0MjZFNDg0ODhDOEIxQkY5NF92aWRlb19kYXNoaW5pdC5tcDQVAALIARIAFQIYOnBhc3N0aHJvdWdoX2V2ZXJzdG9yZS9HRFluN0IxZWprZHc0XzRFQUFYc3RUZkRKSWxIYnFfRUFBQUYVAgLIARIAKAAYABsAFQAAJsKsv6TxptA%2FFQIoAkMzLBdAUgZmZmZmZhgSZGFzaF9iYXNlbGluZV8xX3YxEQB1%2Fgdl5p0BAA%3D%3D&ccb=9-4&oh=00_AfMavpzRW6PSEKyPgrcVALJs6kfHRNeKjBw8wO82ayG4WA&oe=68562E52&_nc_sid=ee9879 width: 480 video_duration: 72.1 has_audio: true url: https://www.instagram.com/p/DKSMEpKRd6h/ next_max_id: '3639831059405682409_59042353222' num_results: 12 more_available: true user: pk: '59042353222' pk_id: '59042353222' full_name: Carson Szeder is_private: false is_active_on_text_post_app: true strong_id__: '59042353222' profile_grid_display_type: default id: '59042353222' username: carsoncantcode is_verified: true profile_pic_id: '3318246086567523250_59042353222' profile_pic_url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-19/431903885_797859762202050_7017850157267325892_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2QHiEom3hMdlCt1UvbqMoAi8AVMa_QCzMo8Z3JyyueN2RgZ46phuoYGRHEiGNrkRFOg&_nc_ohc=DtppWMlqRCcQ7kNvwEYrxi1&_nc_gid=Eb0J24h8KiM70eUrBpX9HQ&edm=ACWDqb8BAAAA&ccb=7-5&oh=00_AfP_ozLRxIquMfrVuFJ1MP_CwqFycc2hoq8Xc9x89Tyx_g&oe=685A4097&_nc_sid=ee9879 schema: $ref: '#/components/schemas/InstagramItemsResponse' x-x402: path: /apis/v2/instagram/user/posts source: https://github.com/AIsa-team/aisa-proxy /instagram/user/reels: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_user_reels summary: User Reels description: Returns one page of a public account's reels as raw Instagram media objects under items[].media, with paging_info.max_id for the following page. Each reel carries code, caption, like_count, comment_count, video_versions, image_versions2 and clips_metadata, whose original_sound_info.audio_asset_id is exactly the id that get_instagram_song_reels expects. Pass user_id rather than handle for a faster response. Measured at 594 KB per page. Use get_instagram_user_posts for the whole timeline including photos and carousels. parameters: - name: user_id in: query required: false description: Instagram user id. Use this for faster response times. schema: type: string example: '2700692569' - name: handle in: query required: false description: Instagram handle. Use user_id for faster response times. schema: type: string example: jane - name: max_id in: query required: false description: Max id to get more reels. Get 'max_id' from previous response. schema: type: string example: QVFCVzNnS2lI...== - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: items: - id: '3641924023820356866_21393171' code: DKKtpqaxg0C taken_at: 1748371310 caption: bit_flags: 0 created_at: 1748371312 created_at_utc: 1748371312 did_report_as_spam: false is_ranked_comment: false pk: '18079986955772842' share_enabled: false content_type: comment media_id: '3641924023820356866' status: Active type: 1 user_id: '21393171' strong_id__: '18079986955772842' text: |- Summer brings out all the girlies, soda, and global warming!!!🤗☀️ #states #utah #idaho #california #oregon #newyork #minnesota #arizona #alaska #girlies #jane #janeinsane #eastcoast #westcoast #drama user: pk: '21393171' pk_id: '21393171' id: '21393171' full_name: Jane Williamson is_private: false is_unpublished: false strong_id__: '21393171' fbid_v2: '17841400515130334' username: jane is_verified: true profile_pic_id: '3583980709961915639_21393171' profile_pic_url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfNtjn382KDVjtIjCSaHRLBv-5axcS6DArSz3ceqiChSQw&oe=685A6928&_nc_sid=c024bc is_covered: false private_reply_status: 0 play_count: 1685367 ig_play_count: 1685367 comment_count: 1096 like_count: 71768 display_uri: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/501064973_18499642795017172_3156358348692457402_n.jpg?stp=c0.469.1206.1206a_dst-jpg_e35_s1080x1080_sh0.08_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=nqrFLRdKJkgQ7kNvwFsYpnt&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfOZBf0XzICMS0v3EFHyXXbDmGCSkBBSD7yGH4KXyIlC3A&oe=685A3C9E&_nc_sid=c024bc user: fbid_v2: '17841400515130334' feed_post_reshare_disabled: false full_name: Jane Williamson id: '21393171' is_private: false is_unpublished: false pk: '21393171' pk_id: '21393171' show_account_transparency_details: true strong_id__: '21393171' third_party_downloads_enabled: 2 account_type: 3 account_badges: [] fan_club_info: autosave_to_exclusive_highlight: null connected_member_count: null fan_club_id: null fan_club_name: null has_created_ssc: null has_enough_subscribers_for_ssc: null is_fan_club_gifting_eligible: null is_fan_club_referral_eligible: null is_free_trial_eligible: null largest_public_bc_id: null subscriber_count: null fan_consideration_page_revamp_eligiblity: null has_anonymous_profile_picture: false hd_profile_pic_url_info: height: 1024 url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfMxQOnDe9llEUmo1gBn1-P5uo-mPtoJ4lTyy_GhgpgIkg&oe=685A6928&_nc_sid=c024bc width: 1024 hd_profile_pic_versions: - height: 320 url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s320x320_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfOxDHstKKV5WkD6-9aKBxJ0mTttI5R3bZ26ZQn9Mg84Og&oe=685A6928&_nc_sid=c024bc width: 320 is_verified: true profile_pic_id: '3583980709961915639_21393171' profile_pic_url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfNtjn382KDVjtIjCSaHRLBv-5axcS6DArSz3ceqiChSQw&oe=685A6928&_nc_sid=c024bc transparency_product_enabled: false username: jane is_embeds_disabled: false eligible_for_text_app_activation_badge: false owner: fbid_v2: '17841400515130334' feed_post_reshare_disabled: false full_name: Jane Williamson id: '21393171' is_private: false is_unpublished: false pk: '21393171' pk_id: '21393171' show_account_transparency_details: true strong_id__: '21393171' third_party_downloads_enabled: 2 account_type: 3 account_badges: [] fan_club_info: autosave_to_exclusive_highlight: null connected_member_count: null fan_club_id: null fan_club_name: null has_created_ssc: null has_enough_subscribers_for_ssc: null is_fan_club_gifting_eligible: null is_fan_club_referral_eligible: null is_free_trial_eligible: null largest_public_bc_id: null subscriber_count: null fan_consideration_page_revamp_eligiblity: null has_anonymous_profile_picture: false hd_profile_pic_url_info: height: 1024 url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfMxQOnDe9llEUmo1gBn1-P5uo-mPtoJ4lTyy_GhgpgIkg&oe=685A6928&_nc_sid=c024bc width: 1024 hd_profile_pic_versions: - height: 320 url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s320x320_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfOxDHstKKV5WkD6-9aKBxJ0mTttI5R3bZ26ZQn9Mg84Og&oe=685A6928&_nc_sid=c024bc width: 320 is_verified: true profile_pic_id: '3583980709961915639_21393171' profile_pic_url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=UOwY1iuLY14Q7kNvwF6T6a4&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfNtjn382KDVjtIjCSaHRLBv-5axcS6DArSz3ceqiChSQw&oe=685A6928&_nc_sid=c024bc transparency_product_enabled: false username: jane is_embeds_disabled: false eligible_for_text_app_activation_badge: false image_versions2: additional_candidates: first_frame: height: 1136 url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-15/501249811_1047509020812730_1368766689877144056_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4LmFkZGl0aW9uYWxfY292ZXJfZnJhbWUifQ&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=110&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=33QsVTbubdAQ7kNvwG_XAXp&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfOPIDhcaTvUglakLpfaFwY0VG7z_Q7Ua0cIZFWseBY6Iw&oe=685A6296&_nc_sid=c024bc width: 640 igtv_first_frame: height: 1136 url: https://scontent-lga3-3.cdninstagram.com/v/t51.2885-15/501249811_1047509020812730_1368766689877144056_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi42NDB4MTEzNi5zZHIuZjcxODc4LmFkZGl0aW9uYWxfY292ZXJfZnJhbWUifQ&_nc_ht=scontent-lga3-3.cdninstagram.com&_nc_cat=110&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=33QsVTbubdAQ7kNvwG_XAXp&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfOPIDhcaTvUglakLpfaFwY0VG7z_Q7Ua0cIZFWseBY6Iw&oe=685A6296&_nc_sid=c024bc width: 640 smart_frame: height: 1920 url: https://scontent-lga3-2.cdninstagram.com/v/t15.5256-10/502085875_1788049852055333_7728247084856383096_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi4xMDgweDE5MjAuc2RyLmY1MjU2LnN0YXRpY19zbWFydF90aHVtYm5haWxzOjpBTUxfTUxQX0hBTkRDUkFGVF9BTkRfWFJBWV9BRFNfQ1RSX0RJVkVSU0UifQ&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=105&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=jVe4YhB4hhcQ7kNvwHLLFGj&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIAAAAA&ccb=7-5&oh=00_AfPE2w7ZHuMdj6JkHfdN0ThY-Qfyhb8JZSwgO0jy3vknFw&oe=685A5983&_nc_sid=c024bc width: 1080 candidates: - height: 2144 url: https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/501064973_18499642795017172_3156358348692457402_n.jpg?stp=dst-jpg_e15_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLmltYWdlX3VybGdlbi4xMjA2eDIxNDQuc2RyLmY3NTc2MS5kZWZhdWx0X2NvdmVyX2ZyYW1lIn0&_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=nqrFLRdKJkgQ7kNvwFsYpnt&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&ig_cache_key=MzY0MTkyNDAyMzgyMDM1Njg2NjE4NDk5NjQyNzkyMDE3MTcy.3-ccb7-5&oh=00_AfOJFvfFxIS1SYZ5aZH9EoStYPO1y4sVrL_f18BDcI4gIA&oe=685A3C9E&_nc_sid=c024bc width: 1206 scrubber_spritesheet_info_candidates: default: file_size_kb: 467 max_thumbnails_per_sprite: 105 rendered_width: 96 sprite_height: 1246 sprite_urls: - https://scontent-lga3-2.cdninstagram.com/v/t51.2885-15/501930551_1739874873569815_2195383679016609522_n.jpg?_nc_ht=scontent-lga3-2.cdninstagram.com&_nc_cat=107&_nc_oc=Q6cZ2QHH_AuDym1_h_Gt35CeYD9UUv5wiBJykWgz0pzbdkl_7HVH1k09gFjEGZGaaanoHrw&_nc_ohc=WQsolWkGTbEQ7kNvwGnCcen&_nc_gid=26ktQKWC9pWQuqHYOHHLSQ&edm=ACHbZRIBAAAA&ccb=7-5&oh=00_AfPA-bQmtGEM1tlWBC9ycNBKmLQXZ8HhuCQqTxZcKAwTNg&oe=685A34DF&_nc_sid=c024bc sprite_width: 1500 thumbnail_duration: 0.8703142857142857 thumbnail_height: 178 thumbnail_width: 100 thumbnails_per_row: 15 total_thumbnail_num_per_sprite: 105 video_length: 91.383 url: https://www.instagram.com/reel/DKKtpqaxg0C/ max_id: QVFEWFlDdGNOamdwbVdNM2pLY1NJRndSZ2tCbWp6WDV0TWxaYl9WNVktZU1BTUxWMlg1c2JFenNDanJVZ2NudWFjR28zRG93a3ByTExXaHJMbTA0aVJBZg== schema: $ref: '#/components/schemas/InstagramItemsResponse' x-x402: path: /apis/v2/instagram/user/reels source: https://github.com/AIsa-team/aisa-proxy /instagram/user/highlights: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_user_highlights summary: User Highlights description: Lists the story highlight albums on a public profile. Returns highlights, each with the numeric id, title, cover_media.thumbnail_src, cover_media_cropped_thumbnail and owner. Small and quick at about 6 KB, which makes it a cheap way to see whether an account keeps highlights at all. This is the only source of a highlight id, and get_instagram_user_highlight_detail requires the bare numeric id exactly as returned here. Pass user_id rather than handle for a faster response. parameters: - name: user_id in: query required: false description: Instagram user id. Use for faster response times. schema: type: string example: '2700692569' - name: handle in: query required: false description: Instagram handle. Use user_id for faster response times. schema: type: string example: jane responses: '200': description: Successful response content: application/json: example: success: true highlights: - __typename: GraphHighlightReel id: '18067016518767507' cover_media: thumbnail_src: https://scontent-atl3-1.cdninstagram.com/v/t51.2885-15/479737232_1405856350793820_7928432152706230890_n.jpg?stp=c0.248.640.640a_dst-jpg_e15_tt6&_nc_ht=scontent-atl3-1.cdninstagram.com&_nc_cat=100&_nc_oc=Q6cZ2QFp33CnPIjTITbJL483a_ZGgbaCZ_M2CLjXKDaTtNtjnH0vMIJHdZhYlMp8pitL7H0&_nc_ohc=yQlHN7CDZ7IQ7kNvwFL7xsz&_nc_gid=_FojUPY_PyEb8t9oWJExMQ&edm=AGW0Xe4BAAAA&ccb=7-5&oh=00_AfL3lEQ_ujUci_Xg8fnjYX3nityUOfroonJnwKyr9yKWdg&oe=682184F5&_nc_sid=94fea1 cover_media_cropped_thumbnail: url: https://scontent-atl3-1.cdninstagram.com/v/t51.2885-15/479737232_1405856350793820_7928432152706230890_n.jpg?stp=c0.202.640.640a_dst-jpg_e15_s150x150_tt6&_nc_ht=scontent-atl3-1.cdninstagram.com&_nc_cat=100&_nc_oc=Q6cZ2QFp33CnPIjTITbJL483a_ZGgbaCZ_M2CLjXKDaTtNtjnH0vMIJHdZhYlMp8pitL7H0&_nc_ohc=yQlHN7CDZ7IQ7kNvwFL7xsz&_nc_gid=_FojUPY_PyEb8t9oWJExMQ&edm=AGW0Xe4BAAAA&ccb=7-5&oh=00_AfL4zidNtWdVh-3T2E2qOiLS4ks_Z9UbmTSFbCX3SFmbBg&oe=682184F5&_nc_sid=94fea1 owner: __typename: GraphUser id: '21393171' profile_pic_url: https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QFp33CnPIjTITbJL483a_ZGgbaCZ_M2CLjXKDaTtNtjnH0vMIJHdZhYlMp8pitL7H0&_nc_ohc=mi86alqirjwQ7kNvwHuN1wX&_nc_gid=_FojUPY_PyEb8t9oWJExMQ&edm=AGW0Xe4BAAAA&ccb=7-5&oh=00_AfLoz8BQ5BXQz1Wm0goIWDxkdw5Z1aNbJGXk8ak6YZ8pzQ&oe=68218068&_nc_sid=94fea1 username: jane title: GRWM chats schema: $ref: '#/components/schemas/InstagramHighlightsResponse' x-x402: path: /apis/v2/instagram/user/highlights source: https://github.com/AIsa-team/aisa-proxy /instagram/user/highlight/detail: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_user_highlight_detail summary: Highlight Detail description: 'Returns the stories inside one highlight album: reel_type, latest_reel_media, the owning user, and items, each a raw Instagram story media object. Pass the bare numeric id from get_instagram_user_highlights. The response echoes that id back in the prefixed form highlight:, and feeding the prefixed form to this endpoint returns 404 with a message blaming deletion or a private account, which points at the wrong cause; send the bare number. Measured at 630 KB for an album of 38 stories, so size scales with the album.' parameters: - name: id in: query required: false description: Highlight ID. Use `/instagram/user/highlights` to discover current highlight IDs for a public account. schema: type: string example: '18029499352961095' responses: '200': description: Successful response content: application/json: example: success: true id: highlight:18067016518767507 latest_reel_media: 1745272279 seen: null can_reply: false can_gif_quick_reply: true can_reshare: true reel_type: highlight_reel ad_expiry_timestamp_in_millis: null is_cta_sticker_available: null app_sticker_info: null should_treat_link_sticker_as_cta: null pool_refresh_ttl_in_sec: null can_react_with_avatar: false cover_media: cropped_image_version: width: 150 height: 150 url: https://scontent-dub4-1.cdninstagram.com/v/t51.2885-15/479737232_1405856350793820_7928432152706230890_n.jpg?stp=c0.202.640.640a_dst-jpg_e15_s150x150_tt6&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_cat=100&_nc_oc=Q6cZ2QGmly2VJEPPnYd3yasHydMcSwfCazUKlRXiU5HUJ-zQVPrC9Xb-ho-EFRAjvcUgWnY&_nc_ohc=yQlHN7CDZ7IQ7kNvwFIJktj&_nc_gid=-RHeydtWtdTLhayCKiI3oQ&edm=ANmP7GQBAAAA&ccb=7-5&oh=00_AfKKWP06eveppAsTaksGtYoLYb_lesIro1a34w-gEGgJ8A&oe=682184F5&_nc_sid=982cc7 scans_profile: '' crop_rect: - 0 media_id: '3574665805209826888_21393171' full_image_version: null upload_id: null user: pk: '21393171' pk_id: '21393171' full_name: Jane Williamson is_private: false strong_id__: '21393171' id: '21393171' username: jane is_verified: true profile_pic_id: '3583980709961915639_21393171' profile_pic_url: https://scontent-dub4-1.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QGmly2VJEPPnYd3yasHydMcSwfCazUKlRXiU5HUJ-zQVPrC9Xb-ho-EFRAjvcUgWnY&_nc_ohc=mi86alqirjwQ7kNvwFr3H5A&_nc_gid=-RHeydtWtdTLhayCKiI3oQ&edm=ANmP7GQBAAAA&ccb=7-5&oh=00_AfIKcWUsUpfsBZW0eePl0Z6La3wJHY0FPIj7QRpbwooklA&oe=68218068&_nc_sid=982cc7 interop_messaging_user_fbid: 119713162748634 transparency_product_enabled: false items: - pk: '3565907942018983442' id: '3565907942018983442_21393171' is_visual_reply_commenter_notice_enabled: true like_and_view_counts_disabled: false is_post_live_clips_media: false is_reshare_of_text_post_app_media_in_ig: false is_reel_media: true fbid: '17968033766718273' device_timestamp: 1739309362129426 caption_is_edited: false strong_id__: '3565907942018983442_21393171' is_quicksnap_recap: false deleted_reason: 0 mezql_token: '' imported_taken_at: 1739305646 should_request_ads: false is_terminal_video_segment: false integrity_review_decision: pending client_cache_key: MzU2NTkwNzk0MjAxODk4MzQ0Mg==.3 comment_threading_enabled: true is_unified_video: false commerciality_status: not_commercial caption_position: 0 has_privately_liked: false filter_type: 0 taken_at: 1739309361 hide_view_all_comment_entrypoint: false is_comments_gif_composer_enabled: false video_sticker_locales: [] is_dash_eligible: 1 video_dash_manifest: | https://scontent-dub4-1.cdninstagram.com/o1/v/t2/f2/m367/AQOfoUrcpLyCypvA0r8KJNYVZqRMK_xKgHt6BIIR-2d-pZc8HrSUxb_ADpVH2fHJ_Jga14in9wNDQMKL8YmnSyh2SyuBIi1wH-0GagOjJyNiPExeppA3tiJXWvimPCV3DixoO1Bq.mp4?_nc_cat=108&_nc_sid=9ca052&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_ohc=jqHP6zi0XkIQ7kNvwHHEdKy&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLnN0b3J5LmMyLUMzLmRhc2hfdnA5LWJhc2ljLWdlbjJfMzYwcCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjoxMzc3ODEwOTUzMzg3NzQ2LCJ2aV91c2VjYXNlX2lkIjoxMDEwMCwiZHVyYXRpb25fcyI6NTUsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_zt=28&oh=00_AfJeY5DgeknyRN-Oj5qSXRKzB0wL9yWYB4PyUjf9wvqfgQ&oe=682162E0https://scontent-dub4-1.cdninstagram.com/o1/v/t2/f2/m367/AQNVYK_LcjKX7BfZe6teyHabLQAnRYyvQ0OaomvrOYVCPI39q3Mua18SLdXRP1rLDAWZtmaw0daxwozitRR7QuRlk-yu0u6aNkSo6bVRxWiHWJMrsuFUpZ3wEXzsglQDn__HYhrE.mp4?_nc_cat=101&_nc_sid=9ca052&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_ohc=YsOmqegW-HAQ7kNvwHvk5t6&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLnN0b3J5LmMyLUMzLmRhc2hfdnA5LWJhc2ljLWdlbjJfNTQwcCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjoxMzc3ODEwOTUzMzg3NzQ2LCJ2aV91c2VjYXNlX2lkIjoxMDEwMCwiZHVyYXRpb25fcyI6NTUsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_zt=28&oh=00_AfJClU-cSxarTYZZelf4X843_PLNlpHXaOVA8JeQ4P6KjA&oe=682163B3https://scontent-dub4-1.cdninstagram.com/o1/v/t2/f2/m367/AQMZ2fGGIbfKfEB8WZCN2uo1kyDrbZSRTuS9NuKQsm1kdrgBwIgx5uTkgSSwSrg-HwQGBXwyIV6JLLFGIHufr1R3biAaDoj6ef07ZsEglx5OkMyyYPdnMGzVR8ssmYaKJyFG6xTa.mp4?_nc_cat=101&_nc_sid=9ca052&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_ohc=ZnDVAwVn1J0Q7kNvwFP3y7A&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLnN0b3J5LmMyLUMzLmRhc2hfdnA5LWJhc2ljLWdlbjJfNzIwcCIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjoxMzc3ODEwOTUzMzg3NzQ2LCJ2aV91c2VjYXNlX2lkIjoxMDEwMCwiZHVyYXRpb25fcyI6NTUsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_zt=28&oh=00_AfJI3HBj5B_USsbfjD3mig9BmKADRB-WNgDkLiSNcA9AXg&oe=6821608Bhttps://scontent-dub4-1.cdninstagram.com/o1/v/t2/f2/m367/AQPnP3tyR_xd5vqiR9rHqL4uKAjCLDaAYc0d8G15LFH4_WgzATFrwGXbO3j9AFBXxW_dMMt-bIcZjhcDf9KdKZVBXZfKTpq4NqOdhEyNtKMfJi0pduOiR8a2SGkol-VtVBcSU7y0ow.mp4?_nc_cat=106&_nc_sid=9ca052&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_ohc=Xh9mj1ql7FsQ7kNvwGfdBze&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLnN0b3J5LmMyLUMzLmRhc2hfdnA5LWJhc2ljLWdlbjJfMTA4MHAiLCJ2aWRlb19pZCI6bnVsbCwib2lsX3VybGdlbl9hcHBfaWQiOjkzNjYxOTc0MzM5MjQ1OSwiY2xpZW50X25hbWUiOiJpZyIsInhwdl9hc3NldF9pZCI6MTM3NzgxMDk1MzM4Nzc0NiwidmlfdXNlY2FzZV9pZCI6MTAxMDAsImR1cmF0aW9uX3MiOjU1LCJ1cmxnZW5fc291cmNlIjoid3d3In0%3D&ccb=17-1&_nc_zt=28&oh=00_AfIPo5nYW_cUOteJVej4-Or_9EsE1QoCPgFvyhr3gWNKbQ&oe=68217548https://scontent-dub4-1.cdninstagram.com/o1/v/t16/f2/m69/AQNyWBRlKnroBxnnX-EpqgZgFfAyiJwI-Shbf9Eq1B1Ma9Pxo26PXQBrs_bIP7SJepuJU3-Yyr9hBKTg1ksLVc5x.mp4?strext=1&_nc_cat=107&_nc_sid=9ca052&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_ohc=asFzHjDcgjkQ7kNvwGBmUxq&efg=eyJ2ZW5jb2RlX3RhZyI6ImlnLXhwdmRzLnN0b3J5LmMyLUMzLmRhc2hfbG5faGVhYWNfdmJyM19hdWRpbyIsInZpZGVvX2lkIjpudWxsLCJvaWxfdXJsZ2VuX2FwcF9pZCI6OTM2NjE5NzQzMzkyNDU5LCJjbGllbnRfbmFtZSI6ImlnIiwieHB2X2Fzc2V0X2lkIjoxMzc3ODEwOTUzMzg3NzQ2LCJ2aV91c2VjYXNlX2lkIjoxMDEwMCwiZHVyYXRpb25fcyI6NTUsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_zt=28&oh=00_AfI_TGV4rJPmSPk3Kr05twnv4TiuERYpk8DZGhIPelmVBg&oe=68216059 number_of_qualities: 4 video_versions: - bandwidth: null height: 852 type: 101 url: https://scontent-dub4-1.cdninstagram.com/o1/v/t16/f2/m78/AQN5lthB7AgZeog8GcsUwAQtYg4PrP5y41v_bUs-ydLXFkg6cTCxlHYvYO9pyOGdbZ_h0iB8TpaRmEFn7KAjENMlWQGfsqMod9-9hpU.mp4?stp=dst-mp4&efg=eyJxZV9ncm91cHMiOiJbXCJpZ193ZWJfZGVsaXZlcnlfdnRzX290ZlwiXSIsInZlbmNvZGVfdGFnIjoidnRzX3ZvZF91cmxnZW4uc3RvcnkuYzIuNzIwLmJhc2VsaW5lIn0&_nc_cat=109&vs=622357473721923_1538615199&_nc_vs=HBksFQIYUWlnX3hwdl9wbGFjZW1lbnRfcGVybWFuZW50X3YyL0EwNEZFM0FDNjFERDBFRDJCNEM3MzVENDg5Rjg0MUIwX3ZpZGVvX2Rhc2hpbml0Lm1wNBUAAsgBABUCGDpwYXNzdGhyb3VnaF9ldmVyc3RvcmUvR0FBRlp4eFJSZ1RQaHJnRUFKMlFxRUgyOGE4dmJwa3dBQUFGFQICyAEAKAAYABsBiAd1c2Vfb2lsATEVAAAmmOLA9%2FDQi0AVAigCQzMsF0BL7tkWhysCGBJkYXNoX2Jhc2VsaW5lXzFfdjERAHXoB2XonQEA&_nc_rid=e09fae6dc1&ccb=9-4&oh=00_AfImyX203uNPxGHYxtNoPwuoBmW0eyV_W9nDNXbdQqs-jw&oe=681D7FBB&_nc_sid=982cc7 width: 480 video_duration: 55.85 has_audio: true can_viewer_save: false shop_routing_user_id: null is_organic_product_tagging_eligible: false product_suggestions: [] photo_of_you: false can_see_insights_as_brand: false media_type: 2 code: DF8pmFZySYS caption: null sharing_friction_info: bloks_app_url: null should_have_sharing_friction: false sharing_friction_payload: null timeline_pinned_user_ids: [] has_translation: false original_media_has_visual_reply_media: false coauthor_producers: [] coauthor_producer_can_see_organic_insights: false invited_coauthor_producers: [] is_in_profile_grid: false profile_grid_control_enabled: false user: fbid_v2: '17841400515130334' full_name: Jane Williamson id: '21393171' username: jane owner: full_name: Jane Williamson id: '21393171' is_private: false pk: '21393171' pk_id: '21393171' strong_id__: '21393171' account_type: 3 account_badges: [] hd_profile_pic_versions: - height: 640 url: https://scontent-dub4-1.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s640x640_tt6&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QGmly2VJEPPnYd3yasHydMcSwfCazUKlRXiU5HUJ-zQVPrC9Xb-ho-EFRAjvcUgWnY&_nc_ohc=mi86alqirjwQ7kNvwFr3H5A&_nc_gid=-RHeydtWtdTLhayCKiI3oQ&edm=ANmP7GQBAAAA&ccb=7-5&oh=00_AfKHfZWBKEMcV8VY_66mTQTcYrFT7E1o3ZFIYULu6d9U4g&oe=68218068&_nc_sid=982cc7 width: 640 is_verified: true profile_pic_id: '3583980709961915639_21393171' profile_pic_url: https://scontent-dub4-1.cdninstagram.com/v/t51.2885-19/482782944_496357423346018_5818268903424754264_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2QGmly2VJEPPnYd3yasHydMcSwfCazUKlRXiU5HUJ-zQVPrC9Xb-ho-EFRAjvcUgWnY&_nc_ohc=mi86alqirjwQ7kNvwFr3H5A&_nc_gid=-RHeydtWtdTLhayCKiI3oQ&edm=ANmP7GQBAAAA&ccb=7-5&oh=00_AfIKcWUsUpfsBZW0eePl0Z6La3wJHY0FPIj7QRpbwooklA&oe=68218068&_nc_sid=982cc7 username: jane image_versions2: candidates: - width: 640 height: 1136 url: https://scontent-dub4-1.cdninstagram.com/v/t51.2885-15/477141407_979589986999224_2561193507868444490_n.jpg?stp=dst-jpg_e15_tt6&_nc_ht=scontent-dub4-1.cdninstagram.com&_nc_cat=100&_nc_oc=Q6cZ2QGmly2VJEPPnYd3yasHydMcSwfCazUKlRXiU5HUJ-zQVPrC9Xb-ho-EFRAjvcUgWnY&_nc_ohc=BTubnUZn6m0Q7kNvwFRIO27&_nc_gid=-RHeydtWtdTLhayCKiI3oQ&edm=ANmP7GQBAAAA&ccb=7-5&oh=00_AfJFG9jHyUa3ScFpjHIIow0vTwwkmkSJygTELwHelaQf9Q&oe=68215FCA&_nc_sid=982cc7 scans_profile: '' original_width: 1080 original_height: 1920 product_type: story is_paid_partnership: false music_metadata: null ig_media_sharing_disabled: false boost_unavailable_identifier: null boost_unavailable_reason: null boost_unavailable_reason_v2: [] subscribe_cta_visible: false is_cutout_sticker_allowed: false cutout_sticker_info: [] fb_aggregated_like_count: 0 fb_aggregated_comment_count: 0 open_carousel_show_follow_button: false is_tagged_media_shared_to_viewer_profile_grid: false should_show_author_pog_for_tagged_media_shared_to_profile_grid: false is_open_to_public_submission: false likers: [] archive_story_deletion_ts: 0 can_send_prompt: false is_first_take: false is_from_discovery_surface: false is_rollcall_v2: false supports_reel_reactions: true is_photo_mash_story: false can_play_spotify_audio: false is_superlative: false show_one_tap_fb_share_tooltip: true can_reply: false can_reshare: true is_nux: false title: GRWM chats created_at: 1743889595 is_pinned_highlight: false prefetch_count: 0 media_count: 25 media_ids: - '3565907942018983442' is_converted_to_clips: false disabled_reply_types: - story_remix_reply highlight_reel_type: DEFAULT is_added_to_main_grid: false is_archived: false is_fit_green: true schema: $ref: '#/components/schemas/InstagramHighlightDetailResponse' '404': description: Highlight not found, deleted, private, or unavailable for the provided highlight ID. content: application/json: schema: $ref: '#/components/schemas/AIsaSocialError' x-x402: path: /apis/v2/instagram/user/highlight/detail source: https://github.com/AIsa-team/aisa-proxy /instagram/user/embed: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Instagram operationId: get_instagram_user_embed summary: User Embed description: 'Returns Instagram''s official profile embed widget for a handle as a single html string, ready to drop into a web page. Measured at about 206 KB, nearly all of it inlined markup and styling, so treat the result as something to store or render rather than something to read. It carries no structured profile data at all: for follower counts, biography or bio links use get_instagram_basic_profile when the numeric id is known, or get_instagram_profile when only the handle is.' parameters: - name: handle in: query required: true description: Instagram handle schema: type: string example: jane responses: '200': description: Successful response content: application/json: example: success: true html: |- / URL, and clips_metadata.original_sound_info.audio_asset_id on any reel returned by get_instagram_user_reels. Measured at about 177 KB for five reels, in the same raw shape as get_instagram_user_reels rather than the normalised shape of the search endpoints. To find reels by keyword instead of by sound, use get_instagram_reels_search.' parameters: - name: audio_id in: query required: true description: The audio id from the Instagram audio page URL. schema: type: string example: '1392969992841787' - name: cursor in: query required: false description: Pagination cursor returned by Instagram from the previous response. schema: type: string example: Gsbyq-aju4eF02y... responses: '200': description: Successful response content: application/json: example: success: true credits_remaining: 49996450280 reels: - gen_ai_chat_with_ai_cta_info: null collaborator_edit_eligibility: false number_of_qualities: 6 related_ads_pivots_media_info: USER_NOT_IN_TEST_GROUP is_artist_pick: false translated_langs_for_autodub: [] subtype_name_for_REST__: XDTClipsMedia is_eligible_for_poe: false original_lang_for_translations: en eligible_insights_entrypoints: NONE igbio_product: null hidden_likes_string_variant: -1 is_social_ufi_disabled: false boost_unavailable_reason: null boost_unavailable_identifier: null boost_unavailable_reason_v2: [] client_cache_key: MzkxNDQ4MzYyNDQ0NjgzOTU0NQ==.3 can_reply: false photo_of_you: false media_attributions_data: [] can_view_more_preview_comments: false mezql_token: '' has_tagged_users: false is_eligible_content_for_post_roll_ad: false is_cutout_sticker_allowed: false is_photo_comments_composer_enabled_for_author: false hide_view_all_comment_entrypoint: false has_liked: false is_organic_product_tagging_eligible: false view_state_item_type: 128 video_sticker_locales: [] is_paid_partnership: false is_in_profile_grid: false is_tagged_media_shared_to_viewer_profile_grid: false should_show_author_pog_for_tagged_media_shared_to_profile_grid: false inventory_source: recommended_clips_chaining_model integrity_review_decision: pending has_delayed_metadata: false filter_type: 0 deleted_reason: 0 device_timestamp: 1780862828857832 is_reshare_of_text_post_app_media_in_ig: false timeline_pinned_user_ids: [] is_open_to_public_submission: false profile_grid_control_enabled: false can_see_insights_as_brand: false media_reposter_bottomsheet_enabled: false coauthor_producer_can_see_organic_insights: false share_count_disabled: false is_visual_reply_commenter_notice_enabled: true should_request_ads: false subscribe_cta_visible: false sharing_friction_info: bloks_app_url: null sharing_friction_payload: null should_have_sharing_friction: false media_overlay_info: null fb_user_tags: in: [] coauthor_producers: [] cutout_sticker_info: [] invited_coauthor_producers: [] gen_ai_detection_method: detection_method: NONE comment_inform_treatment: should_have_inform_treatment: false text: '' action_type: null url: null creative_config: null caption: strong_id__: '18003972137927139' pk: '18003972137927139' bit_flags: 0 content_type: comment created_at: 1780863179 created_at_utc: 1780863179 did_report_as_spam: false is_covered: false is_ranked_comment: false media_id: '3914483624446839545' private_reply_status: 0 share_enabled: false status: Active text: "Thank you so much to the @rangers for having us out to throw the first pitch. Absolute bucket list\ \ item \n\n\U0001F3A5 @derekhockemeyer \n\n#rangers #rockmusic #baseball #mlb" type: 1 user: strong_id__: '50380429276' id: '50380429276' pk: 50380429276 pk_id: '50380429276' username: the_moonrocks full_name: Dexter and The Moonrocks is_private: false is_verified: true profile_pic_id: '3596544531479280878_50380429276' profile_pic_url: https://scontent-bos5-1.cdninstagram.com/v/t51.2885-19/486451888_876116764599836_2484139502902255595_n.jpg?stp=dst-jpg_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDAwLmMyIn0&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2gErZlYFtNgTJHTyDqaQXA7j57JH6I22iRoOkDAGIiYeRo10okFoVMUQF0K8EhLDpz0&_nc_ohc=3AKPMsLISg8Q7kNvwEqyLZS&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&edm=APs17CUBAAAA&ccb=7-5&oh=00_Af9_QPU6gb7UXgbF-8oArHR3Sl88g02CcWe_rjkVHhRegg&oe=6A2D115C&_nc_sid=10d13b fbid_v2: '17841450318307553' is_unpublished: false user_id: 50380429276 music_metadata: null meta_ai_suggested_prompts: [] user: is_embeds_disabled: false id: '50380429276' pk: 50380429276 pk_id: '50380429276' strong_id__: '50380429276' fbid_v2: '17841450318307553' profile_pic_id: '3596544531479280878_50380429276' profile_pic_url: https://scontent-bos5-1.cdninstagram.com/v/t51.2885-19/486451888_876116764599836_2484139502902255595_n.jpg?stp=dst-jpg_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDAwLmMyIn0&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2gErZlYFtNgTJHTyDqaQXA7j57JH6I22iRoOkDAGIiYeRo10okFoVMUQF0K8EhLDpz0&_nc_ohc=3AKPMsLISg8Q7kNvwEqyLZS&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&edm=APs17CUBAAAA&ccb=7-5&oh=00_Af9_QPU6gb7UXgbF-8oArHR3Sl88g02CcWe_rjkVHhRegg&oe=6A2D115C&_nc_sid=10d13b eligible_for_text_app_activation_badge: false interop_messaging_user_fbid: '17851906964677277' username: the_moonrocks full_name: Dexter and The Moonrocks is_private: false is_unpublished: false is_verified: true show_account_transparency_details: true transparency_product_enabled: false third_party_downloads_enabled: 1 feed_post_reshare_disabled: false account_badges: [] account_type: 3 has_anonymous_profile_picture: false fan_club_info: autosave_to_exclusive_highlight: null connected_member_count: null fan_club_id: null fan_club_name: null fan_consideration_page_revamp_eligiblity: null has_enough_subscribers_for_ssc: null is_fan_club_gifting_eligible: null is_fan_club_referral_eligible: null subscriber_count: null has_created_ssc: null is_free_trial_eligible: null largest_public_bc_id: null should_show_playlists_in_profile_tab: null clips_metadata: achievements_info: num_earned_achievements: null show_achievements: false additional_audio_info: additional_audio_username: null audio_reattribution_info: should_allow_restore: false asset_recommendation_info: null audio_ranking_info: best_audio_cluster_id: '1392969992841787' audio_type: licensed_music branded_content_tag_info: can_add_tag: false clips_creation_entry_point: feed content_appreciation_info: enabled: true entry_point_container: comment: action_type: gifting overflow: null pill: action_type: gifting priority: 1 contextual_highlight_info: null cutout_sticker_info: [] disable_use_in_clips_client_cache: false featured_label: null is_fan_club_promo_video: null is_public_chat_welcome_video: false is_shared_to_fb: false mashup_info: can_toggle_mashups_allowed: false formatted_mashups_count: null has_been_mashed_up: false has_nonmimicable_additional_audio: false is_creator_requesting_mashup: false is_light_weight_check: true is_pivot_page_available: false is_light_weight_reuse_allowed_check: false is_reuse_allowed: false mashup_type: null mashups_allowed: false non_privacy_filtered_mashups_media_count: 0 original_media: null privacy_filtered_mashups_media_count: null music_canonical_id: '18455463055100927' music_info: music_asset_info: allows_saving: false artist_id: '318791467948898' audio_asset_id: '1655474642367036' audio_cluster_id: '1392969992841787' cover_artwork_thumbnail_uri: https://scontent-bos5-1.xx.fbcdn.net/v/t39.30808-6/650332792_71060841314503_1416809917085791775_n.jpg?stp=dst-jpg_s168x128_tt6&_nc_cat=1&ccb=1-7&_nc_sid=2f2557&_nc_ohc=nPTxUb7rZPUQ7kNvwGEs4zR&_nc_oc=AdrmbkQxsSMO4Rx1aiI5cZYpc6B3nD2bPqqeRveKVB-9NP2astJfuhYkSTdqS-9UqEE&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7a20f&oh=00_Af_VBrgk1I7krwXYJ1QGlcUcctWs9p3-6cPUOmnlXjHhCQ&oe=6A2CF4CE cover_artwork_uri: https://scontent-bos5-1.xx.fbcdn.net/v/t39.30808-6/650332792_71060841314503_1416809917085791775_n.jpg?stp=dst-jpg_s261x260_tt6&_nc_cat=1&ccb=1-7&_nc_sid=2f2557&_nc_ohc=nPTxUb7rZPUQ7kNvwGEs4zR&_nc_oc=AdrmbkQxsSMO4Rx1aiI5cZYpc6B3nD2bPqqeRveKVB-9NP2astJfuhYkSTdqS-9UqEE&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-bos5-1.xx&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7a20f&oh=00_Af9u_cA6sILr-aFzE0_Ko4cdGK-WT8leUFtCRDWxDH-8rw&oe=6A2CF4CE dark_message: null dash_manifest: null display_artist: Dexter and The Moonrocks duration_in_ms: 217897 fast_start_progressive_download_url: https://video-bos5-1.xx.fbcdn.net/o1/v/t2/f2/m69/AQNlty8t4cP3Rq5yxfHtP_PoPO2pxMe6gh7PD8ha85O3RN4Nj-nQHLnRyUZmr2Aqi9lazeXNN_jutk3-vbuZPaj5.mp4?strext=1&_nc_cat=105&_nc_sid=8bf8fe&_nc_ht=video-bos5-1.xx.fbcdn.net&_nc_ohc=0ZYQDpcAGukQ7kNvwG99Idh&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMC5wcm9ncmVzc2l2ZV9hdWRpb19hYWNwXzQ4X2ZyYWdfMl9hdWRpbyIsInhwdl9hc3NldF9pZCI6OTY5NzMzOTU1NDcwOTAzLCJhc3NldF9hZ2VfZGF5cyI6NDcsInZpX3VzZWNhc2VfaWQiOjEwNTY4LCJkdXJhdGlvbl9zIjoyMTcsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_ad=z-m&_nc_cid=0&_nc_zt=28&_nc_ss=7a20f&oh=00_Af-taeSVWSjiUVS0Yn3LbZMCfyh3gB0SlRx7cXsPKv2U2g&oe=6A2CE3D5 has_lyrics: false highlight_start_times_in_ms: - 59000 id: '1655474642367036' ig_username: the_moonrocks is_eligible_for_audio_effects: true is_explicit: false progressive_download_url: https://video-bos5-1.xx.fbcdn.net/o1/v/t2/f2/m69/AQNlty8t4cP3Rq5yxfHtP_PoPO2pxMe6gh7PD8ha85O3RN4Nj-nQHLnRyUZmr2Aqi9lazeXNN_jutk3-vbuZPaj5.mp4?strext=1&_nc_cat=105&_nc_sid=8bf8fe&_nc_ht=video-bos5-1.xx.fbcdn.net&_nc_ohc=0ZYQDpcAGukQ7kNvwG99Idh&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMC5wcm9ncmVzc2l2ZV9hdWRpb19hYWNwXzQ4X2ZyYWdfMl9hdWRpbyIsInhwdl9hc3NldF9pZCI6OTY5NzMzOTU1NDcwOTAzLCJhc3NldF9hZ2VfZGF5cyI6NDcsInZpX3VzZWNhc2VfaWQiOjEwNTY4LCJkdXJhdGlvbl9zIjoyMTcsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_ad=z-m&_nc_cid=0&_nc_zt=28&_nc_ss=7a20f&oh=00_Af-taeSVWSjiUVS0Yn3LbZMCfyh3gB0SlRx7cXsPKv2U2g&oe=6A2CE3D5 reactive_audio_download_url: null sanitized_title: null subtitle: '' title: Freakin’ Out spotify_track_metadata: null lyrics: null song_monetization_info: null licensed_music_subtype: DEFAULT is_eligible_for_vinyl_sticker: false web_30s_preview_download_url: https://video-bos5-1.xx.fbcdn.net/o1/v/t2/f2/m69/AQNJXvbeaJen3t4kfNe5DHW1PGPqDEzS7O3GuXnWuuGTDobzQc1cfTLeb8362d2F34mq2GBbvFZHzX6imv-Zxtj8.mp4?strext=1&_nc_cat=111&_nc_sid=8bf8fe&_nc_ht=video-bos5-1.xx.fbcdn.net&_nc_ohc=-qwRe0jKEBkQ7kNvwGkqE67&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMC5wcm9ncmVzc2l2ZV9hdWRpb19hYWNwXzQ4X2ZyYWdfMl9hdWRpbyIsInhwdl9hc3NldF9pZCI6OTY5NzMzOTU1NDcwOTAzLCJhc3NldF9hZ2VfZGF5cyI6NDcsInZpX3VzZWNhc2VfaWQiOjEwNTY4LCJkdXJhdGlvbl9zIjoyMTcsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_ss=7a20f&_nc_ad=z-m&_nc_cid=0&_nc_zt=28&oh=00_Af8Uh5Atfr_g51m4GsSV7QmVvq0uRP1IQ1OGLfbmdPsUJg&oe=6A2D12DB music_consumption_info: allow_media_creation_with_music: false audio_asset_start_time_in_ms: 155500 derived_content_start_time_in_composition_in_ms: null display_labels: null audio_filter_infos: [] audio_muting_info: allow_audio_editing: false mute_audio: false mute_reason_str: '' show_muted_audio_toast: false contains_lyrics: null derived_content_id: null ig_artist: strong_id__: '50380429276' id: '50380429276' full_name: Dexter and The Moonrocks is_private: false is_verified: true pk: 50380429276 pk_id: '50380429276' profile_pic_id: '3596544531479280878_50380429276' profile_pic_url: https://scontent-bos5-1.cdninstagram.com/v/t51.2885-19/486451888_876116764599836_2484139502902255595_n.jpg?stp=dst-jpg_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDAwLmMyIn0&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2gErZlYFtNgTJHTyDqaQXA7j57JH6I22iRoOkDAGIiYeRo10okFoVMUQF0K8EhLDpz0&_nc_ohc=3AKPMsLISg8Q7kNvwEqyLZS&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&edm=APs17CUBAAAA&ccb=7-5&oh=00_Af9_QPU6gb7UXgbF-8oArHR3Sl88g02CcWe_rjkVHhRegg&oe=6A2D115C&_nc_sid=10d13b username: the_moonrocks is_bookmarked: false is_trending_in_clips: true overlap_duration_in_ms: 30000 placeholder_profile_pic_url: https://scontent-bos5-1.cdninstagram.com/v/t51.12442-15/43985629_311105916145351_58064759811405776_n.jpg?_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_cat=107&_nc_oc=Q6cZ2gErZlYFtNgTJHTyDqaQXA7j57JH6I22iRoOkDAGIiYeRo10okFoVMUQF0K8EhLDpz0&_nc_ohc=SlIu03LaJRcQ7kNvwEmBEgx&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&edm=APs17CUAAAAA&ccb=7-5&oh=00_Af-tDtQphNDB6gjPndM-HI6TrVRjd1LZ6mJl1F4ctLr50g&oe=6A2D013D&_nc_sid=10d13b should_allow_music_editing: false should_mute_audio: false should_mute_audio_reason: '' should_render_soundwave: false trend_rank: null previous_trend_rank: null nux_info: null original_sound_info: null originality_info: null professional_clips_upsell_type: 0 show_achievements: false reels_on_the_rise_info: null reusable_text_attribute_string: null reusable_text_info: null shopping_info: null template_info: null viewer_interaction_settings: null id: '3914483624446839545_50380429276' strong_id__: '3914483624446839545_50380429276' pk: '3914483624446839545' fbid: '18003971210927139' media_type: 2 like_and_view_counts_disabled: false code: DZTCh3aPMr5 taken_at: 1780862943 product_type: clips caption_is_edited: true can_viewer_reshare: true can_viewer_save: true comment_count: 121 are_remixes_crosspostable: true video_versions: - url: https://scontent-bos5-1.cdninstagram.com/o1/v/t2/f2/m86/AQOGLJxmYlSItzvuJWTmTE6GeF4lsAdDGFMbQ0Twjb94gD4vUyObNmSHG6bml937oZnJrLKX-9ByZ5DHuzCAVt11ZH8YBfJC0JWfXHs.mp4?_nc_cat=108&_nc_sid=5e9851&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_ohc=VtHMjdRHADsQ7kNvwF8NAld&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5JTlNUQUdSQU0uQ0xJUFMuQzMuNzIwLmRhc2hfYmFzZWxpbmVfMV92MSIsInhwdl9hc3NldF9pZCI6OTM3MjMwOTM5MzU5ODY2LCJhc3NldF9hZ2VfZGF5cyI6MSwidmlfdXNlY2FzZV9pZCI6MTAwOTksImR1cmF0aW9uX3MiOjMwLCJ1cmxnZW5fc291cmNlIjoid3d3In0%3D&ccb=17-1&vs=d0fb3e3e71a6f5c9&_nc_vs=HBksFQIYUmlnX3hwdl9yZWVsc19wZXJtYW5lbnRfc3JfcHJvZC9ENTQzODc1Q0I5NTU4MzZGMThDRkM1Qjg0NzI0OUZBMl92aWRlb19kYXNoaW5pdC5tcDQVAALIARIAFQIYUWlnX3hwdl9wbGFjZW1lbnRfcGVybWFuZW50X3YyL0FENDQzRUM2NEJDNzcyQzY5NDE0NEM3OEFBNEVFMzk5X2F1ZGlvX2Rhc2hpbml0Lm1wNBUCAsgBEgAoABgAGwKIB3VzZV9vaWwBMRJwcm9ncmVzc2l2ZV9yZWNpcGUBMRUAACb0qbTTgpqqAxUCKAJDMywXQD71P3ztkWgYEmRhc2hfYmFzZWxpbmVfMV92MREAdf4HZeadAQA&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7e289&_nc_zt=28&oh=00_Af86p9gyqJtDsQCzujuJCr6KuJVQjAxSRBUO1p35jieb_A&oe=6A291B95 height: 1280 width: 720 type: 101 id: 2075839049633029v fallback: null url_expiration_timestamp_us: null bandwidth: 874348 image_versions2: candidates: - estimated_scans_sizes: [] height: 1136 scans_profile: null url: https://scontent-bos5-1.cdninstagram.com/v/t51.71878-15/719150226_27489725720657752_5945269205704640767_n.jpg?stp=dst-jpg_e15_tt6&_nc_cat=103&ig_cache_key=MzkxNDQ4MzYyNDQ0NjgzOTU0NQ%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLnhwaWRzLjY0MC5zZHIudmlkZW9fbmZyYW1lX2NvdmVyX2ZyYW1lLkMzIn0%3D&_nc_ohc=YsjbeqoIlyIQ7kNvwG4yguV&_nc_oc=AdqP5h5UJ6Kk9KASXyBG0uFMcfSgn6jN1fZAbONRrv2xm_XauNoZ8t2eS8N1LCx8D8c&_nc_zt=23&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7e289&oh=00_Af-7yvBgX7dgv9Hr8a_e4w4m-6baxzL6O9vAR4g7FCB51Q&oe=6A2CEEC4 width: 640 additional_candidates: first_frame: estimated_scans_sizes: [] height: 1136 scans_profile: null url: https://scontent-bos5-1.cdninstagram.com/v/t51.71878-15/720049395_2200373580753187_8434766665708624590_n.jpg?stp=dst-jpg_e15_tt6&_nc_cat=111&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLnhwaWRzLjY0MC5zZHIudmlkZW9fYWRkaXRpb25hbF9jb3Zlcl9mcmFtZS5DMyJ9&_nc_ohc=-k4KWqs4qJUQ7kNvwHHtR92&_nc_oc=AdodPhI3iMDbI-P3JXu3JXLpyqeS7wEERLo8aAB0XMO7D6v-DlIPj2VGlwpYBlOhv4U&_nc_zt=23&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7e289&oh=00_Af-Bol1OQ2bSlFr5Ev8aJ6vZVHQQKwI4mJhtY2i41uYxKQ&oe=6A2D02FC width: 640 igtv_first_frame: estimated_scans_sizes: [] height: 1136 scans_profile: null url: https://scontent-bos5-1.cdninstagram.com/v/t51.71878-15/720049395_2200373580753187_8434766665708624590_n.jpg?stp=dst-jpg_e15_tt6&_nc_cat=111&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLnhwaWRzLjY0MC5zZHIudmlkZW9fYWRkaXRpb25hbF9jb3Zlcl9mcmFtZS5DMyJ9&_nc_ohc=-k4KWqs4qJUQ7kNvwHHtR92&_nc_oc=AdodPhI3iMDbI-P3JXu3JXLpyqeS7wEERLo8aAB0XMO7D6v-DlIPj2VGlwpYBlOhv4U&_nc_zt=23&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7e289&oh=00_Af-Bol1OQ2bSlFr5Ev8aJ6vZVHQQKwI4mJhtY2i41uYxKQ&oe=6A2D02FC width: 640 smart_frame: null scrubber_spritesheet_info_candidates: default: sprite_urls: - https://scontent-bos5-1.cdninstagram.com/v/t51.71878-15/719939421_982614911077420_7014871733430920682_n.jpg?_nc_cat=111&ccb=7-5&_nc_sid=efdbef&_nc_ohc=BnmNS3_UWBMQ7kNvwGsvBNv&_nc_oc=AdolU3DvhiwbPBNGZ3E9go6Qpqg4YEAW_VmwVwNi5_r95-mdjFXCmaxugz181YIO-LA&_nc_zt=23&_nc_ht=scontent-bos5-1.cdninstagram.com&_nc_gid=Cb947IFjRDhbeOoUvuQPcg&_nc_ss=7e289&oh=00_Af9E7tePOa73YroEspTO_PwuUO39y5nonHLkVn3bOd5qdg&oe=6A2CFE9D file_size_kb: 441 max_thumbnails_per_sprite: 105 rendered_width: 96 sprite_height: 1232 sprite_width: 1500 thumbnail_duration: 0.2948380952381 thumbnail_height: 176 thumbnail_width: 100 thumbnails_per_row: 15 total_thumbnail_num_per_sprite: 105 video_length: 30.958 smart_thumbnail_enabled: null has_audio: true like_count: 20308 locations: [] is_dash_eligible: 1 is_unified_video: false enable_media_notes_production: false play_count: 293700 fb_play_count: 58317 ig_play_count: 235383 is_third_party_downloads_eligible: true original_width: 1080 original_height: 1920 is_reuse_allowed: false has_shared_to_fb: 0 has_privately_liked: false ig_media_sharing_disabled: false organic_tracking_token: eyJ2ZXJzaW9uIjo2LCJwYXlsb2FkIjp7ImlzX2FuYWx5dGljc190cmFja2VkIjp0cnVlLCJ1dWlkIjoiQXc4U3NPanhycVJzc2ZzQkxXVTh1SkQzOTE0NDgzNjI0NDQ2ODM5NTQ1Iiwic2VydmVyX3Rva2VuIjoiMTc4MDk1MTYwMjQ4MnwzOTE0NDgzNjI0NDQ2ODM5NTQ1fDUwMzgwNDI5Mjc2fGEwOWFhNDBmMTY0YzMxNGI4NmYxNWJjMzI0NjM2MjA0ZDRlNTdjZTFkMDYwZTAzN2E4YTQ4NmRiZTJiNzk3NzQifSwic2lnbmF0dXJlIjoiIn0= has_views_fetching: true video_duration: 30.973 is_post_live_clips_media: false is_quiet_post: false is_comments_gif_composer_enabled: false clips_tab_pinned_user_ids: [] cursor: Gsbyq.... has_more: true schema: $ref: '#/components/schemas/InstagramReelsResponse' x-x402: path: /apis/v2/instagram/song/reels source: https://github.com/AIsa-team/aisa-proxy /embeddings: post: summary: Create embeddings description: Generate embedding vectors for one or more input strings using jina-embeddings-v3 or jina-embeddings-v5-text-small (both 1024-dim output). OpenAI-compatible request and response. Served via the AIsa relay path /v1/embeddings. Billing is token-based at $0.050 per 1M tokens. operationId: createEmbedding requestBody: required: true content: application/json: schema: type: object required: - model - input properties: model: type: string description: 'Embedding model name. Available: jina-embeddings-v3 or jina-embeddings-v5-text-small (both 1024-dim).' enum: - jina-embeddings-v3 - jina-embeddings-v5-text-small example: jina-embeddings-v3 input: description: A non-empty string, or an array of non-empty strings, to embed. oneOf: - type: string - type: array items: type: string minItems: 1 example: A fast, OpenAI-compatible embeddings endpoint. example: model: jina-embeddings-v3 input: A fast, OpenAI-compatible embeddings endpoint. responses: '200': description: Embedding list. content: application/json: schema: type: object properties: object: type: string example: list data: type: array items: type: object properties: object: type: string example: embedding index: type: integer example: 0 embedding: type: array description: 1024-dim embedding vector. items: type: number format: float model: type: string example: jina-embeddings-v3 usage: type: object properties: total_tokens: type: integer example: 9 example: object: list data: - object: embedding index: 0 embedding: - 0.0123 - -0.0456 - 0.0789 model: jina-embeddings-v3 usage: total_tokens: 9 tags: - Other servers: - url: https://api.aisa.one/v1 /rerank: post: summary: Rerank documents description: Rerank a list of documents against a query using jina-reranker-v3, returning documents ordered by relevance score. Served via the AIsa relay path /v1/rerank. Billing is token-based at $0.050 per 1M tokens. operationId: createRerank requestBody: required: true content: application/json: schema: type: object required: - model - query - documents properties: model: type: string description: Rerank model name. example: jina-reranker-v3 query: type: string description: Non-empty query string to rank documents against. example: What is the capital of France? documents: type: array description: Non-empty array of document strings to rerank. minItems: 1 items: type: string example: - Paris is the capital of France. - Berlin is the capital of Germany. - The Eiffel Tower is in Paris. top_n: type: integer description: Optional. Return only the top N most relevant documents. example: 2 example: model: jina-reranker-v3 query: What is the capital of France? documents: - Paris is the capital of France. - Berlin is the capital of Germany. - The Eiffel Tower is in Paris. top_n: 2 responses: '200': description: Reranked results ordered by relevance. content: application/json: schema: type: object properties: model: type: string example: jina-reranker-v3 results: type: array items: type: object properties: index: type: integer description: Index of the document in the original request array. example: 0 relevance_score: type: number format: float example: 0.98 document: type: object properties: text: type: string example: Paris is the capital of France. usage: type: object properties: total_tokens: type: integer example: 27 example: model: jina-reranker-v3 results: - index: 0 relevance_score: 0.98 document: text: Paris is the capital of France. - index: 2 relevance_score: 0.71 document: text: The Eiffel Tower is in Paris. usage: total_tokens: 27 tags: - Other servers: - url: https://api.aisa.one/v1 /kalshi/markets: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.02 cost_tier: med summary: Get Kalshi Markets description: |- List markets on Kalshi, the CFTC-regulated US prediction exchange, with live bid/ask quotes in dollars. Use this when you need odds from a regulated venue, or to cross-check a Polymarket price against a second market; fetch specific markets with `tickers` (comma-separated), scope to a group with `event_ticker` / `series_ticker`, or narrow with `status`, `search`, and the created / close / settled timestamp ranges. Returns `markets[]` with `title`, `status`, `yes_bid_dollars` / `yes_ask_dollars`, `last_price_dollars`, `volume_fp`, `open_interest_fp`, and `rules_primary` (the settlement criteria), plus a `cursor` to page with. For executed fills rather than quotes, use `get_kalshi_trades`. For the crypto-native venue carrying similar questions, use `get_polymarket_markets`. operationId: get_kalshi_markets parameters: - name: tickers in: query required: false description: Comma-separated Kalshi market tickers to retrieve. schema: type: string example: KXMVESPORTSMULTIGAMEEXTENDED-S20268A776ACB3C6-43886DEE17A - name: event_ticker in: query required: false description: Filter by a single Kalshi event ticker. schema: type: string example: KXMVESPORTSMULTIGAMEEXTENDED-S20268A776ACB3C6 - name: search in: query required: false description: Search markets by keywords in title and description. Must be URL encoded (e.g., 'bitcoin%20price' for 'bitcoin price'). schema: type: string example: bitcoin - name: status in: query required: false description: Filter markets by status. schema: type: string enum: - unopened - open - paused - closed - settled example: open - name: limit in: query required: false description: Number of results per page. Defaults to 100. Maximum value is 1000. schema: type: integer format: int64 minimum: 0 maximum: 1000 default: 100 example: 100 - name: cursor in: query required: false description: Pagination cursor from the previous response. schema: type: string - name: series_ticker in: query required: false description: Filter by series ticker. schema: type: string - name: min_created_ts in: query required: false description: Filter markets created after this Unix timestamp. schema: type: integer format: int64 - name: max_created_ts in: query required: false description: Filter markets created before this Unix timestamp. schema: type: integer format: int64 - name: min_updated_ts in: query required: false description: Filter markets updated after this Unix timestamp. schema: type: integer format: int64 - name: max_close_ts in: query required: false description: Filter markets closing before this Unix timestamp. schema: type: integer format: int64 - name: min_close_ts in: query required: false description: Filter markets closing after this Unix timestamp. schema: type: integer format: int64 - name: min_settled_ts in: query required: false description: Filter markets settled after this Unix timestamp. schema: type: integer format: int64 - name: max_settled_ts in: query required: false description: Filter markets settled before this Unix timestamp. schema: type: integer format: int64 - name: mve_filter in: query required: false description: Filter by multivariate events. schema: type: string enum: - only - exclude responses: '200': description: Kalshi markets response with pagination content: application/json: schema: type: object properties: cursor: type: string description: Cursor for the next page. markets: type: array items: type: object additionalProperties: true properties: ticker: type: string event_ticker: type: string title: type: string status: type: string result: type: string market_type: type: string strike_type: type: string response_price_units: type: string yes_bid_dollars: type: string yes_ask_dollars: type: string no_bid_dollars: type: string no_ask_dollars: type: string last_price_dollars: type: string liquidity_dollars: type: string notional_value_dollars: type: string volume_fp: type: string volume_24h_fp: type: string open_interest_fp: type: string created_time: type: string updated_time: type: string open_time: type: string close_time: type: string expiration_time: type: string latest_expiration_time: type: string expected_expiration_time: type: string can_close_early: type: boolean fractional_trading_enabled: type: boolean custom_strike: type: object additionalProperties: true mve_selected_legs: type: array items: type: object additionalProperties: true rules_primary: type: string rules_secondary: type: string required: - markets '400': description: Bad Request - Invalid parameters or validation errors content: application/json: schema: type: object properties: error: type: string example: Invalid limit parameter message: type: string example: limit must be a number between 1 and 100 tags: - Prediction Markets x-x402: path: /apis/v2/kalshi/markets source: https://github.com/AIsa-team/aisa-proxy /kalshi/trades: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.02 cost_tier: med summary: Get Kalshi Trades description: |- Get the executed-trade tape for Kalshi markets — actual fills, not quotes. Use this when you need realized prices and traded size over a window, for example to see how conviction moved while an event unfolded; narrow with `ticker` and the `min_ts` / `max_ts` Unix-second range, and set `is_block_trade` to isolate large negotiated trades. Returns `trades[]` with `trade_id`, `ticker`, `count_fp` (contracts), `yes_price_dollars` / `no_price_dollars`, `taker_side`, and `created_time`, plus a `cursor` to page with. For the current quotes, settlement rules, and market metadata rather than fills, use `get_kalshi_markets`. operationId: get_kalshi_trades parameters: - name: limit in: query required: false description: Number of results per page. Defaults to 100. Maximum value is 1000. schema: type: integer format: int64 minimum: 0 maximum: 1000 default: 100 example: 100 - name: cursor in: query required: false description: Pagination cursor from the previous response. schema: type: string - name: ticker in: query required: false description: Filter by Kalshi market ticker. schema: type: string example: KXMVESPORTSMULTIGAMEEXTENDED-S20268A776ACB3C6-43886DEE17A - name: min_ts in: query required: false description: Filter trades after this Unix timestamp. schema: type: integer format: int64 - name: max_ts in: query required: false description: Filter trades before this Unix timestamp. schema: type: integer format: int64 - name: is_block_trade in: query required: false description: Filter trades by whether they are block trades. Omit to return all trades. schema: type: boolean example: false responses: '200': description: Kalshi trades response with pagination content: application/json: schema: type: object properties: cursor: type: string description: Cursor for the next page. trades: type: array items: type: object additionalProperties: true properties: trade_id: type: string ticker: type: string count_fp: type: string yes_price_dollars: type: string no_price_dollars: type: string taker_side: type: string taker_book_side: type: string taker_outcome_side: type: string created_time: type: string is_block_trade: type: boolean required: - trades '400': description: Bad Request - Invalid parameters content: application/json: schema: type: object properties: error: type: string example: Invalid parameters message: type: string example: Invalid time range or parameters tags: - Prediction Markets x-x402: path: /apis/v2/kalshi/trades source: https://github.com/AIsa-team/aisa-proxy /financial/macro/interest-rates: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med summary: Interest Rates (Historical) description: 'One central bank''s policy rate over time, as an `interest_rates` array of `bank`, `name`, `date` and `rate`. `bank` is required and bound by `start_date` and `end_date`. Trap worth knowing: the code is case-sensitive and must be uppercase — FED works, fed returns HTTP 404 with "No data found", which reads like an empty result rather than a bad argument. Valid codes are FED, ECB, BOJ, BOE, BOC, RBA, PBOC, SNB, RBI and BOK; `get_financial_macro_interest_rates_snapshot` with no arguments lists them all.' operationId: get_financial_macro_interest_rates parameters: - name: bank in: query description: 'The bank whose interest rates to return. Use the /macro/interest-rates/banks endpoint to get a list of available banks. Case-sensitive: must be uppercase. A lowercase code returns HTTP 404 "No data found", which reads like an empty result rather than a bad argument.' required: true schema: type: string enum: - FED - ECB - BOJ - BOE - BOC - RBA - PBOC - SNB - RBI - BOK - name: start_date in: query description: The start date of the interest rates to return in YYYY-MM-DD format. required: false schema: type: string - name: end_date in: query description: The end date of the interest rates to return in YYYY-MM-DD format. required: false schema: type: string responses: '200': description: Interest rates response content: application/json: schema: $ref: '#/components/schemas/InterestRatesResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' tags: - Financial Data x-x402: path: /apis/v2/financial/macro/interest-rates source: https://github.com/AIsa-team/aisa-proxy /financial/macro/interest-rates/snapshot: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med summary: Interest Rates (Real-Time) description: 'Current policy rates for the ten central banks tracked here, as an `interest_rates` array of `bank`, `name`, `rate` and `date`. `bank` is optional — omit it to get all ten at once, which is also how you discover the valid codes: FED, ECB, BOJ, BOE, BOC, RBA, PBOC, SNB, RBI and BOK. Use it for the current rate backdrop. For one bank''s rate path over time use `get_financial_macro_interest_rates`.' operationId: get_financial_macro_interest_rates_snapshot parameters: - name: bank in: query description: 'Optional central bank code (e.g., FED, ECB, BOJ). AIsa also accepts this endpoint without `bank` and returns the latest snapshot for all major central banks. Case-sensitive: must be uppercase. A lowercase code returns HTTP 404 "No data found", which reads like an empty result rather than a bad argument.' required: false schema: type: string enum: - FED - ECB - BOJ - BOE - BOC - RBA - PBOC - SNB - RBI - BOK responses: '200': description: Interest rates snapshot response content: application/json: schema: $ref: '#/components/schemas/InterestRatesResponse' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' tags: - Financial Data x-x402: path: /apis/v2/financial/macro/interest-rates/snapshot source: https://github.com/AIsa-team/aisa-proxy /images/generations: post: summary: Generate images (OpenAI-compatible) description: |- Generate images with the OpenAI-compatible images-generations endpoint. **Size constraint (Seedream routes only).** Seedream's upstream requires a minimum of **3,686,400 pixels** per image. Requests below that return `400 InvalidParameter: image size must be at least 3686400 pixels`. Wan and `gpt-image-2` routes accept smaller sizes — `1024x1024` is verified working for `wan2.7-image`. operationId: createImageGeneration requestBody: required: true content: application/json: schema: type: object required: - model - prompt properties: model: type: string enum: - seedream-5-0-260128 - wan2.7-image - wan2.7-image-pro - gpt-image-2 description: Image generation model. `seedream-5-0-260128` ($0.035/request), `wan2.7-image` ($0.030/request), `wan2.7-image-pro` ($0.075/request), or `gpt-image-2` ($0.03/request or $0.05 per 1024×1024 image). prompt: type: string description: Text description of the image to generate. n: type: integer minimum: 1 default: 1 description: Number of images to generate. Each image is billed separately at the per-image rate. size: type: string description: Image dimensions as `WIDTHxHEIGHT`. Seedream routes require `width × height ≥ 3,686,400` (e.g. `1920x1920`, `2048x2048`); Wan and `gpt-image-2` accept smaller sizes such as `1024x1024`. example: 2048x2048 examples: basic: summary: Single 2K image value: model: seedream-5-0-260128 prompt: A cute red panda, ultra-detailed, cinematic lighting n: 1 size: 2048x2048 minimum_size: summary: Exactly at minimum allowed size (1920×1920) value: model: seedream-5-0-260128 prompt: A futuristic cyberpunk city, neon lights, rainy night, 8k n: 1 size: 1920x1920 batch: summary: Four candidates for selection value: model: seedream-5-0-260128 prompt: Oil painting of a rolling hillside at sunset n: 4 size: 2048x2048 responses: '200': description: Images generated successfully. content: application/json: schema: type: object properties: model: type: string example: seedream-5-0-260128 created: type: integer example: 1776495432 data: type: array description: One entry per generated image. items: type: object properties: url: type: string format: uri description: Short-lived URL to the generated image. Download and persist it; the URL expires. size: type: string description: Actual dimensions of the returned image. usage: type: object properties: generated_images: type: integer output_tokens: type: integer total_tokens: type: integer example: model: seedream-5-0-260128 created: 1776495432 data: - url: https://cdn.aisa.one/images/seedream/20260418-abc.png size: 2048x2048 usage: generated_images: 1 output_tokens: 16384 total_tokens: 16384 '400': description: 'Invalid request. Most common: `size` smaller than 3,686,400 pixels → `"image size must be at least 3686400 pixels"`.' '401': description: Missing or invalid AIsa API key. '404': description: The model isn't routed through this endpoint. The gateway returns `model_route_not_supported` with the model's actual supported routes — see the [model catalog](/guides/models). '429': description: Rate limit hit. '500': description: Internal error. '502': description: Upstream provider unreachable. tags: - Image Generation servers: - url: https://api.aisa.one/v1 /financial/financials/search/line-items: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.04 p95: 0.04 max: 0.04 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Financial Data operationId: post_financial_financials_search_line_items summary: Search specific financial metrics description: Pull named financial line items across one or more companies in a single call. Body takes `tickers` and `line_items` (both required, both arrays), plus `period` (annual, quarterly or ttm) and `limit`. Returns `search_results` with one row per ticker and period carrying only the fields you asked for, alongside `report_period`, `period` and `currency`. Use it to build a comparison table without pulling three full statements per company. The item names are the same field names the statement tools return, so look one up there first if unsure. For everything about a single company use `get_financial_financials`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchLineItemsRequest' responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/FinancialsSearchResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financials/search/line-items source: https://github.com/AIsa-team/aisa-proxy /financial/insider-trades: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_insider_trades summary: Get insider trades description: Form 4 insider transactions for one stock. Each row carries the person (`name`, `title`, `is_board_director`), the trade (`transaction_date`, `transaction_code`, `transaction_type`, `transaction_shares`, `transaction_price_per_share`, `transaction_value`), the resulting position (`shares_owned_before_transaction`, `shares_owned_after_transaction`) and the filing (`form_type`, `filing_date`, `security_title`). `ticker` is required. Filter with `name` or `transaction_type`, and bound by filing date with `filing_date`, `filing_date_gte`, `filing_date_lte`, `filing_date_gt` or `filing_date_lt`. Use it for who inside the company bought or sold and when. parameters: - name: ticker in: query description: The ticker symbol of the company. required: true schema: type: string - name: limit in: query description: 'The maximum number of transactions to return (default: 10).' required: false schema: type: integer default: 10 - name: name in: query description: Filter by insider name (e.g., 'Jen Hsun Huang'). Use the /insider-trades/names endpoint to get available names for a ticker. required: false schema: type: string - name: transaction_type in: query description: Filter by transaction type (e.g., 'Open market sale', 'Gift'). Use the /insider-trades/transaction-types endpoint to get available types. required: false schema: type: string - name: filing_date in: query description: Filter by exact filing date in YYYY-MM-DD format. required: false schema: type: string format: date - name: filing_date_gte in: query description: Filter by filing date greater than or equal to this date (YYYY-MM-DD). required: false schema: type: string format: date - name: filing_date_lte in: query description: Filter by filing date less than or equal to this date (YYYY-MM-DD). required: false schema: type: string format: date - name: filing_date_gt in: query description: Filter by filing date greater than this date (YYYY-MM-DD). required: false schema: type: string format: date - name: filing_date_lt in: query description: Filter by filing date less than this date (YYYY-MM-DD). required: false schema: type: string format: date responses: '200': description: Insider trades response content: application/json: schema: $ref: '#/components/schemas/InsiderTradesResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/insider-trades source: https://github.com/AIsa-team/aisa-proxy /financial/company/facts: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med tags: - Financial Data operationId: get_financial_company_facts summary: Get company facts description: 'Identity and classification for one company: `name`, `ticker`, `cik`, `sector`, `industry`, `exchange`, `location`, `is_active`, `sec_filings_url`, and the SIC trio `sic_code` / `sic_industry` / `sic_sector`. Accepts either `ticker` or `cik`. No prices and no fundamentals at all. Use it to resolve a ticker into the `cik` that the filings tools accept, or to confirm what sector a company is actually classified under before comparing it to peers.' parameters: - name: ticker in: query description: The ticker symbol. required: false schema: type: string - name: cik in: query description: The CIK of the company. required: false schema: type: string responses: '200': description: Company facts response content: application/json: schema: $ref: '#/components/schemas/CompanyFactsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/company/facts source: https://github.com/AIsa-team/aisa-proxy /financial/filings: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med tags: - Financial Data operationId: get_financial_filings summary: Get SEC filings description: The SEC filing index for one company — a list of filings, not their contents. Each entry carries `cik`, `accession_number`, `filing_type`, `report_date`, `filing_date`, `ticker` and `url`. Accepts `ticker` or `cik`, narrows by `filing_type`, and caps with `limit`. Use it to find which filing you want and to get its `accession_number`. To read the text inside one, use `get_financial_filings_items`. parameters: - name: cik in: query description: The Central Index Key (CIK) of the company. required: false schema: type: string - name: ticker in: query description: The ticker symbol. required: false schema: type: string - name: filing_type in: query description: Filter by one or more filing types. Repeat the query parameter to pass multiple values (e.g. filing_type=10-Q&filing_type=10-K). required: false schema: type: array items: type: string enum: - 10-K - 10-Q - 8-K - 20-F - 6-K style: form explode: true - name: limit in: query description: 'The maximum number of filings to return (default: 10).' required: false schema: type: integer minimum: 1 default: 10 responses: '200': description: SEC filings response content: application/json: schema: $ref: '#/components/schemas/FilingsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/filings source: https://github.com/AIsa-team/aisa-proxy /financial/filings/items: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med tags: - Financial Data operationId: get_financial_filings_items summary: Get SEC filing items description: 'The full text of the numbered items inside one SEC filing. `ticker`, `filing_type` (10-K, 10-Q or 8-K) and `year` are all required; narrow further with `quarter`, `item`, `accession_number` or `include_exhibits`. Returns `items` — each with `number`, `title` and the complete `text` — plus `filing_url` and `accession_number`. Mind the size: a 10-K comes back as roughly 19 items of full prose, so request a specific `item` rather than pulling everything unless you truly need the whole document. To find which filing to open in the first place, use `get_financial_filings`.' parameters: - name: ticker in: query description: The ticker symbol. required: true schema: type: string - name: filing_type in: query description: The type of filing. required: true schema: type: string enum: - 10-K - 10-Q - 8-K - name: year in: query description: The year of the filing. required: true schema: type: integer - name: quarter in: query description: The quarter of the filing if 10-Q. required: false schema: type: integer - name: item in: query description: The item to get. required: false schema: type: string enum: - Item-1 - Item-1A - Item-1B - Item-2 - Item-3 - Item-4 - Item-5 - Item-6 - Item-7 - Item-7A - Item-8 - Item-9 - Item-9A - Item-9B - Item-10 - Item-11 - Item-12 - Item-13 - Item-14 - Item-15 - Item-16 - Item-1.01 - Item-1.02 - Item-1.03 - Item-1.04 - Item-2.01 - Item-2.02 - Item-2.03 - Item-2.04 - Item-2.05 - Item-2.06 - Item-3.01 - Item-3.02 - Item-3.03 - Item-4.01 - Item-4.02 - Item-5.01 - Item-5.02 - Item-5.03 - Item-5.04 - Item-5.05 - Item-5.06 - Item-5.07 - Item-5.08 - Item-6.01 - Item-6.02 - Item-6.03 - Item-6.04 - Item-6.05 - Item-7.01 - Item-8.01 - Item-9.01 - name: accession_number in: query description: The accession number of the filing if 8-K. required: false schema: type: string - name: include_exhibits in: query description: Whether to include the raw text from linked exhibits. Only applicable for 8-K filings. When true, exhibit objects will include the 'text' field containing the full exhibit content. required: false schema: type: boolean default: false responses: '200': description: SEC filing items response content: application/json: schema: $ref: '#/components/schemas/FilingItemsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/filings/items source: https://github.com/AIsa-team/aisa-proxy /financial/financials/income-statements: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_financials_income_statements summary: Get income statements description: 'Income statements for one company, about 32 fields per period: `revenue`, `cost_of_revenue`, `gross_profit`, `operating_expense`, `selling_general_and_administrative_expenses`, `research_and_development`, `operating_income`, `interest_expense`, `ebit`, `income_tax_expense`, `net_income`, `net_income_common_stock` and the per-share lines, each stamped with `report_period`, `fiscal_period`, `currency`, `filing_date` and `filing_url`. `period` is required (annual, quarterly or ttm). Use it for the revenue-to-earnings walk. For all three statements at once use `get_financial_financials`.' parameters: - name: ticker in: query description: The ticker symbol. Required if cik is not provided. required: false schema: type: string - name: period in: query description: The time period of the income statements. required: true schema: type: string enum: - annual - quarterly - ttm - name: limit in: query description: The maximum number of income statements to return. schema: type: integer format: int32 - name: cik in: query description: The Central Index Key (CIK) of the company. required: false schema: type: string - $ref: '#/components/parameters/ReportPeriod' - $ref: '#/components/parameters/ReportPeriodGte' - $ref: '#/components/parameters/ReportPeriodLte' - $ref: '#/components/parameters/ReportPeriodGt' - $ref: '#/components/parameters/ReportPeriodLt' responses: '200': description: Income statements response content: application/json: schema: $ref: '#/components/schemas/IncomeStatementResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financials/income-statements source: https://github.com/AIsa-team/aisa-proxy /financial/financials/balance-sheets: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_financials_balance_sheets summary: Get balance sheets description: 'Balance sheets for one company, about 36 fields per period: `total_assets`, `current_assets`, `cash_and_equivalents`, `inventory`, `trade_and_non_trade_receivables`, `property_plant_and_equipment`, `goodwill_and_intangible_assets`, `total_liabilities`, `current_liabilities`, `current_debt`, `trade_and_non_trade_payables`, `deferred_revenue` and the equity lines, stamped with `report_period`, `fiscal_period`, `currency` and `filing_url`. `period` is required. Use it for capital structure and liquidity. For the ratios already computed off these numbers use `get_financial_financial_metrics`.' parameters: - name: ticker in: query description: The ticker symbol. Required if cik is not provided. required: false schema: type: string - name: period in: query description: The time period of the balance sheets. required: true schema: type: string enum: - annual - quarterly - ttm - name: limit in: query description: The maximum number of balance sheets to return schema: type: integer format: int32 - name: cik in: query description: The Central Index Key (CIK) of the company. required: false schema: type: string - $ref: '#/components/parameters/ReportPeriod' - $ref: '#/components/parameters/ReportPeriodGte' - $ref: '#/components/parameters/ReportPeriodLte' - $ref: '#/components/parameters/ReportPeriodGt' - $ref: '#/components/parameters/ReportPeriodLt' responses: '200': description: Balance sheets response content: application/json: schema: $ref: '#/components/schemas/BalanceSheetResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financials/balance-sheets source: https://github.com/AIsa-team/aisa-proxy /financial/financials/cash-flow-statements: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_financials_cash_flow_statements summary: Get cash flow statements description: 'Cash flow statements for one company, about 27 fields per period: `net_cash_flow_from_operations`, `net_cash_flow_from_investing`, `net_cash_flow_from_financing`, `capital_expenditure`, `depreciation_and_amortization`, `share_based_compensation`, `issuance_or_repayment_of_debt_securities`, `issuance_or_purchase_of_equity_shares` and `dividends_and_other_cash_distributions`, stamped with `report_period`, `fiscal_period` and `currency`. `period` is required. Use it to see cash generation rather than accounting earnings. Free cash flow yield and similar derived figures live in `get_financial_financial_metrics`.' parameters: - name: ticker in: query description: The ticker symbol. Required if cik is not provided. required: false schema: type: string - name: period in: query description: The time period of the cash flow statements. required: true schema: type: string enum: - annual - quarterly - ttm - name: limit in: query description: The maximum number of cash flow statements to return. schema: type: integer format: int32 - name: cik in: query description: The Central Index Key (CIK) of the company. required: false schema: type: string - $ref: '#/components/parameters/ReportPeriod' - $ref: '#/components/parameters/ReportPeriodGte' - $ref: '#/components/parameters/ReportPeriodLte' - $ref: '#/components/parameters/ReportPeriodGt' - $ref: '#/components/parameters/ReportPeriodLt' responses: '200': description: Cash flow statements response content: application/json: schema: $ref: '#/components/schemas/CashFlowStatementResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financials/cash-flow-statements source: https://github.com/AIsa-team/aisa-proxy /financial/prices/snapshot: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med tags: - Financial Data operationId: get_financial_prices_snapshot summary: Price Snapshot (Real-Time) description: 'The current price of one stock in a single call: `price`, `day_change`, `day_change_percent`, and `time` (plus `time_milliseconds`). `ticker` is required. Use it whenever the question is "what is it trading at now" — this is the cheapest and fastest way to get one number. For a series of bars over a date range use `get_financial_prices`; for valuation multiples rather than the raw price use `get_financial_financial_metrics_snapshot`.' parameters: - name: ticker in: query description: The stock ticker symbol (e.g. AAPL, MSFT). required: true schema: type: string responses: '200': description: Price snapshot response content: application/json: schema: $ref: '#/components/schemas/PriceSnapshotResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/prices/snapshot source: https://github.com/AIsa-team/aisa-proxy /financial/financials: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.12 cost_tier: med tags: - Financial Data operationId: get_financial_financials summary: Get all financial statements description: All three statements for one company in a single call. Returns a `financials` object holding `income_statements`, `balance_sheets` and `cash_flow_statements`, each the same shape the dedicated tools return. `period` is required (annual, quarterly or ttm); identify the company by `ticker` or `cik` and cap with `limit`. Use it when you need the full picture and would otherwise make three calls. When you only need one statement, `get_financial_financials_income_statements`, `get_financial_financials_balance_sheets` or `get_financial_financials_cash_flow_statements` returns far less data; when you need a handful of named fields across several companies, `post_financial_financials_search_line_items` is narrower still. parameters: - name: ticker in: query description: The ticker symbol. Required if cik is not provided. required: false schema: type: string - name: period in: query description: The time period of the financial statements. required: true schema: type: string enum: - annual - quarterly - ttm - name: limit in: query description: The maximum number of financial statements to return. schema: type: integer format: int32 - name: cik in: query description: The Central Index Key (CIK) of the company. required: false schema: type: string - $ref: '#/components/parameters/ReportPeriod' - $ref: '#/components/parameters/ReportPeriodGte' - $ref: '#/components/parameters/ReportPeriodLte' - $ref: '#/components/parameters/ReportPeriodGt' - $ref: '#/components/parameters/ReportPeriodLt' responses: '200': description: Financial statements response content: application/json: schema: $ref: '#/components/schemas/FinancialsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financials source: https://github.com/AIsa-team/aisa-proxy /financial/news: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_news summary: Get news articles description: 'Recent news headlines for one stock: `title`, `source`, `date`, `url` and the echoed `ticker`, in a `news` array. `ticker` and `limit` are the only parameters — there is no full-text search and no date filter, so narrow by raising or lowering `limit` rather than by query. Use it for recent coverage of a company you have already identified. Headlines only: the article body is not returned, follow `url` for that. For the company''s own filings rather than press coverage use `get_financial_filings`.' parameters: - name: ticker in: query description: The ticker symbol of the company. Omit for broad market news. required: false schema: type: string - name: limit in: query description: 'The maximum number of news articles to return (default: 5, max: 10).' required: false schema: type: integer default: 5 maximum: 10 responses: '200': description: News articles response content: application/json: schema: $ref: '#/components/schemas/NewsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/news source: https://github.com/AIsa-team/aisa-proxy /financial/prices: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.024 cost_tier: med tags: - Financial Data operationId: get_financial_prices summary: Get historical stock price data description: Historical OHLCV bars for one stock. All four of `ticker`, `interval`, `start_date` and `end_date` are required — there is no trailing-window shortcut. `interval` is one of day, week, month or year. Each bar carries `open`, `close`, `high`, `low`, `volume` and `time`, wrapped in a `prices` array alongside the echoed `ticker`. Use it to chart or to measure a move across a known window. For just the latest price use `get_financial_prices_snapshot`. parameters: - name: ticker in: query description: The stock ticker symbol (e.g. AAPL, MSFT). required: true schema: type: string - name: interval in: query description: The time interval for the price data. required: true schema: type: string enum: - day - week - month - year - name: start_date in: query description: 'The start date for the price data (format: YYYY-MM-DD).' required: true schema: type: string format: date - name: end_date in: query description: 'The end date for the price data (format: YYYY-MM-DD).' required: true schema: type: string format: date responses: '200': description: Price data response content: application/json: schema: $ref: '#/components/schemas/PricesResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/prices source: https://github.com/AIsa-team/aisa-proxy /financial/financial-metrics: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_financial_metrics summary: Get financial metrics description: 'Computed ratios for one company over time, about 49 per period: `market_cap`, `enterprise_value`, `price_to_earnings_ratio`, `price_to_book_ratio`, `price_to_sales_ratio`, `enterprise_value_to_ebitda_ratio`, `free_cash_flow_yield`, `peg_ratio`, `gross_margin`, `operating_margin`, `net_margin`, `return_on_equity`, `return_on_assets`, `return_on_invested_capital`, the turnover and liquidity ratios, each stamped with `report_period` and `fiscal_period`. `period` is required; identify by `ticker` or `cik`. Use it to trend a ratio across periods. For the current values only, `get_financial_financial_metrics_snapshot` is one row and much smaller.' parameters: - name: ticker in: query description: The ticker symbol of the company. Required if cik is not provided. required: false schema: type: string - name: cik in: query description: The Central Index Key (CIK) of the company. Can be used instead of ticker. required: false schema: type: string - name: period in: query description: The time period for the financial data. required: true schema: type: string enum: - annual - quarterly - ttm - name: limit in: query description: The maximum number of results to return. required: false schema: type: integer - $ref: '#/components/parameters/ReportPeriod' - $ref: '#/components/parameters/ReportPeriodGte' - $ref: '#/components/parameters/ReportPeriodLte' - $ref: '#/components/parameters/ReportPeriodGt' - $ref: '#/components/parameters/ReportPeriodLt' responses: '200': description: The historical financial metrics and ratios for a ticker content: application/json: schema: $ref: '#/components/schemas/FinancialMetricsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financial-metrics source: https://github.com/AIsa-team/aisa-proxy /financial/financial-metrics/snapshot: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.048 cost_tier: med tags: - Financial Data operationId: get_financial_financial_metrics_snapshot summary: Financial Metrics Snapshot (Real-Time) description: 'The same ratio set as `get_financial_financial_metrics` but current-only: one `snapshot` object of about 41 fields — `market_cap`, `enterprise_value`, `price_to_earnings_ratio`, `price_to_book_ratio`, `price_to_sales_ratio`, `enterprise_value_to_ebitda_ratio`, `free_cash_flow_yield`, `peg_ratio`, the margin and return ratios, and the liquidity ratios. Takes only `ticker` or `cik`, with no period argument. Use it to size up a company right now. For history, or to see whether a multiple is unusual for this company, use `get_financial_financial_metrics`.' parameters: - name: ticker in: query description: The ticker symbol of the company. required: false schema: type: string - name: cik in: query description: The Central Index Key (CIK) of the company. Can be used instead of ticker. required: false schema: type: string responses: '200': description: Financial metrics snapshot response content: application/json: schema: $ref: '#/components/schemas/FinancialMetricSnapshotResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/financial-metrics/snapshot source: https://github.com/AIsa-team/aisa-proxy /financial/financials/search/screener: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.04 max: 0.04 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Search financial statements description: Find tickers that match numeric conditions. Body takes `filters` — each a `field`, an `operator` and a `value` — plus `limit`. Returns `results` with `ticker`, `currency`, `sector`, `industry` and whichever filtered field was matched. This is the only tool here that works without knowing a ticker in advance; everything else takes one as input. Filterable fields are the metric names `get_financial_financial_metrics` returns. Use it to build a candidate list, then pull detail on each name with the statement or metric tools. operationId: post_financial_financials_search_screener tags: - Financial Data requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchFiltersRequest' responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/FinancialsScreenerResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' security: - bearerAuth: [] x-x402: path: /apis/v2/financial/financials/search/screener source: https://github.com/AIsa-team/aisa-proxy /financial/earnings: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.04 max: 0.04 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Financial Data operationId: get_financial_earnings summary: Get earnings snapshot description: 'Reported earnings for one stock, actuals against estimates. Each entry carries `report_period`, `fiscal_period`, `filing_date`, `filing_url` and `accession_number`, a `quarterly` block with `revenue`, `estimated_revenue`, `revenue_surprise` and `revenue_surprise_pct`, the same trio for `earnings_per_share`, plus year-over-year change fields. It also returns `signals`: upstream-computed flags such as EPS_BEAT with a `headline` and the `actual` / `estimate` / `surprise_pct` behind it. `ticker` is required and it is the only parameter. Use it for what a company actually reported. For forward-looking consensus that has not happened yet use `get_financial_analyst_estimates`.' parameters: - name: ticker in: query description: The ticker symbol. required: true schema: type: string responses: '200': description: Earnings response content: application/json: schema: $ref: '#/components/schemas/EarningsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' x-x402: path: /apis/v2/financial/earnings source: https://github.com/AIsa-team/aisa-proxy /oxylabs/ai-search: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.001 cost_tier: low tags: - Web & News Search summary: Query an AI answer engine for GEO/AEO visibility. description: Synchronous passthrough to the upstream Oxylabs Realtime endpoint (POST /v1/queries). Pick an AI answer engine with `source` and send the parameters that source expects; the request body is passed through unchanged. The response returns the AI-generated answer text and the cited source URLs, letting you track how a brand or product is surfaced and cited across AI answers. Billed at a flat $0.001 per successful result; 400/429/5xx/6xx and upstream 4xx responses are not billed. AI sources (chatgpt, gemini, perplexity) take ~40–60s and Google-type sources ~4–8s, so use a client timeout of at least 90s. requestBody: required: true content: application/json: schema: type: object description: Passthrough body. `source` selects the AI answer engine; the remaining fields are the parameters that source expects (see per-source notes on each property). Additional upstream parameters are passed through as-is. additionalProperties: true properties: source: type: string enum: - chatgpt - gemini - perplexity - google_search - google_ai_mode description: The AI answer engine to query. `google_search` returns Google AI Overviews. Each source expects a specific subset of the parameters below. example: google_search prompt: type: string description: The natural-language prompt. Used by `chatgpt` (max 4000 chars), `gemini` (max 8000 chars), and `perplexity`. Use `query` instead for the Google-type sources. example: best noise cancelling headphones 2026 query: type: string description: The search query. Used by `google_search` and `google_ai_mode`. Use `prompt` instead for chatgpt/gemini/perplexity. example: best noise cancelling headphones 2026 search: type: boolean description: For `chatgpt`, set to true to have ChatGPT browse the web before answering. example: true render: type: string enum: - html description: For `google_search` and `google_ai_mode`, set to "html" to render the page before parsing. example: html parse: type: boolean description: Return structured, parsed results instead of raw output. Recommended for every source. example: true geo_location: type: string description: Country-level geo-location for the query, e.g. "United States". example: United States required: - source examples: google_search: summary: Google AI Overviews (google_search) value: source: google_search query: best noise cancelling headphones 2026 parse: true render: html geo_location: United States chatgpt: summary: ChatGPT answer with web browsing value: source: chatgpt prompt: best noise cancelling headphones 2026 search: true parse: true geo_location: United States responses: '200': description: Query completed successfully. `results[]` holds one result per query. The parsed shape inside `content` varies by source (see property descriptions); the example below shows the `google_search` (Google AI Overviews) shape. content: application/json: schema: type: object properties: results: type: array description: One entry per query. A Realtime single query returns exactly one result, which is the billed unit. items: type: object properties: content: type: object description: |- Parsed answer payload. The structure varies by source: - `google_search` → `content.results.ai_overviews[]` with `answer_text` and `references[]{source, url}` (shown below). - `chatgpt` / `gemini` → `response_text` plus `citations[]`. - `perplexity` → `top_sources[]` / `sources_results[]`. - `google_ai_mode` → `content.citations[]{text, urls[]}`. properties: results: type: object description: Google-type parsed results container. properties: ai_overviews: type: array description: Google AI Overviews returned for the query. items: type: object properties: answer_text: type: array description: The AI-generated answer, split into fragments that may carry inline references. items: type: object properties: fragments: type: array items: type: object properties: references: type: array items: {} references: type: array description: Cited sources for this overview. items: type: object properties: source: type: string url: type: string operationId: post_oxylabs_ai_search x-x402: path: /apis/v2/oxylabs/ai-search source: https://github.com/AIsa-team/aisa-proxy /perplexity/sonar: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.01 p50: 0.012 p95: 0.01282 max: 0.25566 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - AI Models operationId: post_perplexity_sonar summary: Sonar — lightweight search + answer description: 'Ask a question and get a written answer with web citations, rather than a list of links to read yourself. Body is OpenAI chat-completions shaped: `model` (required, `sonar`) and `messages`. Returns `choices[0].message.content` as prose, plus `citations` (an array of URL strings) and `search_results[]` with `title`, `url`, `snippet`, `date` and `source`, and a `usage` block. Measured at about 3 seconds. Billed at a flat $0.012 per request. This is the cheapest and fastest of the four Perplexity endpoints — use it for a single factual question. Step up to `post_perplexity_sonar_pro` for multi-part questions, or `post_perplexity_sonar_reasoning_pro` when the answer requires working through steps. If you need results you can iterate over rather than prose, use `post_tavily_search`; `post_exa_answer` answers the same shape of question with semantic retrieval, at $0.08.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' example: model: sonar messages: - role: user content: What are the latest developments in quantum computing? responses: '200': description: Successful response with AI answer and citations content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' x-x402: path: /apis/v2/perplexity/sonar source: https://github.com/AIsa-team/aisa-proxy /perplexity/sonar-pro: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.0682 max: 0.22546 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - AI Models operationId: post_perplexity_sonar_pro summary: Sonar Pro — advanced search for complex queries description: Ask a question that needs more than one search pass and get a written answer with citations. Same request and response shape as `post_perplexity_sonar` — `model` (required, `sonar-pro`) and `messages` in, `choices[0].message.content`, `citations`, `search_results[]` and `usage` out. Measured at about 10 seconds, roughly three times `sonar`, for the same flat $0.012 per request. Use it for questions with several parts or follow-ups. For a single lookup `sonar` answers in a third of the time at the same price; when the difficulty is reasoning rather than retrieval, `post_perplexity_sonar_reasoning_pro` shows its working. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' example: model: sonar-pro messages: - role: user content: Compare the economic policies of the US and EU regarding AI regulation in 2025-2026 responses: '200': description: Successful response with AI answer and citations content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' x-x402: path: /apis/v2/perplexity/sonar-pro source: https://github.com/AIsa-team/aisa-proxy /perplexity/sonar-reasoning-pro: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.01228 p95: 0.06066 max: 0.07052 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - AI Models operationId: post_perplexity_sonar_reasoning_pro summary: Sonar Reasoning Pro — chain-of-thought reasoning with search description: Ask a question that has to be worked through, not just looked up, and get a step-by-step answer backed by web search. Same shape as the other Perplexity endpoints — `model` (required, `sonar-reasoning-pro`) and `messages` in; `choices[0].message.content`, `citations`, `search_results[]` and `usage` out. Measured at about 5 seconds, flat $0.012 per request. Use it for comparison, causation and analysis. When the question is simply what is the case, `post_perplexity_sonar` is faster; when you need a long report over many sources rather than an answer, `post_perplexity_sonar_deep_research`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' example: model: sonar-reasoning-pro messages: - role: user content: Analyze whether Tesla stock is overvalued based on current P/E ratio compared to industry averages responses: '200': description: Successful response with AI answer and citations content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' x-x402: path: /apis/v2/perplexity/sonar-reasoning-pro source: https://github.com/AIsa-team/aisa-proxy /perplexity/sonar-deep-research: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.01004 p50: 0.012 p95: 1.72686 max: 1.72686 cost_drivers: - param: response size effect: charge scales with provider response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - AI Models operationId: post_perplexity_sonar_deep_research summary: Sonar Deep Research — exhaustive research & comprehensive reports description: 'Commission a report: this endpoint runs many searches and writes a long, cited document. `model` (required, `sonar-deep-research`) and `messages` in; `choices[0].message.content`, `citations`, `search_results[]` and `usage` out, where `usage` also reports `num_search_queries` and `reasoning_tokens`. ⚠️ Budget for the wait: a two-sentence question measured **192 seconds** and returned 86 KB after 10 upstream searches — roughly 60 times slower and 10 times larger than `post_perplexity_sonar`, at the same flat $0.012 per request. Many clients time out well before it answers, so call it only when a report is genuinely the deliverable, and never in a loop. For anything you would read in one sitting, the other three Perplexity endpoints answer in seconds.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' example: model: sonar-deep-research messages: - role: user content: Write a comprehensive analysis of the global semiconductor supply chain risks in 2026 responses: '200': description: Successful response with AI answer and citations content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' x-x402: path: /apis/v2/perplexity/sonar-deep-research source: https://github.com/AIsa-team/aisa-proxy /pinterest/search: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Pinterest operationId: get_pinterest_search summary: Search description: Searches Pinterest for pins matching a keyword and returns pins plus a cursor to page. Each pin carries id, url, title, description, grid_title, created_at, images in five sizes (170x, 236x, 474x, 736x, orig), link, domain, board (name, url, pin_count) and pinner (username). Measured at about 110 KB for 17 pins; trim=true cuts that to 28 KB and keeps six fields per pin — id, url, description, created_at, images and pinner — dropping title, link, board and domain, so only skip trim when you need those. The board.url on each result feeds get_pinterest_board; for one pin's engagement counts use get_pinterest_pin. parameters: - name: query in: query required: true description: Search query schema: type: string example: Italian Pot Roast - name: cursor in: query required: false description: Cursor schema: type: string example: Y2JVSG81V2sxcmNHRlpWM1J... - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: success: true pins: - id: '643874078015272259' url: https://www.pinterest.com/pin/643874078015272259 description: '#cute #animal #dog #puppy #pfp #icon #dogpfp #silly #cutepuppy #bordercollie #fyp #trend' created_at: Tue, 10 Jun 2025 21:45:32 +0000 pinner: node_id: VXNlcjo2NDM4NzQyMTUzODQxMzkwMTg= full_name: Annika Strøm is_ads_only_profile: false username: annikastrom2 image_medium_url: https://i.pinimg.com/75x75_RS/60/d5/a8/60d5a8405ec70c5c46b677186c626587.jpg is_primary_website_verified: false follower_count: 2 ads_only_profile_site: null id: '643874215384139018' is_verified_merchant: false image_large_url: https://i.pinimg.com/140x140_RS/60/d5/a8/60d5a8405ec70c5c46b677186c626587.jpg verified_identity: {} image_small_url: https://i.pinimg.com/30x30_RS/60/d5/a8/60d5a8405ec70c5c46b677186c626587.jpg images: 170x: width: 236 height: 312 url: https://i.pinimg.com/236x/a7/d6/dc/a7d6dced1ee95c11a150dcf2f1c6e05f.jpg 236x: width: 236 height: 312 url: https://i.pinimg.com/236x/a7/d6/dc/a7d6dced1ee95c11a150dcf2f1c6e05f.jpg 474x: width: 474 height: 626 url: https://i.pinimg.com/474x/a7/d6/dc/a7d6dced1ee95c11a150dcf2f1c6e05f.jpg 736x: width: 736 height: 973 url: https://i.pinimg.com/736x/a7/d6/dc/a7d6dced1ee95c11a150dcf2f1c6e05f.jpg orig: width: 946 height: 1251 url: https://i.pinimg.com/originals/a7/d6/dc/a7d6dced1ee95c11a150dcf2f1c6e05f.jpg cursor: Y2JVSG81V2sxcmNHRlpWM1J5VFVad1ZsWl... schema: $ref: '#/components/schemas/PinterestPinsResponse' x-x402: path: /apis/v2/pinterest/search source: https://github.com/AIsa-team/aisa-proxy /pinterest/pin: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Pinterest operationId: get_pinterest_pin summary: Pin description: 'Fetches one pin by URL, of the form pinterest.com/pin/. The response is a different shape from search results: camelCase fields including entityId, description, category, totalReactionCount, aggregatedPinData, richMetadata, pinner, originPinner and genAiTopics. Measured at 12.5 KB, the smallest full response in this API; trim=true reduces it to 1.6 KB, keeping entityId, description, createdAt, pinner, originPinner, nativeCreator, shareCount, repinCount and totalReactionCount while dropping richMetadata and category. To find pins by keyword use get_pinterest_search; to page through the board a pin sits on use get_pinterest_board. Only standard numeric pin URLs resolve: of 12 search results fed straight back, the 3 whose URL ended in a shortcode (dwA0UYrl style) all answered 404 and one numeric id did too, so check for a numeric trailing id before calling and expect occasional 404s on deleted pins.' parameters: - name: url in: query required: true description: Pinterest pin URL schema: type: string example: https://www.pinterest.com/pin/1124351863225567517/ - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: success: true entityId: '36662184461578355' seoAltText: a small brown dog sitting in the back seat of a car with its head hanging out originPinner: entityId: '1144125617743372495' id: VXNlcjoxMTQ0MTI1NjE3NzQzMzcyNDk1 username: Chloe_hi15 imageMediumUrl: https://i.pinimg.com/75x75_RS/90/99/6f/90996f6eac9c9fd4836fba948699fd28.jpg blockedByMe: false explicitlyFollowedByMe: false followerCount: 55 fullName: Chloe Marie Monroe imageLargeUrl: https://i.pinimg.com/140x140_RS/90/99/6f/90996f6eac9c9fd4836fba948699fd28.jpg imageSmallUrl: https://i.pinimg.com/30x30_RS/90/99/6f/90996f6eac9c9fd4836fba948699fd28.jpg isVerifiedMerchant: false verifiedIdentity: verified: null pinner: blockedByMe: false id: VXNlcjozNjY2MjMyMTg3NDk5NjcxNQ== entityId: '36662321874996715' __typename: User fullName: Crystal Catlett imageSmallUrl: https://i.pinimg.com/30x30_RS/51/76/82/5176824c31aaeec633f0f09bf1ca12e4.jpg imageLargeUrl: https://i.pinimg.com/140x140_RS/51/76/82/5176824c31aaeec633f0f09bf1ca12e4.jpg explicitlyFollowedByMe: false username: cc1025 imageMediumUrl: https://i.pinimg.com/75x75_RS/51/76/82/5176824c31aaeec633f0f09bf1ca12e4.jpg firstName: Crystal followerCount: 347 isVerifiedMerchant: false verifiedIdentity: verified: null imageSpec_orig: url: https://i.pinimg.com/originals/71/5c/5d/715c5d48feb038e16f48a28e6f8ca1f3.jpg description: ' ' shareCount: 0 nativeCreator: null createdAt: Mon, 09 Jun 2025 04:04:22 +0000 repinCount: 88 totalReactionCount: 88 schema: $ref: '#/components/schemas/PinterestPinResponse' x-x402: path: /apis/v2/pinterest/pin source: https://github.com/AIsa-team/aisa-proxy /pinterest/board: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Pinterest operationId: get_pinterest_board summary: Board description: 'Returns one page of pins from a board URL, with a cursor to page. Board pins carry a third field subset, different from both search results and pin detail: node_id, link, domain, rich_summary, seo_url, board and auto_alt_text among them. Measured at 104 KB for 16 pins; trim=true cuts it to 28 KB, keeping per pin id, title, description, link, domain, board, pinner, alt_text, rich_summary and reaction_counts. Board URLs come from board.url on search results — relative, like /agkelsey/the-apartment/, so prefix https://www.pinterest.com — or from get_pinterest_user_boards. For a user''s board list rather than one board''s pins, use get_pinterest_user_boards.' parameters: - name: url in: query required: true description: The URL of the board to get schema: type: string example: https://www.pinterest.com/lizmrodgers/moms-night/ - name: cursor in: query required: false description: The cursor to get the next page of results schema: type: string example: Y2JURlEwTWsxNlp6Vk9SR2MwV.... - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: success: true pins: - id: '549579960798399243' link: https://gekbuzz.com/crispy-air-fryer-pizza-rolls-recipe/ title: Crispy Air Fryer Pizza Rolls Recipe - board: node_id: Qm9hcmQ6NTQ5NTgwMDI5NDY3NTc3NDM2 followed_by_me: false owner: node_id: VXNlcjo1NDk1ODAwOTgxODYwMzM3MzU= image_small_url: https://s.pinimg.com/images/user/default_30.png is_primary_website_verified: true is_verified_merchant: false full_name: Gekbuzz username: sharat24k image_medium_url: https://s.pinimg.com/images/user/default_75.png id: '549580098186033735' verified_identity: {} privacy: public is_collaborative: false url: /sharat24k/pizza-recipes/ layout: default type: board name: Pizza Recipes id: '549580029467577436' collaborated_by_me: false unified_user_note: Craving a quick snack that combines cheesy goodness and crispy texture? These air fryer pizza rolls are the answer! Perfect for movie nights, parties, or just a casual treat, they pack all the flavor of your favorite pizza into a bite-sized delight. Imagine biting into a perfectly golden roll where melty cheese and zesty sauce meld together. The air fryer gives these pizza rolls a satisfying crunch without the extra oil, making them a healthier option that doesn’t skimp on taste. alt_text: Crispy air fryer pizza rolls served with marinara sauce for dipping on a plate. rich_summary: actions: [] products: [] apple_touch_icon_link: null type_name: article type: richpingriddata id: 5aa12f54bef882f6f3cdd77234027e25 favicon_link: https://s.pinimg.com/images/default_rich_pin_favicon.png url: https://gekbuzz.com/crispy-air-fryer-pizza-rolls-recipe/ display_name: Crispy Air Fryer Pizza Rolls Recipe - favicon_images: orig: https://s.pinimg.com/images/default_rich_pin_favicon.png display_description: Craving a quick snack that combines cheesy goodness and crispy texture? These air fryer pizza rolls are the answer! Perfect for movie nights, parties, or just a casual treat, they pack all the flavor of your favorite pizza into a bite-sized delight. Imagine biting into a perfectly golden roll where melty cheese and zesty sauce […] apple_touch_icon_images: null site_name: gekbuzz.com reaction_counts: {} pinner: node_id: VXNlcjo1NDk1ODAwOTgxODYwMzM3MzU= image_small_url: https://s.pinimg.com/images/user/default_30.png is_primary_website_verified: true is_verified_merchant: false full_name: Gekbuzz username: sharat24k image_medium_url: https://s.pinimg.com/images/user/default_75.png id: '549580098186033735' verified_identity: {} description: Craving a quick snack that combines cheesy goodness and crispy texture? These air fryer pizza rolls are the answer! Perfect for movie nights, parties, or just a casual treat, they pack all the flavor of your favorite pizza into a bite-sized delight. Imagine biting into a perfectly golden roll where melty cheese and zesty sauce meld together. The air fryer gives these pizza rolls a satisfying crunch without the extra oil, making them a healthier option that doesn’t skimp on taste. domain: gekbuzz.com cursor: Y2JURlEwTVU1RWF6Rk9lbXMxV.... schema: $ref: '#/components/schemas/PinterestPinsResponse' x-x402: path: /apis/v2/pinterest/board source: https://github.com/AIsa-team/aisa-proxy /pinterest/user/boards: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Pinterest operationId: get_pinterest_user_boards summary: User Boards description: Lists a user's public boards by username, with a cursor to page. Each board carries id, name, url, description, pin_count, follower_count, section_count, collaborator_count, privacy, owner, created_at, cover_pin and cover_images. Measured at 59 KB for 10 boards; trim=true collapses it to 3.3 KB — the largest trim ratio in this API — keeping id, name, url, description, pin_count, follower_count, created_at and image_cover_hd_url. The handle is the bare username as it appears in a profile URL (agkelsey, not a full URL). Feed each board's url to get_pinterest_board to read its pins; to search across all of Pinterest use get_pinterest_search. parameters: - name: handle in: query required: true description: The username of the user to get boards for. (e.g. broadstbullycom from https://www.pinterest.com/broadstbullycom/) schema: type: string example: broadstbullycom - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: success: true boards: - id: '549580029467577434' url: https://www.pinterest.com/sharat24k/turkey-recipes/ description: '' follower_count: 292 pin_count: 545 name: Turkey Recipes image_cover_hd_url: https://i.pinimg.com/474x/45/00/df/4500dfc5bc8bbc15137ff9d9abf04cc1.jpg created_at: Mon, 17 Feb 2025 02:19:26 +0000 cursor: LT41NDk1ODAwMjk0Njc1Njc1O.... schema: $ref: '#/components/schemas/PinterestBoardsResponse' x-x402: path: /apis/v2/pinterest/user/boards source: https://github.com/AIsa-team/aisa-proxy /scholar/search/mixed: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.0024 cost_tier: low summary: Smart search combining web and academic results description: 'Search the web and academic sources together, for questions that straddle both. ⚠️ Parameters go in the **query string**: `query` (required), `max_num_results`, `as_ylo`/`as_yhi`. Returns a search `id` and `results[]`; **the entry shape varies by source** — every result has `title`, `link` and `snippet`, and academic ones additionally carry `authors` and `number_of_citations`, so treat those two as optional rather than assuming they are there. Measured at about 3 seconds. Use it when you do not know in advance which kind of source will answer. When you do, `post_scholar_search_web` or `post_scholar_search_scholar` is more predictable. Keep the `id` for `post_scholar_search_explain`.' operationId: post_scholar_search_mixed tags: - Scholar Search security: - BearerAuth: [] parameters: - name: query in: query required: true description: Search query for scholarly materials schema: type: string example: machine learning - name: max_num_results in: query description: Maximum number of search results to return, up to 100 schema: type: integer minimum: 1 maximum: 100 default: 10 - name: as_ylo in: query description: Year of publication lower bound schema: type: integer nullable: true minimum: 1900 maximum: 2030 - name: as_yhi in: query description: Year of publication upper bound schema: type: integer nullable: true minimum: 1900 maximum: 2030 responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/SmartSearchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' x-x402: path: /apis/v2/scholar/search/mixed source: https://github.com/AIsa-team/aisa-proxy /scholar/search/web: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.0024 cost_tier: low summary: Search the web description: 'Search the open web and get back a lean result list. ⚠️ Despite being a POST, parameters go in the **query string** — `query` (required), `max_num_results` (default 10, max 100), and `as_ylo`/`as_yhi` for a year range. A JSON body is not accepted. Returns a search `id` and `results[]` carrying only `title`, `link` and `snippet`. Measured at about 4 seconds for a roughly 600-byte response. Its virtue is how little it returns, which suits an agent that only needs to know what exists. It gives you no page text — if you need the content, `post_tavily_search` returns it in the same call. Keep the `id`: it is what `post_scholar_search_explain` needs.' operationId: post_scholar_search_web tags: - Scholar Search security: - BearerAuth: [] parameters: - name: query in: query required: true description: Search query for scholarly materials schema: type: string example: machine learning - name: max_num_results in: query description: Maximum number of search results to return, up to 100 schema: type: integer minimum: 1 maximum: 100 default: 10 - name: as_ylo in: query description: Year of publication lower bound schema: type: integer nullable: true minimum: 1900 maximum: 2030 - name: as_yhi in: query description: Year of publication upper bound schema: type: integer nullable: true minimum: 1900 maximum: 2030 responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/WebSearchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' x-x402: path: /apis/v2/scholar/search/web source: https://github.com/AIsa-team/aisa-proxy /scholar/search/scholar: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.0024 cost_tier: low summary: Search academic papers description: 'Search academic literature. ⚠️ Parameters go in the **query string**, not a body: `query` (required), `max_num_results`, and `as_ylo`/`as_yhi` to bound publication years. Returns a search `id` and `results[]` with `title`, `link`, `snippet`, `authors` and `number_of_citations` — that last field is what a general web search cannot give you. Measured at under 2 seconds. Use it when the question calls for peer-reviewed sources or when citation counts matter. For current events and product pages a general engine is better: `post_tavily_search`. To cover both at once, `post_scholar_search_mixed`. Keep the `id` for `post_scholar_search_explain`.' operationId: post_scholar_search_scholar tags: - Scholar Search security: - BearerAuth: [] parameters: - name: query in: query required: true description: Search query for scholarly materials schema: type: string example: machine learning - name: max_num_results in: query description: Maximum number of search results to return, up to 100 schema: type: integer minimum: 1 maximum: 100 default: 10 - name: as_ylo in: query description: Year of publication lower bound schema: type: integer nullable: true minimum: 1900 maximum: 2030 - name: as_yhi in: query description: Year of publication upper bound schema: type: integer nullable: true minimum: 1900 maximum: 2030 responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/ScholarSearchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' x-x402: path: /apis/v2/scholar/search/scholar source: https://github.com/AIsa-team/aisa-proxy /scholar/search/explain: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.0024 cost_tier: low summary: Explain search results description: 'Explain a result set you already fetched. Unlike the three search endpoints this one takes a **JSON body**: `search_id` (required — the `id` returned by `post_scholar_search_web`, `post_scholar_search_scholar` or `post_scholar_search_mixed`), plus `detail_level` (BRIEF / MODERATE / DETAILED), `language`, and `response_mode`. ⚠️ Use `response_mode: NON_STREAMING`. It returns `{"message": "…"}` as JSON, measured at about 2 KB. The COMPLETE and INCREMENTAL modes emit server-sent events in which **each event repeats the whole answer so far** — the identical explanation measured 177 KB that way, roughly 90 times larger, and a tool call cannot consume a stream incrementally anyway. It only ever explains an existing search; it cannot run one.' operationId: post_scholar_search_explain tags: - Scholar Search security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExplainSearchRequest' responses: '200': description: Successful explanation response. COMPLETE/INCREMENTAL stream text/event-stream; NON_STREAMING returns application/json. content: application/json: schema: $ref: '#/components/schemas/ExplainSearchResponse' text/event-stream: schema: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' x-x402: path: /apis/v2/scholar/search/explain source: https://github.com/AIsa-team/aisa-proxy /polymarket/markets: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.00044 cost_tier: low summary: Get Polymarket Markets description: |- List individual Polymarket prediction markets — one binary question each — with live pricing. Use this when you need the market-implied probability of a specific outcome, or to screen markets by size and timing; filter with `slug`, `condition_ids`, `clob_token_ids`, `tag_id`, `closed`, and the `volume_num_*` / `start_date_*` / `end_date_*` ranges. Returns a top-level array of market objects. The probability signal is `outcomes` paired with `outcomePrices`, quoted against `bestBid` / `bestAsk`; `conditionId` and `clobTokenIds` are the on-chain identifiers you need to join to other Polymarket data. For the topic that groups several related questions together, use `get_polymarket_events`. For the same kind of question on the US-regulated Kalshi exchange, use `get_kalshi_markets`. operationId: get_polymarket_markets parameters: - name: limit in: query required: false description: Maximum number of markets to return. schema: type: integer minimum: 0 example: 20 - name: offset in: query required: false description: Number of markets to skip for offset-based pagination. schema: type: integer minimum: 0 example: 0 - name: order in: query required: false description: Comma-separated list of fields to order by. schema: type: string example: volume - name: ascending in: query required: false description: Sort ascending when true. schema: type: boolean example: false - name: id in: query required: false description: Filter by one or more Polymarket market IDs. schema: type: array items: type: integer example: - 540817 style: form explode: true - name: slug in: query required: false description: Filter by one or more market slugs. schema: type: array items: type: string example: - new-rhianna-album-before-gta-vi-926 style: form explode: true - name: clob_token_ids in: query required: false description: Filter by one or more CLOB token IDs. schema: type: array items: type: string style: form explode: true - name: condition_ids in: query required: false description: Filter by one or more market condition IDs. schema: type: array items: type: string example: - '0x1fad72fae204143ff1c3035e99e7c0f65ea8d5cd9bd1070987bd1a3316f772be' style: form explode: true - name: volume_num_min in: query required: false description: Minimum total volume. schema: type: number example: 1000 - name: volume_num_max in: query required: false description: Maximum total volume. schema: type: number example: 1000000 - name: start_date_min in: query required: false description: Filter markets starting after this ISO timestamp. schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - name: start_date_max in: query required: false description: Filter markets starting before this ISO timestamp. schema: type: string format: date-time example: '2026-01-01T00:00:00Z' - name: end_date_min in: query required: false description: Filter markets ending after this ISO timestamp. schema: type: string format: date-time example: '2025-01-01T00:00:00Z' - name: end_date_max in: query required: false description: Filter markets ending before this ISO timestamp. schema: type: string format: date-time example: '2026-01-01T00:00:00Z' - name: tag_id in: query required: false description: Filter by tag ID. schema: type: integer example: 1 - name: closed in: query required: false description: Filter by whether the market is closed. schema: type: boolean default: false example: false - name: include_tag in: query required: false description: Include tag metadata when true. schema: type: boolean example: true responses: '200': description: Top-level array of Polymarket market objects content: application/json: schema: type: array items: type: object additionalProperties: true properties: id: type: string example: '540817' question: type: string example: New Rihanna Album before GTA VI? slug: type: string example: new-rhianna-album-before-gta-vi-926 conditionId: type: string example: '0x1fad72fae204143ff1c3035e99e7c0f65ea8d5cd9bd1070987bd1a3316f772be' clobTokenIds: description: Polymarket CLOB token IDs. The upstream Gamma API may encode this as a JSON string. oneOf: - type: string - type: array items: type: string outcomes: description: Market outcomes. The upstream Gamma API may encode this as a JSON string. oneOf: - type: string - type: array items: type: string outcomePrices: description: Outcome prices. The upstream Gamma API may encode this as a JSON string. oneOf: - type: string - type: array items: type: string active: type: boolean closed: type: boolean liquidity: type: string volume: type: string volumeNum: type: number bestBid: type: number bestAsk: type: number startDate: type: string format: date-time endDate: type: string format: date-time image: type: string icon: type: string description: type: string '400': description: Bad Request - Invalid parameters or validation errors content: application/json: schema: type: object properties: error: type: string example: Invalid search parameter message: type: string example: search must be at least 2 characters long examples: search_too_short: summary: Search query too short value: error: Invalid search parameter message: search must be at least 2 characters long search_with_other_params: summary: Search with other parameters value: error: Invalid query parameters message: search parameter cannot be used with other filter parameters invalid_limit: summary: Invalid limit value: error: Invalid limit parameter message: limit must be a number between 1 and 100 '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string example: Internal Server Error message: type: string example: Failed to fetch markets data tags: - Prediction Markets x-x402: path: /apis/v2/polymarket/markets source: https://github.com/AIsa-team/aisa-proxy /polymarket/events: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.00044 cost_tier: low summary: Get Polymarket Events description: |- List Polymarket events — the topic-level grouping that bundles related markets, such as an election or a season-long series. Use this to browse by subject rather than by individual question, or to find every market attached to one storyline; filter with `tag_slug`, `active`, `featured`, `archived`, `closed`, and the liquidity / volume ranges. Returns a top-level array of event objects with `title`, `ticker`, `slug`, `volume`, `volume24hr`, `liquidity`, `startDate` / `endDate`, and a nested `markets` array holding the tradable questions. When you already know which question you want and need its price, use `get_polymarket_markets` instead. operationId: get_polymarket_events parameters: - name: limit in: query required: false description: Maximum number of events to return. schema: type: integer minimum: 0 example: 20 - name: offset in: query required: false description: Number of events to skip for offset-based pagination. schema: type: integer minimum: 0 example: 0 - name: order in: query required: false description: Comma-separated list of fields to order by. schema: type: string example: volume - name: ascending in: query required: false description: Sort ascending when true. schema: type: boolean example: false - name: id in: query required: false description: Filter by one or more event IDs. schema: type: array items: type: integer style: form explode: true - name: slug in: query required: false description: Filter by one or more event slugs. schema: type: array items: type: string style: form explode: true - name: tag_id in: query required: false description: Filter by tag ID. schema: type: integer - name: tag_slug in: query required: false description: Filter by tag slug. schema: type: string example: sports - name: active in: query required: false description: Filter by active events. schema: type: boolean - name: archived in: query required: false description: Filter by archived events. schema: type: boolean - name: featured in: query required: false description: Filter by featured events. schema: type: boolean - name: closed in: query required: false description: Filter by whether the event is closed. schema: type: boolean - name: liquidity_min in: query required: false description: Minimum liquidity. schema: type: number - name: liquidity_max in: query required: false description: Maximum liquidity. schema: type: number - name: volume_min in: query required: false description: Minimum volume. schema: type: number - name: volume_max in: query required: false description: Maximum volume. schema: type: number - name: start_date_min in: query required: false description: Filter events starting after this ISO timestamp. schema: type: string format: date-time - name: start_date_max in: query required: false description: Filter events starting before this ISO timestamp. schema: type: string format: date-time - name: end_date_min in: query required: false description: Filter events ending after this ISO timestamp. schema: type: string format: date-time - name: end_date_max in: query required: false description: Filter events ending before this ISO timestamp. schema: type: string format: date-time responses: '200': description: Top-level array of Polymarket event objects content: application/json: schema: type: array items: type: object additionalProperties: true properties: id: type: string ticker: type: string slug: type: string title: type: string description: type: string active: type: boolean closed: type: boolean archived: type: boolean startDate: type: string format: date-time endDate: type: string format: date-time volume: type: string volume24hr: type: number liquidity: type: number image: type: string icon: type: string markets: type: array items: type: object additionalProperties: true '400': description: Bad Request - Invalid parameters content: application/json: schema: type: object properties: error: type: string example: Invalid status parameter message: type: string example: status must be 'open' or 'closed' examples: invalid_status: summary: Invalid status value: error: Invalid status parameter message: status must be 'open' or 'closed' invalid_limit: summary: Invalid limit value: error: Invalid limit parameter message: limit must be a number between 1 and 100 invalid_offset: summary: Invalid offset value: error: Invalid offset parameter message: offset must be a non-negative number '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string example: Internal Server Error message: type: string example: Failed to fetch events data tags: - Prediction Markets x-x402: path: /apis/v2/polymarket/events source: https://github.com/AIsa-team/aisa-proxy /polymarket/activity: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.012 cost_tier: med summary: Get Polymarket Wallet Activity description: |- Get one wallet's on-chain Polymarket activity — a per-address lookup, not a market-wide trade feed. The `user` parameter is required. Use it to reconstruct what a specific trader did — position splits, merges and redemptions, with size, price, and the transaction that settled them; narrow further with `market_slug`, `condition_id`, and the `start_time` / `end_time` Unix-second range. Returns `activities[]` with `side` (`MERGE` / `SPLIT` / `REDEEM`), `market_slug`, `condition_id`, `shares`, `price`, `timestamp`, and `tx_hash`, plus a `pagination` object whose key you pass back as `pagination_key`. For market-wide prices rather than one wallet's history, use `get_polymarket_markets`. operationId: get_polymarket_activity parameters: - name: user in: query required: true description: Wallet address or user identifier. Required by the runtime route. schema: type: string pattern: ^0x[0-9a-fA-F]{40}$ example: '0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b' - name: start_time in: query required: false description: Filter activity from this Unix timestamp in seconds (inclusive) schema: type: integer example: 1640995200 - name: end_time in: query required: false description: Filter activity until this Unix timestamp in seconds (inclusive) schema: type: integer example: 1672531200 - name: market_slug in: query required: false description: Filter activity by market slug schema: type: string example: bitcoin-up-or-down-july-25-8pm-et - name: condition_id in: query required: false description: Filter activity by condition ID schema: type: string example: '0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57' - name: limit in: query required: false description: Number of activities to return (1-1000) schema: type: integer minimum: 1 maximum: 1000 default: 100 example: 50 - name: pagination_key in: query required: false description: Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object. schema: type: string example: eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJzaWRlIjoiU1BMSVQiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjE5ODkwMTc3Nn0= responses: '200': description: Activity response with pagination content: application/json: schema: type: object properties: activities: type: array items: type: object properties: token_id: type: string example: '' side: type: string enum: - MERGE - SPLIT - REDEEM example: REDEEM market_slug: type: string example: will-the-doj-charge-boeing condition_id: type: string example: '0x92e4b1b8e0621fab0537486e7d527322569d7a8fd394b3098ff4bb1d6e1c0bbd' shares: type: number example: 187722726 description: Raw number of shares (from the blockchain) shares_normalized: type: number example: 187.722726 description: Number of shares normalized (raw divided by 1000000) price: type: number example: 1 block_number: type: integer description: Block number where the activity occurred example: 123456789 log_index: type: integer description: Log index of the activity event in the block example: 42 tx_hash: type: string example: '0x028baff23a90c10728606781d15077098ee93c991ea204aa52a0bd2869187574' title: type: string example: Will the DOJ charge Boeing? timestamp: type: integer description: Unix timestamp in seconds when the activity occurred example: 1721263049 order_hash: type: string example: '' user: type: string description: User wallet address example: '0xfd9c3e7f8c56eb4186372f343c873cce154b3873' pagination: type: object properties: limit: type: integer example: 50 count: type: integer description: Total number of activities matching the filters example: 1250 has_more: type: boolean description: Whether there are more activities available example: true pagination_key: type: string description: Base64-encoded cursor for the next page. Only present when there are more results. example: eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJzaWRlIjoiU1BMSVQiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjE5ODkwMTc3Nn0= '400': description: Bad Request - Invalid parameters or validation errors content: application/json: schema: type: object properties: error: type: string example: Missing required parameter message: type: string example: user parameter is required examples: invalid_start_time: summary: Invalid start_time parameter value: error: Invalid start_time parameter message: start_time must be a valid Unix timestamp invalid_end_time: summary: Invalid end_time parameter value: error: Invalid end_time parameter message: end_time must be a valid Unix timestamp invalid_time_range: summary: Invalid time range value: error: Invalid time range message: start_time must be less than end_time invalid_limit: summary: Invalid limit value: error: Invalid limit parameter message: limit must be a number between 1 and 1000 invalid_pagination_key: summary: Invalid pagination key value: error: Invalid pagination key message: pagination_key is invalid or corrupted invalid_filter_combination: summary: Invalid filter combination value: error: Invalid filter combination message: Only one of market_slug or condition_id can be provided '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string example: Internal Server Error message: type: string example: Failed to fetch activity data tags: - Prediction Markets x-x402: path: /apis/v2/polymarket/activity source: https://github.com/AIsa-team/aisa-proxy /reddit/search: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Reddit operationId: get_reddit_search summary: Search Reddit description: Searches every public subreddit for posts matching a query and returns posts plus an after token to page. Each post carries title, author, selftext, selftext_html, subreddit, score, ups, downs, upvote_ratio, num_comments, created_utc, created_at_iso, url, permalink, subreddit_subscribers, is_video, over_18 and spoiler. sort accepts relevance, new, top and comment_count, and timeframe narrows the window. Measured at 8 to 16 seconds and 8 to 26 KB, the slowest endpoint here. To stay inside one community use get_reddit_subreddit_search, which is faster and pages with cursor rather than after; to read one post's discussion use get_reddit_post_comments. parameters: - name: query in: query required: true description: Search query schema: type: string - name: sort in: query required: false description: Sort by schema: type: string enum: - relevance - new - top - comment_count example: relevance - name: timeframe in: query required: false description: Timeframe schema: type: string enum: - all - day - week - month - year example: all - name: after in: query required: false description: Used to paginate to next page schema: type: string example: t3_1i8z28z - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: success: true posts: - id: w63dgy author: Morgentau7 author_fullname: t2_2hy2xjit subreddit: MadeMeSmile title: Player realizes that he nearly stole the dogs job downs: 0 name: t3_w63dgy upvote_ratio: 0.97 ups: 220403 total_awards_received: 0 score: 220403 created: 1658580900 num_comments: 1246 url: https://www.reddit.com/r/MadeMeSmile/comments/w63dgy/player_realizes_that_he_nearly_stole_the_dogs_job/ subreddit_subscribers: 11605207 is_video: true created_utc: 1658580900 after: t3_1izmcgx schema: $ref: '#/components/schemas/RedditPostsResponse' x-x402: path: /apis/v2/reddit/search source: https://github.com/AIsa-team/aisa-proxy /reddit/subreddit: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Reddit operationId: get_reddit_subreddit summary: Subreddit Posts description: 'Returns the post stream of one subreddit with an after token to page. Posts carry the same fields as get_reddit_search, including title, author, selftext, score, ups, upvote_ratio, num_comments, created_utc, created_at_iso, url, permalink and subreddit_subscribers. sort accepts best, hot, new, top and rising. Important: timeframe is only accepted together with sort=top, and any other combination returns 400 rather than ignoring the parameter. Subreddit names are case-sensitive. Measured at about 18 KB for 24 posts. To search inside the same subreddit use get_reddit_subreddit_search, and for its metadata use get_reddit_subreddit_details.' parameters: - name: subreddit in: query required: true description: Subreddit name schema: type: string - name: timeframe in: query required: false description: Timeframe to get posts from. Runtime requires `sort=top` when `timeframe` is provided. schema: type: string enum: - all - day - week - month - year - name: sort in: query required: false description: Sort order schema: type: string enum: - best - hot - new - top - rising - name: after in: query required: false description: After to get more posts. Get 'after' from previous response. schema: type: string example: t3_1234567890 - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: posts: - id: 1lfbo7u author: Vetro_Nodulare2 author_fullname: t2_16syu27ar1 subreddit: AskReddit title: What is a thing you love that lots of people hate? downs: 0 name: t3_1lfbo7u upvote_ratio: 0.9 ups: 45 total_awards_received: 0 score: 45 created: 1750341959 num_comments: 349 url: https://www.reddit.com/r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/ subreddit_subscribers: 56146328 is_video: false created_utc: 1750341959 after: t3_1lfogps schema: $ref: '#/components/schemas/RedditPostsResponse' '400': description: Bad request, for example when `timeframe` is provided with a sort other than `top`. content: application/json: schema: $ref: '#/components/schemas/AIsaSocialError' x-x402: path: /apis/v2/reddit/subreddit source: https://github.com/AIsa-team/aisa-proxy /reddit/subreddit/details: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Reddit operationId: get_reddit_subreddit_details summary: Subreddit Details description: 'Returns metadata about one subreddit, by name or by URL: subreddit_id, display_name, subscribers, weekly_active_users, weekly_contributions, description, rules, icon_img, header_img, advertiser_category, submit_text and created_at. Use it to size a community or read its rules before posting anything elsewhere. The name is case-sensitive, so AskReddit resolves and askreddit does not. Measured at about 5 KB, the smallest response here. It returns no posts at all: for those call get_reddit_subreddit, or get_reddit_subreddit_search to query within the community.' parameters: - name: subreddit in: query required: false description: Subreddit name. MUST be case sensitive. So 'AskReddit' not 'askreddit'. schema: type: string example: AskReddit - name: url in: query required: false description: Subreddit URL schema: type: string example: https://www.reddit.com/r/AbsoluteUnits/ responses: '200': description: Successful response content: application/json: example: success: true credits_remaining: 33950256 subreddit_id: t5_a7wuv display_name: AbsoluteUnits weekly_active_users: 1428398 weekly_contributions: 8923 rules: "#ABSOLUTE UNITS\n\n---\n\n Be in awe at the size of these lads\n\n---\n\n###[Check out our deep,\ \ well-reflected definitions of an absolute unit.](https://www.reddit.com/r/AbsoluteUnits/wiki/index) " description: 'Absolute Unit : an Animal or Public Figure, who is larger than we should normally expect.' header_img: null icon_img: https://styles.redditmedia.com/t5_a7wuv/styles/communityIcon_t3cspt08bl681.png?width=128&frame=1&auto=webp&s=6f7e59ccf1724bd6c8b3e0d2840c9b21297102c3 subscribers: 1923642 advertiser_category: '' created_at: '2018-01-05T10:35:24.000Z' submit_text: '' schema: $ref: '#/components/schemas/RedditSubredditDetailsResponse' x-x402: path: /apis/v2/reddit/subreddit/details source: https://github.com/AIsa-team/aisa-proxy /reddit/subreddit/search: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Reddit operationId: get_reddit_subreddit_search summary: Search Within Subreddit description: 'Searches inside one subreddit and returns matching posts with a cursor token to page. Posts carry title, author, selftext, score, ups, upvote_ratio, num_comments, created_utc, created_at_iso, url, permalink and is_video. Despite what sort suggests, every sort value returns posts and only posts: comments and media were confirmed absent from all five. Measured at about 5 KB and 2 seconds, faster than get_reddit_search, which searches all of Reddit and pages with after instead of cursor. For the replies under a result, pass its url to get_reddit_post_comments.' parameters: - name: subreddit in: query required: true description: Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL) schema: type: string - name: query in: query required: false description: Search query to find matching content schema: type: string example: push ups - name: sort in: query required: false description: 'Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new' schema: type: string enum: - relevance - hot - top - new - comments - name: timeframe in: query required: false description: Timeframe to filter results schema: type: string enum: - all - year - month - week - day - hour - name: cursor in: query required: false description: Cursor to get more results. Get 'cursor' from previous response. schema: type: string example: eyJjYW5kaWRhdGVzX3JldHVybmVkIjoi... responses: '200': description: Successful response content: application/json: example: posts: - id: t3_8gmjrb post_id: t3_8gmjrb title: Is doing 50-100 pushups a day doing anything? url: https://www.reddit.com/r/Fitness/comments/8gmjrb/is_doing_50100_pushups_a_day_doing_anything/ permalink: /r/Fitness/comments/8gmjrb/is_doing_50100_pushups_a_day_doing_anything/ nsfw: false spoiler: false is_crosspost: false subreddit: id: t5_2qhx4 name: Fitness nsfw: false quarantined: false icon: https://b.thumbs.redditmedia.com/Ted4KOMuRbaCYlDS55cTqjpVVZ2ENHKtYFbBFjI1i2o.png banner: null description: |- A place for the pursuit of physical fitness goals. Please see the r/Fitness Wiki and FAQ at https://thefitness.wiki for help with common questions. weekly_visitors: 898726 weekly_contributions: 1827 votes: 1414 num_comments: 582 created_at: 2018-05-03T01:09:17.620000+0000 created_at_iso: '2018-05-03T01:09:17.620Z' thumbnail: null thumbnail_blurred: false position: 0 relative_position: 0 comments: - id: t1_nxf7p27 post_id: t3_1q2p898 parent_comment_id: null is_reply_to_comment: false author: Philser23 author_avatar: null author_nsfw: false body: On the 30th my girlfriend out of the blue decided her new year's resolution would be to start going to the gym. I was so excited since none of my partners ever shared the fitness hobby with me. body_html:

On the 30th my girlfriend out of the blue decided her new year's resolution would be to start going to the gym...

images: [] votes: 123 url: https://www.reddit.com/r/Fitness/comments/1q2p898/gym_story_saturday/nxf7p27/ permalink: /r/Fitness/comments/1q2p898/gym_story_saturday/nxf7p27/ created_at: 2026-01-03T11:26:02.434000+0000 created_at_iso: '2026-01-03T11:26:02.434Z' post: id: t3_1q2p898 title: Gym Story Saturday url: https://www.reddit.com/r/Fitness/comments/1q2p898/gym_story_saturday/ permalink: /r/Fitness/comments/1q2p898/gym_story_saturday/ nsfw: false spoiler: false votes: 67 num_comments: 80 created_at: 2026-01-03T08:15:49.709000+0000 created_at_iso: '2026-01-03T08:15:49.709Z' subreddit: id: t5_2qhx4 name: Fitness nsfw: false quarantined: false icon: https://b.thumbs.redditmedia.com/Ted4KOMuRbaCYlDS55cTqjpVVZ2ENHKtYFbBFjI1i2o.png position: 0 media: - id: t3_geo4x title: Bodyweight training for really strong people. See on you're own what I mean with strong. (Not me) url: https://www.reddit.com/r/Fitness/comments/geo4x/bodyweight_training_for_really_strong_people_see/ permalink: /r/Fitness/comments/geo4x/bodyweight_training_for_really_strong_people_see/ media_type: image video: null image: src: https://external-preview.redd.it/X6lz5yGIzqVA5LcI9w-FsQJJHhXoCugDhsXgWW3I404.jpg?format=pjpg&auto=webp&s=46814b0a707a532e39e6c20851ddc1fefb0a111f width: 480 height: 360 resolutions: - url: https://external-preview.redd.it/X6lz5yGIzqVA5LcI9w-FsQJJHhXoCugDhsXgWW3I404.jpg?width=320&crop=smart&format=pjpg&auto=webp&s=144ac4171a1862e5d91d8dd90d44271e22a8273d width: 320 gallery_count: null aspect_ratio: 1.3333333333333333 nsfw: false spoiler: false is_blurred: false subreddit: id: t5_2qhx4 name: Fitness nsfw: false quarantined: false position: 0 safe_search: UNAVAILABLE cursor: eyJjYW5kaWRhdGVzX3JldHVybmVkIjoie1wic2VjdGlvbl8xX3BpcGVsaW5lXzBfZ2xvYmFsX21vZGlmaWVyc1wiOlwiM1wiLFwic2VjdGlvbl8xX3BpcGVsaW5lXzFfbG9jYWxfbW9kaWZpZXJzXCI6XCIzXCIsXCJzZWN0aW9uXzJfcGlwZWxpbmVfNl9zY29wZV9zd2l0Y2hlclwiOlwiMFwiLFwic2VjdGlvbl8yX3BpcGVsaW5lXzdfcG9zdF9zZWFyY2hcIjpcIjdcIn0ifQ== schema: $ref: '#/components/schemas/RedditPostsResponse' x-x402: path: /apis/v2/reddit/subreddit/search source: https://github.com/AIsa-team/aisa-proxy /reddit/post/comments: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.012 observed_usd: min: 0.00376 p50: 0.012 p95: 0.012 max: 0.012 cost_drivers: - param: records returned effect: charge scales with number of records returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Reddit operationId: get_reddit_post_comments summary: Post Comments description: 'Returns one post and its discussion from a post URL: post with title, author, selftext, score, ups, upvote_ratio, num_comments, created_utc, permalink, archived and locked, then comments, each with author, body, score, ups, downs, created_utc, parent_id, permalink and a nested replies object holding items and more. Paging is a third shape again: the top level carries more.has_more and more.cursor rather than the after of get_reddit_search or the cursor of get_reddit_subreddit_search. Measured at about 21 KB for 19 top-level comments. To find posts worth opening, start from get_reddit_search or get_reddit_subreddit.' parameters: - name: url in: query required: true description: Reddit post URL schema: type: string example: https://www.reddit.com/r/AskReddit/comments/ablzuq/people_who_havent_pooped_in_2019_yet_why_are_you/ - name: cursor in: query required: false description: Cursor to get more comments, or replies. schema: type: string example: ed1lvsa,ed3fnpq,ed25l2w - name: trim in: query required: false description: Set to true for a trimmed down version of the response schema: type: boolean example: 'false' responses: '200': description: Successful response content: application/json: example: comments: - id: mymupxb author: Background-Emu-2890 author_fullname: t2_efdlposp6 body: Black cat i have one and i love her so much ! name: t1_mymupxb created_utc: 1750342221 created_at_iso: '2025-06-19T14:10:21.000Z' parent_id: t3_1lfbo7u url: https://www.reddit.com/r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/mymupxb/ replies: items: - url: https://www.reddit.com/r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/mymxwde/ created_utc: 1750343166 created_at_iso: '2025-06-19T14:26:06.000Z' subreddit_id: t5_2qh1i approved_at_utc: null author_is_blocked: false comment_type: null awarders: [] mod_reason_by: null banned_by: null author_flair_type: text total_awards_received: 0 subreddit: AskReddit author_flair_template_id: null likes: null replies: items: [] more: has_more: false next_cursor: null user_reports: [] saved: false id: mymxwde banned_at_utc: null mod_reason_title: null gilded: 0 archived: false collapsed_reason_code: null no_follow: false author: doublestitch can_mod_post: false send_replies: true parent_id: t1_mymupxb score: 19 author_fullname: t2_10py0g removal_reason: null approved_by: null mod_note: null all_awardings: [] body: House panthers for the win edited: false top_awarded_type: null author_flair_css_class: null name: t1_mymxwde is_submitter: false downs: 0 author_flair_richtext: [] author_patreon_flair: false body_html: |- <div class="md"><p>House panthers for the win</p> </div> gildings: {} collapsed_reason: null distinguished: null associated_award: null stickied: false author_premium: false can_gild: false link_id: t3_1lfbo7u unrepliable_reason: null author_flair_text_color: null score_hidden: false permalink: /r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/mymxwde/ subreddit_type: public locked: false report_reasons: null created: 1750343166 author_flair_text: null treatment_tags: [] collapsed: false subreddit_name_prefixed: r/AskReddit controversiality: 0 depth: 1 author_flair_background_color: null collapsed_because_crowd_control: null mod_reports: [] num_reports: null ups: 19 more: has_more: true cursor: myn970w ups: 75 downs: 0 score: 75 post: id: 1lfbo7u author: Vetro_Nodulare2 author_fullname: t2_16syu27ar1 subreddit: AskReddit title: What is a thing you love that lots of people hate? downs: 0 name: t3_1lfbo7u upvote_ratio: 0.91 ups: 47 total_awards_received: 0 score: 47 created: 1750341959 num_comments: 353 url: https://www.reddit.com/r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/ subreddit_subscribers: 56146601 is_video: false created_utc: 1750341959 more: has_more: true cursor: myoaw2m,myob40l,myoeo9h schema: $ref: '#/components/schemas/RedditCommentsResponse' x-x402: path: /apis/v2/reddit/post/comments source: https://github.com/AIsa-team/aisa-proxy /semrush/domain-overview: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.003 cost_tier: low note: price reflects the current pricing revision; historical charges may be higher (a prior revision billed more) summary: Domain Overview description: 'Return the organic search overview for a domain in a given regional database: Rank, organic keyword count, organic traffic, organic traffic cost, and Adwords keyword count. Billed $0.09 per successful call; 4xx/5xx are not charged. Response is semicolon-delimited text.' operationId: get_semrush_domain_overview parameters: - name: domain in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string - name: database in: query required: false description: 'Regional database / country code. Defaults to `us`. Examples: `us`, `uk`, `cn`.' schema: type: string default: us responses: '200': description: 'Semicolon-delimited overview: Database;Domain;Rank;OrganicKeywords;OrganicTraffic;OrganicCost;AdwordsKeywords.' content: text/plain: schema: type: string example: us;ahrefs.com;1843;204139;1387538;4247450;679 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/domain-overview source: https://github.com/AIsa-team/aisa-proxy /semrush/backlinks-overview: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.01 cost_tier: low note: price reflects the current pricing revision; historical charges may be higher (a prior revision billed more) summary: Backlinks Overview description: 'Return the backlink profile summary for a root domain: authority score (ascore), total backlinks, referring domains, referring URLs, and referring IPs. Billed $0.30 per successful call; 4xx/5xx are not charged. Response is semicolon-delimited text.' operationId: get_semrush_backlinks_overview parameters: - name: target in: query required: true description: Target root domain, e.g. `ahrefs.com`. schema: type: string responses: '200': description: 'Semicolon-delimited overview: ascore;total_backlinks;referring_domains;referring_urls;referring_ips.' content: text/plain: schema: type: string example: 73;7376713;127172;5228834;87874 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/backlinks-overview source: https://github.com/AIsa-team/aisa-proxy /semrush/keyword-overview: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.003 cost_tier: low note: price reflects the current pricing revision; historical charges may be higher (a prior revision billed more) summary: Keyword Overview description: 'Return search metrics for a keyword phrase in a given regional database: search volume, CPC, competition, and number of results. Billed $0.09 per successful call; 4xx/5xx are not charged. Response is semicolon-delimited text.' operationId: get_semrush_keyword_overview parameters: - name: phrase in: query required: true description: Keyword phrase. URL-encode spaces as `%20` or `+`. schema: type: string example: seo tools - name: database in: query required: false description: Regional database / country code. Defaults to `us`. schema: type: string default: us responses: '200': description: 'Semicolon-delimited overview: Keyword;SearchVolume;CPC;Competition;NumberOfResults.' content: text/plain: schema: type: string example: seo tools;550000;7.79;0.03;124 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/keyword-overview source: https://github.com/AIsa-team/aisa-proxy /semrush/keyword-difficulty: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.45 observed_usd: min: 0.015 p50: 0.105 p95: 0.9 max: 0.9 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Keyword Difficulty description: Keyword Difficulty Index (0-100) for one or more keywords. Billed per returned data row at $0.45 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_keyword_difficulty parameters: - name: phrase in: query required: true description: One or more keywords separated by `;` (up to 20). schema: type: string example: seo tools;ahrefs - name: database in: query required: false description: Regional database / country code. Defaults to `us`. schema: type: string default: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;Keyword Difficulty Index`.' content: text/plain: schema: type: string example: |- Keyword;Keyword Difficulty Index seo tools;94 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/keyword-difficulty source: https://github.com/AIsa-team/aisa-proxy /semrush/keyword-organic-results: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.09 observed_usd: min: 0.051 p50: 0.06 p95: 0.18 max: 1.8 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Organic Results description: Domains and URLs currently ranking in Google organic results for a keyword. Billed per returned data row at $0.09 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_organic_results parameters: - name: phrase in: query required: true description: Keyword phrase. URL-encode spaces as `%20` or `+`. schema: type: string example: seo tools - name: database in: query required: false description: Regional database / country code. Defaults to `us`. schema: type: string default: us responses: '200': description: 'Semicolon-delimited rows. Header: `Domain;Url;Keywords SERP Features;SERP Features`.' content: text/plain: schema: type: string example: |- Domain;Url;Keywords SERP Features;SERP Features smallseotools.com;https://smallseotools.com/;6,7,9;6,7,9 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/keyword-organic-results source: https://github.com/AIsa-team/aisa-proxy /semrush/keyword-paid-results: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.18 observed_usd: min: 0.048 max: 0.36 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Paid Results description: Domains and URLs currently running Google Ads for a keyword. Billed per returned data row at $0.18 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_paid_results parameters: - name: phrase in: query required: true description: Keyword phrase. URL-encode spaces as `%20` or `+`. schema: type: string example: seo tools - name: database in: query required: false description: Regional database / country code. Defaults to `us`. schema: type: string default: us responses: '200': description: 'Semicolon-delimited rows. Header: `Domain;Url`.' content: text/plain: schema: type: string example: |- Domain;Url progressive.com;https://www.progressive.com/lp/insurance-superstore tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/keyword-paid-results source: https://github.com/AIsa-team/aisa-proxy /semrush/broad-match-keywords: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.18 observed_usd: min: 0.006 p50: 0.12 p95: 3.6 max: 3.6 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Broad Match Keywords description: Broad-match and alternate keyword variants for a seed phrase, with volume and CPC. Billed per returned data row at $0.18 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_broad_match_keywords parameters: - name: phrase in: query required: true description: Keyword phrase. URL-encode spaces as `%20` or `+`. schema: type: string example: seo tools - name: database in: query required: false description: Regional database / country code. Defaults to `us`. schema: type: string default: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;Search Volume;CPC`.' content: text/plain: schema: type: string example: |- Keyword;Search Volume;CPC seo tools;550000;7.79 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/broad-match-keywords source: https://github.com/AIsa-team/aisa-proxy /semrush/question-keywords: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 7.2 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Question Keywords description: Question-form keyword variations for a seed phrase, with volume and CPC. Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_question_keywords parameters: - name: phrase in: query required: true description: Keyword phrase. URL-encode spaces as `%20` or `+`. schema: type: string example: seo tools - name: database in: query required: false description: Regional database / country code. Defaults to `us`. schema: type: string default: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;Search Volume;CPC`.' content: text/plain: schema: type: string example: |- Keyword;Search Volume;CPC what is seo;40500;2.05 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/question-keywords source: https://github.com/AIsa-team/aisa-proxy /semrush/domain-rank-history: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.09 observed_usd: min: 0.06 max: 1.8 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Rank History description: Historical rank, organic traffic and keyword-count trajectory for a domain. Billed per returned data row at $0.09 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_domain_rank_history parameters: - name: domain in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string example: ahrefs.com - name: database in: query required: true description: Regional database / country code, e.g. `us`. schema: type: string example: us responses: '200': description: 'Semicolon-delimited rows. Header: `Rank;Organic Keywords;Organic Traffic;Organic Cost`.' content: text/plain: schema: type: string example: |- Rank;Organic Keywords;Organic Traffic;Organic Cost 1332;209108;1909338;6145922 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/domain-rank-history source: https://github.com/AIsa-team/aisa-proxy /semrush/domain-organic-keywords: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.09 observed_usd: min: 0.006 p50: 0.06 p95: 0.06 max: 0.18 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Organic Keywords description: Keywords a domain ranks for in Google organic (position, volume, CPC, URL). Billed per returned data row at $0.09 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_domain_organic_keywords parameters: - name: domain in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string example: ahrefs.com - name: database in: query required: true description: Regional database / country code, e.g. `us`. schema: type: string example: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;Position;Search Volume;CPC;Url`.' content: text/plain: schema: type: string example: |- Keyword;Position;Search Volume;CPC;Url search operators;1;1220000;2.02;https://ahrefs.com/blog/google-advanced-search-operators/ tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/domain-organic-keywords source: https://github.com/AIsa-team/aisa-proxy /semrush/domain-paid-keywords: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.18 observed_usd: min: 0.12 max: 3.6 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain Paid Keywords description: Keywords a domain bids on in Google Ads (position, volume, CPC, URL). Billed per returned data row at $0.18 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_domain_paid_keywords parameters: - name: domain in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string example: ahrefs.com - name: database in: query required: true description: Regional database / country code, e.g. `us`. schema: type: string example: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;Position;Search Volume;CPC;Url`.' content: text/plain: schema: type: string example: |- Keyword;Position;Search Volume;CPC;Url hotels near me;1;2240000;1.45;https://www.booking.com/ tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/domain-paid-keywords source: https://github.com/AIsa-team/aisa-proxy /semrush/domain-organic-competitors: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 7.2 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Organic Competitors description: Domains competing with a target in Google organic search. Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_organic_competitors parameters: - name: domain in: query required: true description: Target domain, e.g. `ahrefs.com`. schema: type: string example: ahrefs.com - name: database in: query required: true description: Regional database / country code, e.g. `us`. schema: type: string example: us responses: '200': description: 'Semicolon-delimited rows. Header: `Domain;Competitor Relevance;Common Keywords;Organic Keywords`.' content: text/plain: schema: type: string example: |- Domain;Competitor Relevance;Common Keywords;Organic Keywords seranking.com;0.36;13476;78356 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/domain-organic-competitors source: https://github.com/AIsa-team/aisa-proxy /semrush/domain-vs-domain: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.72 observed_usd: min: 0.48 max: 14.4 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Domain vs Domain description: Cross-domain keyword position comparison across up to 5 domains. Billed per returned data row at $0.72 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_domain_vs_domain parameters: - name: domains in: query required: true description: 'Comparison spec: `sign|type|domain` groups joined by `|` (sign in + - * /, type in `or`/`ad`). Example: `+|or|ahrefs.com|+|or|semrush.com`.' schema: type: string example: +|or|ahrefs.com|+|or|semrush.com - name: database in: query required: true description: Regional database / country code, e.g. `us`. schema: type: string example: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;ahrefs.com`.' content: text/plain: schema: type: string example: |- Keyword;ahrefs.com ai detector;79 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/domain-vs-domain source: https://github.com/AIsa-team/aisa-proxy /semrush/url-organic-keywords: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.09 observed_usd: min: 0.06 max: 0.18 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: URL Organic Keywords description: Keywords a specific URL ranks for in Google organic. Billed per returned data row at $0.09 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_url_organic_keywords parameters: - name: url in: query required: true description: Target URL (landing page). schema: type: string example: https://ahrefs.com/blog/ - name: database in: query required: true description: Regional database / country code, e.g. `us`. schema: type: string example: us responses: '200': description: 'Semicolon-delimited rows. Header: `Keyword;Position;Search Volume;CPC`.' content: text/plain: schema: type: string example: |- Keyword;Position;Search Volume;CPC ahrefs blog;1;2900;4.98 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/url-organic-keywords source: https://github.com/AIsa-team/aisa-proxy /semrush/backlinks: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 7.2 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlinks description: Individual backlink records pointing at a target (source, target, anchor). Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_backlinks parameters: - name: target in: query required: true description: Target domain or URL. schema: type: string example: ahrefs.com - name: target_type in: query required: true description: One of `root_domain`, `domain`, or `url`. schema: type: string example: root_domain responses: '200': description: 'Semicolon-delimited rows. Header: `source_url;target_url;anchor`.' content: text/plain: schema: type: string example: |- source_url;target_url;anchor https://example.com/post;https://ahrefs.com/blog/agentic-marketing/;Agentic Marketing tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/backlinks source: https://github.com/AIsa-team/aisa-proxy /semrush/referring-domains: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 0.72 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Referring Domains description: Referring domains linking to a target, aggregated by domain. Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_referring_domains parameters: - name: target in: query required: true description: Target domain or URL. schema: type: string example: ahrefs.com - name: target_type in: query required: true description: One of `root_domain`, `domain`, or `url`. schema: type: string example: root_domain responses: '200': description: 'Semicolon-delimited rows. Header: `domain;backlinks_num`.' content: text/plain: schema: type: string example: |- domain;backlinks_num mein-tagwerk.de;872721 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/referring-domains source: https://github.com/AIsa-team/aisa-proxy /semrush/backlink-anchors: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 0.72 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlink Anchors description: Anchor-text distribution of backlinks to a target. Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_backlink_anchors parameters: - name: target in: query required: true description: Target domain or URL. schema: type: string example: ahrefs.com - name: target_type in: query required: true description: One of `root_domain`, `domain`, or `url`. schema: type: string example: root_domain responses: '200': description: 'Semicolon-delimited rows. Header: `anchor;backlinks_num`.' content: text/plain: schema: type: string example: |- anchor;backlinks_num ahrefs;1658450 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/backlink-anchors source: https://github.com/AIsa-team/aisa-proxy /semrush/indexed-pages: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 0.72 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Indexed Pages description: Pages of a target that have backlinks (page-level breakdown). Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_indexed_pages parameters: - name: target in: query required: true description: Target domain or URL. schema: type: string example: ahrefs.com - name: target_type in: query required: true description: One of `root_domain`, `domain`, or `url`. schema: type: string example: root_domain responses: '200': description: 'Semicolon-delimited rows. Header: `source_url;backlinks_num`.' content: text/plain: schema: type: string example: |- source_url;backlinks_num https://ahrefs.com/;1706893 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/indexed-pages source: https://github.com/AIsa-team/aisa-proxy /semrush/backlink-competitors: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 3 nominal_usd: 0.36 observed_usd: min: 0.24 max: 0.72 cost_drivers: - param: display_limit (rows) effect: charge scales with number of rows returned (up to display_limit) cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Backlink Competitors description: Domains with a backlink profile similar to the target. Billed per returned data row at $0.36 per row (up to 20 rows; header row excluded); 4xx/5xx are not charged. Response is semicolon-delimited text. operationId: get_semrush_backlink_competitors parameters: - name: target in: query required: true description: Target domain or URL. schema: type: string example: ahrefs.com - name: target_type in: query required: true description: One of `root_domain`, `domain`, or `url`. schema: type: string example: root_domain responses: '200': description: 'Semicolon-delimited rows. Header: `neighbour;similarity`.' content: text/plain: schema: type: string example: |- neighbour;similarity semrush.com;0.477280 tags: - SEO & Search Data x-x402: path: /apis/v2/semrush/backlink-competitors source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/traffic-engagement: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 1 x metrics x periods credit_rate: 1 credit / (metric x month) cost_drivers: - param: metrics effect: number of metrics requested - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 metric + 1 month) = 1 credit ($0.10); cost grows with metrics and periods. summary: Traffic & Engagement description: 'Traffic & Engagement. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: the start_date-end_date span must cover between 1 and 120 monthly buckets.' operationId: get_similarweb_traffic_engagement parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly. Default: monthly.' schema: type: string enum: - monthly default: monthly - name: metrics in: query required: true description: Comma-separated metrics, e.g. visits,pages_per_visit. schema: type: string - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: 'Restrict to the main domain only (true/false). Default: True.' schema: type: boolean default: true - name: mtd in: query required: false description: Month-to-date flag (true/false). schema: type: boolean responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total metrics: - visits - pages_per_visit - average_visit_duration - bounce_rate - new_users - page_views - returning_users - unique_visitors state: null mtd: false main_domain_only: true status: success last_updated: '2026-07-31' data: - date: '2026-06-01' visits: 182538329.78179574 bounce_rate: 0.6402229356798581 average_visit_duration: 194.8333714917004 pages_per_visit: 1.9970684926970637 page_views: 364541547.1167704 unique_visitors: 32705292.619999997 new_users: 10074246.080150243 returning_users: 22631046.540221456 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: date: type: string visits: type: number bounce_rate: type: number average_visit_duration: type: number pages_per_visit: type: number page_views: type: number unique_visitors: type: number new_users: type: number returning_users: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/traffic-engagement source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/ranking: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 2 x periods credit_rate: 2 credits / (month) cost_drivers: - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 month) = 2 credits ($0.20); cost grows with periods. summary: Website Ranking description: 'Website Ranking. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: the start_date-end_date span must cover between 1 and 120 monthly buckets.' operationId: get_similarweb_ranking parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly. Default: monthly.' schema: type: string enum: - monthly default: monthly - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: 'Restrict to the main domain only (true/false). Default: True.' schema: type: boolean default: true responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total metrics: - country_rank - category_rank - category status: success last_updated: '2026-07-31' data: - date: '2026-06-01' country_rank: 69 category: News_and_Media category_rank: 5 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: date: type: string country_rank: type: integer category: type: string category_rank: type: integer tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/ranking source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/ppc-spend: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 1 x periods credit_rate: 1 credit / (month) cost_drivers: - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 month) = 1 credit ($0.10); cost grows with periods. summary: PPC Spend description: 'PPC Spend. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: the start_date-end_date span must cover between 1 and 120 monthly buckets.' operationId: get_similarweb_ppc_spend parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly. Default: monthly.' schema: type: string enum: - monthly default: monthly - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: 'Restrict to the main domain only (true/false). Default: True.' schema: type: boolean default: true responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: currency: usd format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total data_version: null main_domain_only: true status: success last_updated: '2026-07-31' data: - date: '2026-06-01' currency: usd ppc_spend: 136064.05 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: date: type: string currency: type: string ppc_spend: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/ppc-spend source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/top-sites-ranking: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(1 x rows); rows capped at 20 credit_rate: 1 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 1 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 20 credits ($2.00); limit=5 = 5 credits ($0.50) summary: Top Sites Ranking description: Top Sites Ranking. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_top_sites_ranking parameters: - name: category in: query required: true description: Industry category, e.g. Finance. schema: type: string - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: offset in: query required: false description: Row offset for pagination. schema: type: integer responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: channel: total format: json granularity: monthly country: us start_date: '2026-05-01' end_date: '2026-07-31' category: News_and_Media web_source: total status: success last_updated: '2026-07-31' data: - domain: yahoo.com rank: 1 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: domain: type: string rank: type: integer tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/top-sites-ranking source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/marketing-channel-sources-legacy: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 7 x periods credit_rate: 7 credits / (month) cost_drivers: - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 month) = 7 credits ($0.70); cost grows with periods. summary: Marketing Channel Sources description: 'Marketing Channel Sources. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: the start_date-end_date span must cover between 1 and 120 monthly buckets.' operationId: get_similarweb_marketing_channel_sources_legacy parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly. Default: monthly.' schema: type: string enum: - monthly default: monthly - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: 'Restrict to the main domain only (true/false). Default: True.' schema: type: boolean default: true responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total metrics: - visits mtd: false main_domain_only: true status: success last_updated: '2026-07-31' data: - date: '2026-06-01' source_type: Direct visits: 122433065.2298491 bounce_rate: null average_visit_duration: null pages_per_visit: null schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: date: type: string source_type: type: string visits: type: number bounce_rate: type: string average_visit_duration: type: string pages_per_visit: type: string tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/marketing-channel-sources-legacy source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/referrals: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(4 x rows); rows capped at 20 credit_rate: 4 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 4 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 80 credits ($8.00); limit=5 = 20 credits ($2.00) summary: Referrals description: Referrals. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_referrals parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: referral_type: incoming format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total main_domain_only: false status: success last_updated: '2026-07-31' data: - domain: citizenfreepress.com share: 0.1664343819749612 change: 0.44941053996464486 visits: 1083633.5339702675 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: domain: type: string share: type: number change: type: number visits: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/referrals source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/ad-networks: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(3 x rows); rows capped at 20 credit_rate: 3 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 3 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 60 credits ($6.00); limit=5 = 15 credits ($1.50) summary: Ad Networks description: Ad Networks. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_ad_networks parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: ad_network_type: incoming metrics: - share - change format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: desktop data_version: null main_domain_only: false status: success last_updated: '2026-07-31' data: - ad_network: Zeta Global share: 1 change: 0.4053466348518069 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: ad_network: type: string share: type: number change: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/ad-networks source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/similar-sites: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(5 x rows); rows capped at 20 credit_rate: 5 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 5 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 100 credits ($10.00); limit=5 = 25 credits ($2.50) summary: SimilarSites description: 'SimilarSites. Response follows the SimilarWeb v5 envelope (meta + data). Date window (upstream SimilarWeb constraint): start_date and end_date must span EXACTLY 3 consecutive months — a 1- or 2-month span is rejected with upstream error 120 (''must span exactly 3 month(s)''). That span must also be SimilarWeb''s most recent supported window, which advances forward each month; an older or out-of-range span is rejected with error 101 (''Dates not in range''). In practice, request the three most recent completed months (e.g. if the latest published month is 2026-07, use start_date=2026-05 and end_date=2026-07). To read the exact currently-supported range, call SimilarWeb''s /describe endpoint for this API.' operationId: get_similarweb_similar_sites parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: 'Start month, format YYYY-MM. Must be exactly 2 months before end_date: the window has to span exactly 3 consecutive months within SimilarWeb''s latest supported range (see the endpoint description).' schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. Together with start_date must span exactly 3 consecutive months, and must be the most recent supported month (the window rolls forward monthly; see the endpoint description). schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: format: json domain: cnn.com granularity: monthly start_date: '2026-05-01' end_date: '2026-07-31' metrics: - rank - affinity - has_adsense category: null status: success last_updated: '2026-07-31' data: - domain: bbc.com category: News_and_Media rank: 95 affinity: 1 has_adsense: true schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: domain: type: string category: type: string rank: type: integer affinity: type: number has_adsense: type: boolean tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/similar-sites source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/demographics: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 8 (fixed per request) credit_rate: 8 credits (fixed) cost_drivers: - param: (none) effect: flat per-request credit charge cost_tier: med example: 1 request = 8 credits ($0.80) summary: Demographics description: 'Demographics. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: start_date and end_date must fall in the SAME month (exactly one monthly bucket).' operationId: get_similarweb_demographics parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: true description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: total.' schema: type: string enum: - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: format in: query required: false description: 'Response format. Allowed: json.' schema: type: string enum: - json responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' metrics: - age_18_to_24_share - age_25_to_34_share - age_35_to_44_share - age_45_to_54_share - age_55_to_64_share - age_65_plus_share - male_share - female_share status: success last_updated: '2026-07-31' data: - age_18_to_24_share: 0.0684928856109901 age_25_to_34_share: 0.16978297333160164 age_35_to_44_share: 0.202684431962113 age_45_to_54_share: 0.2104190356035189 age_55_to_64_share: 0.21167119791609917 age_65_plus_share: 0.1369494755756772 male_share: 0.5816619373492008 female_share: 0.4183380626507992 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: age_18_to_24_share: type: number age_25_to_34_share: type: number age_35_to_44_share: type: number age_45_to_54_share: type: number age_55_to_64_share: type: number age_65_plus_share: type: number male_share: type: number female_share: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/demographics source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/deduplicated-audience: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 7 x periods credit_rate: 7 credits / (month) cost_drivers: - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 month) = 7 credits ($0.70); cost grows with periods. summary: Deduplicated Audience description: 'Deduplicated Audience. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: the start_date-end_date span must cover between 1 and 120 monthly buckets.' operationId: get_similarweb_deduplicated_audience parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly. Default: monthly.' schema: type: string enum: - monthly default: monthly - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: 'Restrict to the main domain only (true/false). Default: True.' schema: type: boolean default: true responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' metrics: - total_deduplicated_audience - desktop_only_audience_share - desktop_only_audience_visitors - mobile_web_only_audience_share - mobile_web_only_audience_visitors - desktop_and_mobile_web_audience_share - desktop_and_mobile_web_audience_visitors main_domain_only: true status: success last_updated: '2026-07-31' data: - date: '2026-06-01' total_deduplicated_audience: 23727616.32935698 desktop_only_audience_share: 0.12370405221553608 desktop_only_audience_visitors: 2935202.2893569823 mobile_web_only_audience_share: 0.4979319281532382 mobile_web_only_audience_visitors: 11814737.749356981 desktop_and_mobile_web_audience_share: 0.3783640196312258 desktop_and_mobile_web_audience_visitors: 8977676.290643018 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: date: type: string total_deduplicated_audience: type: number desktop_only_audience_share: type: number desktop_only_audience_visitors: type: number mobile_web_only_audience_share: type: number mobile_web_only_audience_visitors: type: number desktop_and_mobile_web_audience_share: type: number desktop_and_mobile_web_audience_visitors: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/deduplicated-audience source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/audience-interest: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(5 x rows); rows capped at 20 credit_rate: 5 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 5 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 100 credits ($10.00); limit=5 = 25 credits ($2.50) summary: Audience Interest description: Audience Interest. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_audience_interest parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total metrics: - affinity - overlap - pop_change - has_adsense - domain main_domain_only: false status: success last_updated: '2026-07-31' data: - domain: bbc.com affinity: 100 overlap: 0.09255490176393671 has_adsense: true pop_change: 0.01894630277754676 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: domain: type: string affinity: type: number overlap: type: number has_adsense: type: boolean pop_change: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/audience-interest source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/audience-overlap: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(2 x rows); rows capped at 5 credit_rate: 2 / row (max 5 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 2 credit/row; at most 5 rows are billed cost_tier: med example: 5 rows = 10 credits ($1.00); limit=5 = 10 credits ($1.00) summary: Audience Overlap description: 'Audience Overlap. Response follows the SimilarWeb v5 envelope (meta + data). Note: `data` may arrive grouped as an array of arrays; billing counts rows across all groups.' operationId: get_similarweb_audience_overlap parameters: - name: domains in: query required: true description: Two to five target domains, comma-separated (e.g. cnn.com,bbc.com). schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly. Default: monthly.' schema: type: string enum: - monthly default: monthly - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: request: metrics: - overlap - union format: json domains: cnn.com,bbc.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total status: success last_updated: '2026-07-31' data: - domains: bbc.com,cnn.com overlap_unique_visitors: 12918459.191519193 union_unique_users: 61619561.028480805 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: domains: type: string overlap_unique_visitors: type: number union_unique_users: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/audience-overlap source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/technologies: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 10 (fixed per request) credit_rate: 10 credits (fixed) cost_drivers: - param: (none) effect: flat per-request credit charge cost_tier: med example: 1 request = 10 credits ($1.00) summary: Website Technologies description: 'Website Technologies. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: start_date and end_date must be the SAME month, and that month must be the latest available data month — a single monthly bucket that advances as SimilarWeb refreshes its data, and which may differ by country. Supplying any other month returns SimilarWeb error_code 101 ("Dates not in range"); the error message states the currently-allowed range.' operationId: get_similarweb_technologies parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: true description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer maximum: 20 default: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: total.' schema: type: string enum: - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: format in: query required: false description: 'Response format. Allowed: json.' schema: type: string enum: - json responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: status: installed_and_removed format: json domain: cnn.com granularity: monthly start_date: '2026-07-01' end_date: '2026-07-31' metrics: - sub_category - pricing_model - description - first_seen_date main_domain_only: false category: null status: success last_updated: '2026-07-31' data: - technology: 24 7 Media category: Advertising sub_category: Publisher Ad Server pricing_model: Free description: 24/7 Media creates the tools for business advantage in the digital world. status: removed first_seen_date: '2018-04-21' schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: technology: type: string category: type: string sub_category: type: string pricing_model: type: string description: type: string status: type: string first_seen_date: type: string tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/technologies source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/popular-pages: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(3 x rows); rows capped at 20 credit_rate: 3 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 3 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 60 credits ($6.00); limit=5 = 15 credits ($1.50) summary: Popular Pages description: 'Popular Pages. Response follows the SimilarWeb v5 envelope (meta + data). Note: `data` may arrive grouped as an array of arrays; billing counts rows across all groups.' operationId: get_similarweb_popular_pages parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: classify: all utm: false page: null format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total metrics: - share - change status: success last_updated: '2026-07-31' data: - page: cnn.com share: 0.5037170076541321 change: -0.6326814889385246 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: page: type: string share: type: number change: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/popular-pages source: https://github.com/AIsa-team/aisa-proxy /similarweb/website/subdomains: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(2 x rows); rows capped at 20 credit_rate: 2 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 2 credit/row; at most 20 rows are billed cost_tier: high example: 20 rows = 40 credits ($4.00); limit=5 = 10 credits ($1.00) summary: Website Subdomains description: Website Subdomains. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_subdomains parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: desktop main_domain_only: false status: success last_updated: '2026-07-31' data: - subdomain: cnn.com share: 0.9567702368880975 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: subdomain: type: string share: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website/subdomains source: https://github.com/AIsa-team/aisa-proxy /similarweb/search/keyword-competitors: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(0.03 x rows); rows capped at 20 credit_rate: 0.03 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 0.03 credit/row; at most 20 rows are billed cost_tier: med example: 20 rows = 1 credit ($0.10); limit=5 = 1 credit ($0.10) summary: Keyword Competitors description: Keyword Competitors. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_keyword_competitors parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: Web source. This endpoint accepts desktop only (the gateway rejects mobile_web and total with 400). schema: type: string enum: - desktop - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: traffic_source: organic format: json domain: cnn.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: desktop metrics: - score - shared_keywords main_domain_only: false status: success last_updated: '2026-07-31' data: - url: robinhood.com score: 19.105918884277344 shared_keywords: 0.42673856019973755 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: url: type: string score: type: number shared_keywords: type: number tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/search/keyword-competitors source: https://github.com/AIsa-team/aisa-proxy /similarweb/search/website-keywords: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(0.1 x rows); rows capped at 20 credit_rate: 0.1 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 0.1 credit/row; at most 20 rows are billed cost_tier: med example: 20 rows = 2 credits ($0.20); limit=5 = 1 credit ($0.10) summary: Website Keywords description: 'Website Keywords. Response follows the SimilarWeb v5 envelope (meta + data). Date constraint: the start_date-end_date span must cover between 1 and 3 monthly buckets. Note: `data` may arrive grouped as an array of arrays; billing counts rows across all groups.' operationId: get_similarweb_keywords parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: true description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer maximum: 20 default: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: total.' schema: type: string enum: - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: format in: query required: false description: 'Response format. Allowed: json.' schema: type: string enum: - json responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: branded_type: all keywords_filter_rules: [] format: json domain: nike.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' traffic_source: all web_source: total metrics: - clicks - traffic_share - competition - primary_intent - secondary_intent - position - serp_features - top_url - url_count status: success last_updated: '2026-07-31' data: - keyword: nike clicks: 1001887.5658500849 traffic_share: 0.15853772273003125 competition: 100 primary_intent: Navigational secondary_intent: null position: 1 serp_features: - organic_sitelinks - organic_expanded_sitelinks - apps - pla - images - related_searches - popular_products - paid_sitelinks - paid - news - video - organic - local_pack - related_questions top_url: nike.com url_count: 1581 schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: keyword: type: string clicks: type: number traffic_share: type: number competition: type: integer primary_intent: type: string secondary_intent: type: string position: type: integer serp_features: type: string top_url: type: string url_count: type: integer tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/search/website-keywords source: https://github.com/AIsa-team/aisa-proxy /similarweb/search/serp-players-timeseries: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(0.02 x rows); rows capped at 20 credit_rate: 0.02 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 0.02 credit/row; at most 20 rows are billed cost_tier: med example: 20 rows = 1 credit ($0.10); limit=5 = 1 credit ($0.10) summary: SERP Players - Clicks over time description: SERP Players - Clicks over time. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_serp_players_timeseries parameters: - name: keyword in: query required: true description: Target keyword. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: offset in: query required: false description: Row offset for pagination. schema: type: integer responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: format: json keyword: nike granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' traffic_source: all web_source: total is_keyword_group: false status: success last_updated: '2026-07-31' data: - date: '2026-06-01' clicks: 1001887 domain: nike.com schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: date: type: string clicks: type: integer domain: type: string tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/search/serp-players-timeseries source: https://github.com/AIsa-team/aisa-proxy /similarweb/search/serp-players-aggregated: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(0.07 x rows); rows capped at 20 credit_rate: 0.07 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 0.07 credit/row; at most 20 rows are billed cost_tier: med example: 20 rows = 2 credits ($0.20); limit=5 = 1 credit ($0.10) summary: SERP Players - Aggregated description: SERP Players - Aggregated. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_serp_players_aggregated parameters: - name: keyword in: query required: true description: Target keyword. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: offset in: query required: false description: Row offset for pagination. schema: type: integer responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: format: json keyword: nike granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' traffic_source: all web_source: total metrics: - clicks - traffic_share - serp_features - top_url - top_url_position is_keyword_group: false status: success last_updated: '2026-07-31' data: - site: nike.com domain: nike.com clicks: 995980.9211660791 traffic_share: 0.9220950172205099 serp_features: - pla - paid - paid_sitelinks - organic_expanded_sitelinks - organic_sitelinks - organic top_url_position: 1 top_url: nike.com schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: site: type: string domain: type: string clicks: type: number traffic_share: type: number serp_features: type: string top_url_position: type: integer top_url: type: string tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/search/serp-players-aggregated source: https://github.com/AIsa-team/aisa-proxy /similarweb/search/landing-pages: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(0.1 x rows); rows capped at 20 credit_rate: 0.1 / row (max 20 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 0.1 credit/row; at most 20 rows are billed cost_tier: med example: 20 rows = 2 credits ($0.20); limit=5 = 1 credit ($0.10) summary: Landing Pages description: Landing Pages. Response follows the SimilarWeb v5 envelope (meta + data). operationId: get_similarweb_landing_pages parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: start_date in: query required: true description: Start month, format YYYY-MM. schema: type: string - name: end_date in: query required: true description: End month, format YYYY-MM. schema: type: string - name: granularity in: query required: false description: 'Time granularity. Allowed: monthly.' schema: type: string enum: - monthly - name: limit in: query required: true description: Number of rows to return; max 20, billed as 20 if exceeded. schema: type: integer default: 20 maximum: 20 - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww - name: web_source in: query required: false description: 'Traffic source device split. Allowed: desktop, mobile_web, total.' schema: type: string enum: - desktop - mobile_web - total - name: main_domain_only in: query required: false description: Restrict to the main domain only (true/false). schema: type: boolean - name: offset in: query required: false description: Row offset for pagination. schema: type: integer - name: traffic_source in: query required: false description: Traffic-source filter. schema: type: string responses: '200': description: SimilarWeb v5 envelope (meta + data). content: application/json: example: meta: query: limit: 5 offset: 0 asc: null sort: null request: traffic_source: organic format: json domain: nike.com granularity: monthly country: us start_date: '2026-06-01' end_date: '2026-06-30' web_source: total status: success last_updated: '2026-07-31' data: - url: nike.com clicks: 347144.3535507277 traffic_share: 0.07918893200800411 desktop_share: 0.8394896572520231 mobile_share: 0.16051034274797696 keywords: 749 top_keyword: nike serp_features: - organic - local_pack - related_questions spend: null ads: null schema: type: object properties: meta: $ref: '#/components/schemas/SimilarWebMeta' data: type: array items: type: object properties: url: type: string clicks: type: number traffic_share: type: number desktop_share: type: number mobile_share: type: number keywords: type: integer top_keyword: type: string serp_features: type: string spend: type: string ads: type: string tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/search/landing-pages source: https://github.com/AIsa-team/aisa-proxy /similarweb/website-traffic-snapshot: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 1 x metrics x periods credit_rate: 1 credit / (metric x month) cost_drivers: - param: metrics effect: number of metrics requested - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 metric + 1 month) = 1 credit ($0.10); cost grows with metrics and periods. summary: Website Traffic Snapshot description: 'Latest-month traffic snapshot for a domain: visits plus core engagement metrics (average visit duration, bounce rate, pages per visit) in a single object. The most recent available month is selected automatically and echoed in meta.start_date / meta.end_date.' operationId: get_similarweb_website_traffic_snapshot parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww responses: '200': description: SimilarWeb traffic response (meta + data). data is a single object for the latest available month. content: application/json: schema: type: object properties: meta: type: object properties: country: type: string end_date: type: string granularity: type: string request_id: type: string retrieved_at: type: string source: type: string start_date: type: string data: type: object properties: domain: type: string metrics: type: object properties: average_visit_duration: type: number bounce_rate: type: number pages_per_visit: type: number visits: type: number month: type: string example: data: domain: cnn.com metrics: average_visit_duration: 186.18602691805518 bounce_rate: 0.6533879990143767 pages_per_visit: 1.9618751425218268 visits: 227227320.82816133 month: 2026-07 meta: country: ww end_date: 2026-07 granularity: monthly request_id: imc_03ff6814856076c42c01a8ea4fd5d2a2d8b0629843037bdb907f883203c4ce5f retrieved_at: '2026-08-27T14:47:55.963779366Z' source: similarweb start_date: 2026-07 tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website-traffic-snapshot source: https://github.com/AIsa-team/aisa-proxy /similarweb/website-traffic-trend: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = 1 x metrics x periods credit_rate: 1 credit / (metric x month) cost_drivers: - param: metrics effect: number of metrics requested - param: periods effect: number of months in the date window cost_tier: med example: minimal (1 metric + 1 month) = 1 credit ($0.10); cost grows with metrics and periods. summary: Website Traffic Trend description: Monthly traffic time series for a domain over the recent available window (data.points, one entry per month). The window is selected automatically and echoed in meta.start_date / meta.end_date. operationId: get_similarweb_website_traffic_trend parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string - name: country in: query required: false description: 'Two-letter country code. Allowed: us, ww. Default: ww. Coverage is limited to ww and us on the current plan.' schema: type: string enum: - us - ww default: ww responses: '200': description: SimilarWeb traffic response (meta + data). data.points is an array of monthly data points. content: application/json: schema: type: object properties: meta: type: object properties: country: type: string end_date: type: string granularity: type: string request_id: type: string retrieved_at: type: string source: type: string start_date: type: string data: type: object properties: domain: type: string metrics: type: array items: type: string points: type: array items: type: object properties: month: type: string values: type: object properties: visits: type: number example: data: domain: cnn.com metrics: - visits points: - month: 2026-02 values: visits: 281819265.12642866 - month: 2026-03 values: visits: 331983472.9258732 - month: 2026-04 values: visits: 297093461.6820024 - month: 2026-05 values: visits: 233813785.58586735 - month: 2026-06 values: visits: 223877755.99760738 - month: 2026-07 values: visits: 227227320.82816133 meta: country: ww end_date: 2026-07 granularity: monthly request_id: imc_23295fabad90ffc413b20f39065b623cdd86946787ddbda5fe1270c7842ca2dc retrieved_at: '2026-08-27T14:47:56.413728046Z' source: similarweb start_date: 2026-02 tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website-traffic-trend source: https://github.com/AIsa-team/aisa-proxy /similarweb/website-top-geographies: get: x-aisa-pricing: model: per_credit currency: USD credit_price_usd: 0.1 credit_formula: credits = ceil(3 x rows); rows capped at 10 credit_rate: 3 / row (max 10 rows) cost_drivers: - param: limit effect: charge scales with rows returned at 3 credit/row; at most 10 rows are billed cost_tier: high example: 10 rows = 30 credits ($3.00); limit=5 = 15 credits ($1.50) summary: Website Top Geographies description: 'Top countries by share of a domain''s traffic for the latest available month (data.countries, up to 10 rows with country_code, country_name, share and visits). Geography coverage is worldwide (ww) and fixed: a country parameter is not accepted for this endpoint.' operationId: get_similarweb_website_top_geographies parameters: - name: domain in: query required: true description: Target domain, e.g. example.com. schema: type: string responses: '200': description: SimilarWeb traffic response (meta + data). data.countries is ranked by traffic share (highest first). content: application/json: schema: type: object properties: meta: type: object properties: country: type: string end_date: type: string granularity: type: string request_id: type: string retrieved_at: type: string source: type: string start_date: type: string data: type: object properties: countries: type: array items: type: object properties: country_code: type: string country_name: type: string rank: type: integer nullable: true share: type: number visits: type: number example: data: countries: - country_code: us country_name: United States rank: null share: 0.8135986038373749 visits: 184871830.97664917 - country_code: ca country_name: Canada rank: null share: 0.1250244855835728 visits: 28408978.896636344 - country_code: gb country_name: United Kingdom rank: null share: 0.0046361238147776184 visits: 1053453.9934433121 - country_code: in country_name: India rank: null share: 0.004525631464841616 visits: 1028347.1127957336 - country_code: au country_name: Australia rank: null share: 0.0038766416446363557 visits: 880878.8947080157 - country_code: za country_name: South Africa rank: null share: 0.0032450884260539874 visits: 737372.7488913544 - country_code: sg country_name: Singapore rank: null share: 0.0029357496450864123 visits: 667082.5264649267 - country_code: de country_name: Germany rank: null share: 0.002332122537702222 visits: 529921.9560768788 - country_code: nl country_name: Netherlands rank: null share: 0.0022503248115619393 visits: 511335.2779164732 - country_code: nz country_name: New Zealand rank: null share: 0.002059521596153513 visits: 467979.5744744864 meta: country: ww end_date: 2026-07 granularity: monthly request_id: imc_7d699adfa9e84a0e867521b2d071c2bb35f887a6f6b7c1e5d95067a1dfc2f2fa retrieved_at: '2026-08-27T14:47:22.508241524Z' source: similarweb start_date: 2026-07 tags: - Market Intelligence x-x402: path: /apis/v2/similarweb/website-top-geographies source: https://github.com/AIsa-team/aisa-proxy /tavily/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0096 observed_usd: min: 1.0e-06 p50: 0.0096 p95: 0.016 max: 0.016 cost_drivers: - param: results / pages effect: charge scales with number of results (search) or pages (crawl/extract) returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Web & News Search summary: Execute a search query using Tavily Search. operationId: post_tavily_search description: 'Search the web and get back ranked results with the page text already extracted, so there is no second call to fetch content. `query` is required. Returns `results[]` with `url`, `title`, `content` (the extracted excerpt), `score` and optionally `raw_content`, alongside `query`, `images`, `response_time` and `request_id`; set `include_answer` to also get a one-paragraph `answer`. Filter with `topic` (general/news/finance), `time_range` or explicit `start_date`/`end_date`, and trade cost against depth with `search_depth`. Measured at roughly 6 seconds for 2 results. This is the default choice for open-web research, and the only search here that returns ranked results and page text in one call. Reach past it when: you already know the URLs — `post_tavily_extract` is cheaper and exact; the query is a description rather than keywords — `post_exa_search` matches on meaning; you want a written answer rather than a list to iterate — `post_perplexity_sonar`; you want peer-reviewed papers — `post_scholar_search_scholar`.' requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: The search query to execute with Tavily. example: Who is Leo Messi? search_depth: type: string enum: - advanced - basic - fast - ultra-fast default: basic description: Controls the latency vs. relevance tradeoff. advanced gives the highest relevance with higher latency and cost; basic is balanced; fast and ultra-fast optimize for lower latency. chunks_per_source: type: integer default: 3 description: Maximum number of relevant chunks returned per source. minimum: 1 maximum: 3 max_results: type: integer default: 5 description: Maximum number of search results to return. minimum: 0 maximum: 20 topic: type: string enum: - general - news - finance default: general description: Category of the search. time_range: type: string enum: - day - week - month - year - d - w - m - y description: Time range to filter results based on publish date. start_date: type: string format: date description: Return results after the specified start date. example: '2025-02-09' end_date: type: string format: date description: Return results before the specified end date. example: '2025-12-29' include_answer: oneOf: - type: boolean - type: string enum: - basic - advanced default: false description: Include an LLM-generated answer. true uses the default answer mode; basic or advanced selects the answer generation mode. include_raw_content: oneOf: - type: boolean - type: string enum: - markdown - text default: false description: Include cleaned and parsed content for each search result. true or markdown returns markdown; text returns plain text and may increase latency. include_images: type: boolean default: false description: Perform an image search and include results. include_image_descriptions: type: boolean default: false description: Add descriptive text for each image when include_images is true. safe_search: type: boolean default: false description: Filter out adult or unsafe content from search results. Enterprise only; not supported when search_depth is fast or ultra-fast. include_favicon: type: boolean default: false description: Include the favicon URL for each result. include_domains: type: array items: type: string description: List of domains to specifically include in the search results. maxItems: 300 exclude_domains: type: array items: type: string description: List of domains to specifically exclude from the search results. maxItems: 150 country: type: string description: Boost search results from a specific country. Available only when topic is general. enum: - afghanistan - albania - algeria - andorra - angola - argentina - armenia - australia - austria - azerbaijan - bahamas - bahrain - bangladesh - barbados - belarus - belgium - belize - benin - bhutan - bolivia - bosnia and herzegovina - botswana - brazil - brunei - bulgaria - burkina faso - burundi - cambodia - cameroon - canada - cape verde - central african republic - chad - chile - china - colombia - comoros - congo - costa rica - croatia - cuba - cyprus - czech republic - denmark - djibouti - dominican republic - ecuador - egypt - el salvador - equatorial guinea - eritrea - estonia - ethiopia - fiji - finland - france - gabon - gambia - georgia - germany - ghana - greece - guatemala - guinea - haiti - honduras - hungary - iceland - india - indonesia - iran - iraq - ireland - israel - italy - jamaica - japan - jordan - kazakhstan - kenya - kuwait - kyrgyzstan - latvia - lebanon - lesotho - liberia - libya - liechtenstein - lithuania - luxembourg - madagascar - malawi - malaysia - maldives - mali - malta - mauritania - mauritius - mexico - moldova - monaco - mongolia - montenegro - morocco - mozambique - myanmar - namibia - nepal - netherlands - new zealand - nicaragua - niger - nigeria - north korea - north macedonia - norway - oman - pakistan - panama - papua new guinea - paraguay - peru - philippines - poland - portugal - qatar - romania - russia - rwanda - saudi arabia - senegal - serbia - singapore - slovakia - slovenia - somalia - south africa - south korea - south sudan - spain - sri lanka - sudan - sweden - switzerland - syria - taiwan - tajikistan - tanzania - thailand - togo - trinidad and tobago - tunisia - turkey - turkmenistan - uganda - ukraine - united arab emirates - united kingdom - united states - uruguay - uzbekistan - venezuela - vietnam - yemen - zambia - zimbabwe auto_parameters: type: boolean default: false description: Automatically configure search parameters based on query content. include_usage: type: boolean default: false description: Include credit usage information in the response. required: - query responses: '200': description: Search results returned successfully. content: application/json: schema: type: object properties: query: type: string description: The search query that was executed. answer: type: string description: A short LLM-generated answer. Present as null when include_answer is false or no answer is generated. nullable: true images: type: array items: type: object properties: url: type: string description: Image URL. description: type: string description: Image description. results: type: array items: type: object properties: title: type: string description: Title of the search result. url: type: string description: URL of the search result. content: type: string description: Content snippet of the search result. score: type: number format: float description: Relevance score of the search result. favicon: type: string description: Favicon URL of the search result. nullable: true raw_content: type: string nullable: true description: Cleaned and parsed source content. Null unless include_raw_content is requested or no raw content is available. response_time: type: number format: float description: Time in seconds it took to complete the request. usage: type: object properties: credits: type: integer description: Credit usage details for the request. request_id: type: string description: Unique request identifier. x-x402: path: /apis/v2/tavily/search source: https://github.com/AIsa-team/aisa-proxy /tavily/extract: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0096 observed_usd: min: 0.008 p50: 0.0096 p95: 0.0096 max: 0.04 cost_drivers: - param: results / pages effect: charge scales with number of results (search) or pages (crawl/extract) returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Web & News Search summary: Extract web page content from specified URLs using Tavily Extract. operationId: post_tavily_extract description: Fetch clean, parsed content for URLs you already have — from a search result, a sitemap, or a user. `urls` is required and takes several at once. Returns `results[]` with `url`, `title`, `raw_content` and `images`, plus a `failed_results[]` array — **read that one**, because a page that could not be fetched is reported there rather than raising an error. Choose `format` (markdown or text) and `extract_depth`. Measured at about 1 second for one page. Use this instead of `post_tavily_search` whenever you can already name the pages; searching for pages you can name costs more and may not return them. For a long list that can wait, `post_firecrawl_batch_scrape` runs it as a background job. To discover the URLs of a whole site first, use `post_tavily_map`. requestBody: required: true content: application/json: schema: type: object properties: urls: oneOf: - type: string - type: array items: type: string description: The URL or URLs to extract content from. A single URL string and an array of URL strings are both accepted. example: - https://en.wikipedia.org/wiki/Artificial_intelligence query: type: string description: User intent for reranking extracted content chunks. chunks_per_source: type: integer default: 3 description: Maximum number of relevant chunks returned per source. Available only when query is provided. minimum: 1 maximum: 5 extract_depth: type: string enum: - basic - advanced default: basic description: Depth of the extraction process. include_images: type: boolean default: false description: Include a list of images extracted from the URLs. include_favicon: type: boolean default: false description: Include the favicon URL for each result. format: type: string enum: - markdown - text default: markdown description: Format of the extracted web page content. timeout: type: number format: float description: 'Maximum time in seconds to wait for URL extraction. If omitted, default timeouts depend on extract_depth: 10 seconds for basic and 30 seconds for advanced.' minimum: 1 maximum: 60 include_usage: type: boolean default: false description: Include credit usage information in the response. required: - urls responses: '200': description: Extraction results returned successfully. content: application/json: schema: type: object properties: results: type: array items: type: object properties: url: type: string description: URL of the extracted content. title: type: string description: Title of the extracted page. raw_content: type: string description: Extracted raw content from the URL. images: type: array items: type: string description: Images extracted from the URL when include_images is true. favicon: type: string description: Favicon URL of the extracted content. nullable: true failed_results: type: array items: type: string description: List of URLs that could not be processed. response_time: type: number format: float description: Time in seconds it took to complete the request. usage: type: object properties: credits: type: integer description: Credit usage details for the request. request_id: type: string description: Unique request identifier. x-x402: path: /apis/v2/tavily/extract source: https://github.com/AIsa-team/aisa-proxy /tavily/crawl: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0096 observed_usd: min: 0.008 p50: 0.0096 p95: 0.016 max: 0.024 cost_drivers: - param: results / pages effect: charge scales with number of results (search) or pages (crawl/extract) returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Web & News Search summary: Graph-based website traversal tool using Tavily Crawl. operationId: post_tavily_crawl description: 'Walk a site from a root `url` and return the content of the pages it finds. Steer it with natural-language `instructions` plus regex path and domain filters, and bound it with `max_depth`, `max_breadth` and `limit`. Returns `base_url` and `results[]` with `url` and `raw_content`. Measured at about 4.5 seconds for a 3-page limit; cost and time grow with the bounds you set, so set them. Use it for broad coverage of one site — documentation, a catalogue, a competitor''s blog. It answers synchronously, which `post_firecrawl_crawl` does not: that one runs as a background job and suits crawls too large to wait on. For a handful of known pages `post_tavily_extract` is far cheaper; to size a site before paying to crawl it, run `post_tavily_map` first.' requestBody: required: true content: application/json: schema: type: object properties: url: type: string description: The root URL to begin the crawl. example: docs.tavily.com instructions: type: string description: Natural language instructions for the crawler. chunks_per_source: type: integer default: 3 description: Maximum number of relevant chunks returned per source. minimum: 1 maximum: 5 max_depth: type: integer default: 1 description: Max depth of the crawl. minimum: 1 maximum: 5 max_breadth: type: integer default: 20 description: Max number of links to follow per level of the tree. minimum: 1 maximum: 500 limit: type: integer default: 50 description: Total number of links the crawler will process before stopping. minimum: 1 select_paths: type: array items: type: string description: Regex patterns to select only URLs with specific path patterns. select_domains: type: array items: type: string description: Regex patterns to select crawling to specific domains or subdomains. exclude_paths: type: array items: type: string description: Regex patterns to exclude URLs with specific path patterns. exclude_domains: type: array items: type: string description: Regex patterns to exclude specific domains or subdomains from crawling. allow_external: type: boolean default: true description: Include external domain links in the final results list. include_images: type: boolean default: false description: Include images in the crawl results. extract_depth: type: string enum: - basic - advanced default: basic description: Depth of the extraction process. format: type: string enum: - markdown - text default: markdown description: Format of the extracted web page content. include_favicon: type: boolean default: false description: Include the favicon URL for each result. timeout: type: number format: float default: 150 description: Maximum time in seconds to wait for the crawl operation. minimum: 10 maximum: 150 include_usage: type: boolean default: false description: Include credit usage information in the response. required: - url responses: '200': description: Crawl results returned successfully. content: application/json: schema: type: object properties: base_url: type: string description: The base URL that was crawled. results: type: array items: type: object properties: url: type: string description: URL of the crawled page. raw_content: type: string description: Extracted raw content from the page. favicon: type: string description: Favicon URL of the crawled page. response_time: type: number format: float description: Time in seconds it took to complete the request. usage: type: object properties: credits: type: integer description: Credit usage details for the request. request_id: type: string description: Unique request identifier. x-x402: path: /apis/v2/tavily/crawl source: https://github.com/AIsa-team/aisa-proxy /tavily/map: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0096 observed_usd: min: 0.008 p50: 0.0096 p95: 0.016 max: 0.064 cost_drivers: - param: results / pages effect: charge scales with number of results (search) or pages (crawl/extract) returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Web & News Search summary: Generate comprehensive site maps using Tavily Map. operationId: post_tavily_map description: 'List a site''s URLs from a root `url` without fetching any page content. Steer it with natural-language `instructions` and regex `select_paths` / `exclude_paths` / `select_domains` filters. Returns `base_url` and `results` — **a flat array of URL strings, not objects** — with `response_time` and `request_id`. Fast and cheap: measured at about 1.5 seconds. Use it to size a site before committing to a crawl, then fetch only the parts that matter with `post_tavily_extract`. When you want the content rather than the shape, `post_tavily_crawl` does both in one call.' requestBody: required: true content: application/json: schema: type: object properties: url: type: string description: The root URL to begin the mapping. example: docs.tavily.com instructions: type: string description: Natural language instructions for the crawler. max_depth: type: integer default: 1 description: Max depth of the mapping. minimum: 1 maximum: 5 max_breadth: type: integer default: 20 description: Max number of links to follow per level of the tree. minimum: 1 maximum: 500 limit: type: integer default: 50 description: Total number of links the crawler will process before stopping. minimum: 1 select_paths: type: array items: type: string description: Regex patterns to select only URLs with specific path patterns. select_domains: type: array items: type: string description: Regex patterns to select crawling to specific domains or subdomains. exclude_paths: type: array items: type: string description: Regex patterns to exclude URLs with specific path patterns. exclude_domains: type: array items: type: string description: Regex patterns to exclude specific domains or subdomains from mapping. allow_external: type: boolean default: true description: Include external domain links in the final results list. timeout: type: number format: float default: 150 description: Maximum time in seconds to wait for the map operation. minimum: 10 maximum: 150 include_usage: type: boolean default: false description: Include credit usage information in the response. required: - url responses: '200': description: Map results returned successfully. content: application/json: schema: type: object properties: base_url: type: string description: The base URL that was mapped. results: type: array items: type: string description: URLs discovered during the mapping. response_time: type: number format: float description: Time in seconds it took to complete the request. usage: type: object properties: credits: type: integer description: Credit usage details for the request. request_id: type: string description: Unique request identifier. x-x402: path: /apis/v2/tavily/map source: https://github.com/AIsa-team/aisa-proxy /twitter/auth_twitter: post: x-aisa-pricing: model: per_request currency: USD price_usd: 1.0e-06 cost_tier: low summary: Link an X/Twitter account (start OAuth) description: |- Start the OAuth flow that links a user's X/Twitter account to the AIsa API key on the request. Call this once per source user. AIsa returns an authorization URL — the user opens it in a browser, approves the requested scopes, and X redirects back to AIsa's fixed callback. AIsa stores the resulting session against your API key, and every subsequent Twitter write call (e.g., `POST /twitter/follow_twitter`) uses that session automatically. The returned `auth_url` is short-lived; generate a fresh one every time the user needs to (re-)link. operationId: authTwitterUser security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: aisa_api_key: type: string description: 'Your AIsa API key (the `sk-aisa-...` value). REQUIRED in the JSON body in addition to the `Authorization: Bearer` header — the OAuth session is bound to this key. Sending only the header returns HTTP 422; sending only the body returns 404.' scopes: type: array items: type: string description: 'Optional list of X OAuth 2.0 scopes to request. Defaults to the set required by AIsa''s Twitter write endpoints: `follows.write`, `tweet.read`, `users.read`, `tweet.write`, `like.write`, `dm.read`, `dm.write`.' example: - follows.write - tweet.read - users.read required: - aisa_api_key example: aisa_api_key: sk-aisa-... scopes: - follows.write - tweet.read - users.read responses: '200': description: Authorization URL generated. content: application/json: schema: type: object required: - auth_url - state properties: auth_url: type: string format: uri description: Short-lived X OAuth authorization URL. Open it in a browser so the source user can approve the requested scopes. state: type: string description: Opaque CSRF state token that AIsa will validate when X redirects back to its callback. Store it client-side if you need to correlate the flow. expires_at: type: string format: date-time description: When the `auth_url` expires. Request a new one if the user hasn't completed the flow before this time. example: auth_url: https://twitter.com/i/oauth2/authorize?response_type=code&client_id=AIsa&redirect_uri=https%3A%2F%2Fapi.aisa.one%2Fapis%2Fv1%2Ftwitter%2Foauth_callback&scope=follows.write%20tweet.read%20users.read&state=0c2...d1f&code_challenge=...&code_challenge_method=S256 state: 0c2ad1f... expires_at: '2026-04-18T07:00:00Z' '400': description: Invalid `scopes` list — contains an unsupported scope. '401': description: Missing or invalid AIsa API key. '429': description: Rate limit hit. '500': description: Internal error generating the OAuth URL. tags: - Twitter / X x-x402: path: /apis/v2/twitter/auth_twitter source: https://github.com/AIsa-team/aisa-proxy /twitter/unlike_twitter: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.01 cost_tier: low summary: Unlike a tweet description: |- Remove the source user's like from a tweet. Mirrors the [official X v2 `DELETE /2/users/{id}/likes/{tweet_id}` endpoint](https://docs.x.com/x-api/users/unlike-post), routed through the AIsa gateway. Uses POST (not DELETE) for consistency with the other AIsa Twitter write actions. **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the account once via `POST /apis/v1/twitter/auth_twitter`. **Scopes.** The underlying X session must hold `like.write`, `tweet.read`, and `users.read`. Unliking a tweet the source user has not liked is a no-op and still returns `200` with `liked: false`. operationId: unlikeTwitter security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - tweet_id properties: tweet_id: type: string description: Numeric ID of the tweet to unlike. Must match X's regex `^[0-9]{1,19}$`. pattern: ^[0-9]{1,19}$ example: '1346889436626259968' examples: unlike_tweet: summary: Unlike tweet 1346889436626259968 value: tweet_id: '1346889436626259968' responses: '200': description: Unlike succeeded (or the source user hadn't liked the tweet to begin with). content: application/json: schema: type: object properties: data: type: object properties: liked: type: boolean description: '`false` once the like has been removed.' example: data: liked: false '400': description: Invalid request — missing or malformed `tweet_id`. '401': description: Missing or invalid AIsa API key. '403': description: OAuth session missing, expired, or lacking `like.write`. Re-authorize via `POST /apis/v1/twitter/auth_twitter`. '404': description: Tweet not found or not visible to the source user. '429': description: Rate limit hit. '500': description: Internal error. '502': description: Upstream X API unreachable. Safe to retry with exponential backoff. tags: - Twitter / X x-x402: path: /apis/v2/twitter/unlike_twitter source: https://github.com/AIsa-team/aisa-proxy /twitter/like_twitter: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.015 cost_tier: med summary: Like a tweet description: |- Like a tweet on behalf of the authenticated source user. Mirrors the [official X v2 `POST /2/users/{id}/likes` endpoint](https://docs.x.com/x-api/users/like-post), routed through the AIsa gateway. **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the account once via `POST /apis/v1/twitter/auth_twitter`. **Scopes.** The underlying X session must hold `like.write`, `tweet.read`, and `users.read`. Liking a tweet already liked is a no-op and still returns `200` with `liked: true`. operationId: likeTwitter security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - tweet_id properties: tweet_id: type: string description: Numeric ID of the tweet to like. Must match X's regex `^[0-9]{1,19}$`. pattern: ^[0-9]{1,19}$ example: '1346889436626259968' examples: like_tweet: summary: Like tweet 1346889436626259968 value: tweet_id: '1346889436626259968' responses: '200': description: Like succeeded (or was already in place). content: application/json: schema: type: object properties: data: type: object properties: liked: type: boolean description: '`true` once the source user has liked the target tweet.' example: data: liked: true '400': description: Invalid request — missing or malformed `tweet_id`. '401': description: Missing or invalid AIsa API key. '403': description: OAuth session missing, expired, or lacking `like.write`. Re-authorize via `POST /apis/v1/twitter/auth_twitter`. '404': description: Tweet not found or not visible to the source user. '429': description: Rate limit hit — either your AIsa key's RPM cap or the upstream X rate limit. '500': description: Internal error. '502': description: Upstream X API unreachable. Safe to retry with exponential backoff. tags: - Twitter / X x-x402: path: /apis/v2/twitter/like_twitter source: https://github.com/AIsa-team/aisa-proxy /twitter/post_twitter: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.01 observed_usd: min: 0.01 p50: 0.01 p95: 0.01 max: 0.2 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Post or edit a tweet description: |- Publish a new tweet on behalf of the authenticated source user, or edit an existing tweet. Mirrors the [official X v2 `POST /2/tweets` endpoint](https://docs.x.com/x-api/posts/create-post), routed through the AIsa gateway. **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the account once via `POST /apis/v1/twitter/auth_twitter`. **Scopes.** The underlying X session must hold `tweet.read`, `tweet.write`, and `users.read`. **Mutually exclusive fields.** `media`, `poll`, `quote_tweet_id`, and `card_uri` cannot be combined in the same request. At most one of them may be set. operationId: postTwitter security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: text: type: string description: The content of the tweet. Optional when posting media, a poll, or a quote tweet; required otherwise. example: Hello from AIsa — shipping agent-friendly Twitter APIs. reply: type: object description: Post as a reply to another tweet. required: - in_reply_to_tweet_id properties: in_reply_to_tweet_id: type: string description: Tweet ID being replied to. pattern: ^[0-9]{1,19}$ auto_populate_reply_metadata: type: boolean description: Auto-populate reply @-mentions from the original tweet. exclude_reply_user_ids: type: array items: type: string pattern: ^[0-9]{1,19}$ maxItems: 10 description: User IDs to exclude from reply auto-mentions (max 10). quote_tweet_id: type: string description: Tweet ID to quote. Mutually exclusive with `media`, `poll`, and `card_uri`. pattern: ^[0-9]{1,19}$ media: type: object description: Attach media. Mutually exclusive with `poll`, `quote_tweet_id`, and `card_uri`. required: - media_ids properties: media_ids: type: array items: type: string minItems: 1 maxItems: 4 description: 1–4 media IDs from the X media-upload API. tagged_user_ids: type: array items: type: string pattern: ^[0-9]{1,19}$ maxItems: 10 description: User IDs tagged in the media (max 10). poll: type: object description: Attach a poll. Mutually exclusive with `media`, `quote_tweet_id`, and `card_uri`. required: - options - duration_minutes properties: options: type: array items: type: string maxLength: 25 minItems: 2 maxItems: 4 description: 2–4 poll choices, each 1–25 characters. duration_minutes: type: integer minimum: 5 maximum: 10080 description: Poll duration in minutes (5–10080, i.e. up to 7 days). reply_settings: type: string enum: - following - mentionedUsers - subscribers - verified card_uri: type: string description: Card URI. Mutually exclusive with `media`, `poll`, `quote_tweet_id`, and `direct_message_deep_link`. direct_message_deep_link: type: string description: Deep link that takes the conversation into a private DM. geo: type: object description: Attach a place to the tweet. properties: place_id: type: string description: X place ID. reply_settings: type: string enum: - following - mentionedUsers - subscribers - verified description: Who is allowed to reply. for_super_followers_only: type: boolean default: false description: Only visible to super followers. nullcast: type: boolean default: false description: Nullcast (promoted-only) tweet — not shown in the public timeline or to followers. paid_partnership: type: boolean description: Marks the tweet as a paid partnership. made_with_ai: type: boolean description: Flags the tweet as containing AI-generated media. community_id: type: string pattern: ^[0-9]{1,19}$ description: Post into the specified community. share_with_followers: type: boolean default: false description: Also share the community post with your followers. edit_options: type: object description: Edit an existing tweet instead of creating a new one (subject to X's edit window). required: - previous_post_id properties: previous_post_id: type: string pattern: ^[0-9]{1,19}$ description: Tweet ID to edit. examples: simple_text: summary: Plain text tweet value: text: Hello, World! reply: summary: Reply to a tweet value: text: Totally agree 👌 reply: in_reply_to_tweet_id: '1234567890123456789' auto_populate_reply_metadata: true with_poll: summary: Tweet with a poll value: text: 'Pick your favorite:' poll: options: - Option A - Option B - Option C duration_minutes: 60 with_media: summary: Tweet with media value: text: Ship log 📸 media: media_ids: - '1146654567674912769' tagged_user_ids: - '2244994945' quote: summary: Quote tweet value: text: 'Worth reading:' quote_tweet_id: '1234567890123456789' edit: summary: Edit an existing tweet value: text: Updated tweet content (typo fixed). edit_options: previous_post_id: '1234567890123456789' responses: '201': description: Tweet created (or edited) successfully. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^[0-9]{1,19}$ description: ID of the newly created or edited tweet. text: type: string description: Final text of the tweet as stored by X. example: data: id: '1346889436626259968' text: Hello, World! '400': description: Invalid request — violated a mutual-exclusivity rule, missing required field, or text too long. '401': description: Missing or invalid AIsa API key. '403': description: OAuth session missing, expired, or lacking `tweet.write`. Re-authorize via `POST /apis/v1/twitter/auth_twitter`. '404': description: Referenced tweet (reply, quote, or edit target) not found. '409': description: Conflict — e.g., duplicate tweet content or edit outside the allowed window. '429': description: Rate limit hit. '500': description: Internal error. '502': description: Upstream X API unreachable. tags: - Twitter / X x-x402: path: /apis/v2/twitter/post_twitter source: https://github.com/AIsa-team/aisa-proxy /twitter/unfollow_twitter: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.01 cost_tier: low summary: Unfollow a user on X/Twitter description: |- Make the authenticated source user unfollow the given target user on X/Twitter. Mirrors the [official X v2 `DELETE /2/users/{source_user_id}/following/{target_user_id}` endpoint](https://docs.x.com/x-api/users/unfollow-user), routed through the AIsa gateway. Uses POST (not DELETE) for consistency with the other AIsa Twitter write actions. **Authentication.** Requires an OAuth session for the source user, attached to your AIsa API key. Link the account once via `POST /apis/v1/twitter/auth_twitter`. **Scopes.** The underlying X session must hold `follows.write`, `tweet.read`, and `users.read`. Unfollowing a user you don't currently follow is a no-op and still returns `200` with `following: false`. operationId: unfollowTwitterUser security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - target_user_id properties: target_user_id: type: string description: Numeric ID of the X/Twitter user to unfollow. Must match the X regex `^[0-9]{1,19}$`. pattern: ^[0-9]{1,19}$ example: '2244994945' examples: unfollow_user: summary: Unfollow @TwitterDev (id 2244994945) value: target_user_id: '2244994945' responses: '200': description: Unfollow succeeded (or the source user wasn't following the target to begin with). content: application/json: schema: type: object properties: data: type: object properties: following: type: boolean description: '`false` once the source user no longer follows the target user.' example: data: following: false '400': description: Invalid request — missing or malformed `target_user_id`. '401': description: Missing or invalid AIsa API key. '403': description: OAuth session missing, expired, or lacking the `follows.write` scope. Re-authorize via `POST /apis/v1/twitter/auth_twitter`. '429': description: Rate limit hit — either your AIsa key's RPM cap or the upstream X rate limit. '500': description: Internal error. '502': description: Upstream X API unreachable or returned an error. Safe to retry with exponential backoff. tags: - Twitter / X x-x402: path: /apis/v2/twitter/unfollow_twitter source: https://github.com/AIsa-team/aisa-proxy /twitter/follow_twitter: post: x-aisa-pricing: model: per_request currency: USD price_usd: 0.015 cost_tier: med summary: Follow a user on X/Twitter description: |- Make the authenticated source user follow the given target user on X/Twitter. Mirrors the [official X v2 `POST /2/users/{id}/following` endpoint](https://docs.x.com/x-api/users/follow-user), routed through the AIsa gateway. **Authentication.** This is a write action that requires an OAuth session for the source user, attached to your AIsa API key. Link your X account once by calling `POST /apis/v1/twitter/auth_twitter` — AIsa then uses that session automatically for every write request sent with your key. **Scopes.** The underlying X session must hold `follows.write`, `tweet.read`, and `users.read`. operationId: followTwitterUser security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - target_user_id properties: target_user_id: type: string description: Numeric ID of the X/Twitter user to follow. Must match the X regex `^[0-9]{1,19}$`. pattern: ^[0-9]{1,19}$ example: '6253282' examples: follow_user: summary: Follow @TwitterDev (id 2244994945) value: target_user_id: '2244994945' responses: '200': description: Follow succeeded (or was already in place). content: application/json: schema: type: object properties: data: type: object properties: following: type: boolean description: '`true` when the source user now follows the target user.' pending_follow: type: boolean description: '`true` when a follow request has been sent to a protected account and is awaiting approval.' example: data: following: true pending_follow: false '400': description: Invalid request — missing or malformed `target_user_id`. '401': description: Missing or invalid AIsa API key. '403': description: OAuth session missing, expired, or lacking the `follows.write` scope. Re-authorize from the dashboard. '429': description: Rate limit hit — either your AIsa key's RPM cap or the upstream X rate limit. '500': description: Internal error. '502': description: Upstream X API unreachable or returned an error. Safe to retry with exponential backoff. tags: - Twitter / X x-x402: path: /apis/v2/twitter/follow_twitter source: https://github.com/AIsa-team/aisa-proxy /twitter/community/info: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0022 observed_usd: min: 0.0002 p50: 0.0002 p95: 0.0022 max: 0.0022 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Community Info By Id operationId: get_twitter_community_info description: Get metadata for an X Community by its numeric community ID — name, description, member count, and access rules. Use this to qualify a community before pulling its members or posts. Returns the object under `community_info`. To discover communities by topic, search their posts with `get_twitter_community_tweets_all`. parameters: - name: community_id in: query required: true schema: type: string description: ID of the community responses: '200': description: Community info response content: application/json: schema: $ref: '#/components/schemas/CommunityInfoResponse' x-x402: path: /apis/v2/twitter/community/info source: https://github.com/AIsa-team/aisa-proxy /twitter/community/members: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.0022 max: 0.0072 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Community Members operationId: get_twitter_community_members description: List the members of an X Community, cursor-paginated. Use this to map who participates in a topic-specific group — usually a higher-signal audience than general followers, because membership is opt-in. Returns full user objects. For the subset who moderate it, use `get_twitter_community_moderators`. parameters: - name: community_id in: query required: true schema: type: string description: ID of the community - name: cursor in: query required: false schema: type: string description: Cursor for pagination responses: '200': description: Community members response content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/User' has_next_page: type: boolean next_cursor: type: string has_next: type: boolean status: type: string enum: - success - error msg: type: string x-x402: path: /apis/v2/twitter/community/members source: https://github.com/AIsa-team/aisa-proxy /twitter/community/moderators: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.0072 max: 0.0072 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Community Moderators operationId: get_twitter_community_moderators description: List the moderators of an X Community, cursor-paginated. Use this to identify the people who set the agenda in a community — the highest-leverage contacts for outreach or partnership. Returns full user objects. For the full membership use `get_twitter_community_members`. parameters: - name: community_id in: query required: true schema: type: string description: ID of the community - name: cursor in: query required: false schema: type: string description: Cursor for pagination responses: '200': description: Community moderators response content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/User' has_next_page: type: boolean next_cursor: type: string has_next: type: boolean status: type: string enum: - success - error msg: type: string x-x402: path: /apis/v2/twitter/community/moderators source: https://github.com/AIsa-team/aisa-proxy /twitter/community/tweets: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.0022 max: 0.006 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Community Tweets operationId: get_twitter_community_tweets description: Get posts published inside one specific X Community, cursor-paginated. Use this to read what a known community is actually discussing. Returns full tweet objects with engagement counts. If you do not know which community to look at, search across all of them with `get_twitter_community_tweets_all`. parameters: - name: community_id in: query required: true schema: type: string description: ID of the community - name: cursor in: query required: false schema: type: string description: Cursor for pagination responses: '200': description: Community tweets response content: application/json: schema: type: object properties: tweets: type: array items: $ref: '#/components/schemas/Tweet' has_next_page: type: boolean next_cursor: type: string has_next: type: boolean status: type: string enum: - success - error msg: type: string x-x402: path: /apis/v2/twitter/community/tweets source: https://github.com/AIsa-team/aisa-proxy /twitter/community/get_tweets_from_all_community: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.0022 max: 0.006 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Search Tweets From All Communities operationId: get_twitter_community_tweets_all description: Search posts across all X Communities by keyword, sorted by Latest (default) or Top, cursor-paginated. Use this to find topic-specific discussion happening inside communities rather than on the public timeline — signal density is usually higher and noise lower. Returns full tweet objects. Once you identify a community worth following, use `get_twitter_community_tweets` to read it directly, or `get_twitter_community_info` for its metadata. For public-timeline search use `get_twitter_tweet_advanced_search`. parameters: - name: query in: query required: true schema: type: string description: Search query (e.g., keyword) - name: queryType in: query required: true schema: type: string enum: - Latest - Top default: Latest description: Query type (Latest or Top) - name: cursor in: query required: false schema: type: string description: Cursor for pagination responses: '200': description: Tweets response content: application/json: schema: type: object properties: tweets: type: array items: $ref: '#/components/schemas/Tweet' has_next_page: type: boolean next_cursor: type: string x-x402: path: /apis/v2/twitter/community/get_tweets_from_all_community source: https://github.com/AIsa-team/aisa-proxy /twitter/list/tweets_timeline: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0036 observed_usd: min: 0.0015 p50: 0.0036 p95: 0.0036 max: 0.0036 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get List Tweet Timeline operationId: get_twitter_list_tweets_timeline description: Get the tweet timeline of an X List by `listId`, up to 20 per page, cursor-paginated. Use this to monitor a hand-curated set of accounts as a single feed — Lists are the cheapest way to track a fixed cohort (competitors, analysts, a beat) without polling each account. Returns tweets with `has_next_page` and `next_cursor`. To see who is in the List use `get_twitter_list_members`. parameters: - name: listId in: query required: true schema: type: string description: The list ID to get tweets from. e.g. 1846987139428634858 - name: cursor in: query required: false schema: type: string description: Cursor for paginating through results. Leave empty for the first page. responses: '200': description: List tweet timeline response content: application/json: schema: $ref: '#/components/schemas/ListTweetsTimelineResponse' x-x402: path: /apis/v2/twitter/list/tweets_timeline source: https://github.com/AIsa-team/aisa-proxy /twitter/list/followers: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0022 observed_usd: min: 0.0015 p50: 0.0015 p95: 0.0022 max: 0.0022 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get List Followers operationId: get_twitter_list_followers description: List the accounts that subscribe to an X List, 20 per page, cursor-paginated. Use this to gauge how much attention a curated list attracts and who cares about that topic. Returns full user objects under `followers`. For the accounts included in the List (not its subscribers) use `get_twitter_list_members`. parameters: - name: list_id in: query required: true schema: type: string description: ID of the list - name: cursor in: query required: false schema: type: string description: Cursor of the page responses: '200': description: List followers of the list content: application/json: schema: $ref: '#/components/schemas/TwitterListFollowersResponse' x-x402: path: /apis/v2/twitter/list/followers source: https://github.com/AIsa-team/aisa-proxy /twitter/list/members: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0022 observed_usd: min: 0.0015 p50: 0.0015 p95: 0.0022 max: 0.0022 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get List Members operationId: get_twitter_list_members description: List the accounts included in an X List, 20 per page, cursor-paginated. Use this to extract a ready-made, human-curated cohort — someone else has already done the filtering. Returns full user objects under `members`. To read what those accounts are posting as one feed, use `get_twitter_list_tweets_timeline`. For the List's subscribers use `get_twitter_list_followers`. parameters: - name: list_id in: query required: true schema: type: string description: ID of the list - name: cursor in: query required: false schema: type: string description: Cursor of the page responses: '200': description: List members response content: application/json: schema: $ref: '#/components/schemas/TwitterListMembersResponse' x-x402: path: /apis/v2/twitter/list/members source: https://github.com/AIsa-team/aisa-proxy /twitter/trends: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0022 observed_usd: min: 0.00015 p50: 0.0022 p95: 0.0022 max: 0.0022 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Trends operationId: get_twitter_trends description: Get the trending topics for a location, identified by its Yahoo WOEID (Where On Earth ID), with an optional `count` (default 30). Use this for a real-time read on what a specific market is talking about right now — useful for timing content or spotting emerging stories. Returns trend names and volumes under `trends`. Once you pick a trend, search its posts with `get_twitter_tweet_advanced_search`. parameters: - name: woeid in: query required: true schema: type: integer format: int64 description: 'The WOEID of the location. Example: 2418046.' - name: count in: query required: false schema: type: integer format: int64 default: 30 minimum: 30 description: The number of trends to return. Default is 30. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TrendsResponse' x-x402: path: /apis/v2/twitter/trends source: https://github.com/AIsa-team/aisa-proxy /twitter/spaces/detail: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.0022 cost_tier: low tags: - Twitter / X summary: Get Space Detail operationId: get_twitter_spaces_detail description: Get details of an X Space (live audio room) by its space ID — title, state, host, participants, and scheduling. Use this to check whether a Space is scheduled, live, or ended, and who is hosting, before deciding to reference or attend it. Returns the object under `data`. parameters: - name: space_id in: query required: true schema: type: string description: The ID of the space. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SpaceDetailResponse' x-x402: path: /apis/v2/twitter/spaces/detail source: https://github.com/AIsa-team/aisa-proxy /twitter/tweets: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.00015 p50: 0.0022 p95: 0.0111 max: 0.015 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Tweets by IDs operationId: get_twitter_tweets description: Fetch the full content of specific tweets when you already know their numeric tweet IDs (accepts multiple IDs in one call). Use this to expand IDs surfaced by search, timelines, or replies into complete objects. Returns text, author, source client, language, creation time, and engagement counts (likes, retweets, replies, quotes, bookmarks, views). If you do not have IDs yet, start with `get_twitter_tweet_advanced_search`. parameters: - name: tweet_ids in: query required: true schema: type: array items: type: string description: Comma-separated list of tweet IDs. responses: '200': description: Successful response content: application/json: schema: type: object properties: tweets: type: array items: $ref: '#/components/schemas/Tweet' status: type: string msg: type: string code: type: integer x-x402: path: /apis/v2/twitter/tweets source: https://github.com/AIsa-team/aisa-proxy /twitter/tweet/replies: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.00015 p50: 0.0022 p95: 0.00255 max: 0.0204 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Tweet Replies operationId: get_twitter_tweet_replies description: Get the direct replies to a tweet, cursor-paginated. Use this to read the discussion under a post — sentiment, corrections, or follow-up questions. Returns full tweet objects with engagement counts. Prefer `get_twitter_tweet_replies_v2` when you want to control ordering (Relevance, Latest, or Likes); this v1 endpoint returns the default order only. To follow a conversation upward to its root instead of downward, use `get_twitter_tweet_thread_context`. parameters: - name: tweetId in: query required: true schema: type: string description: The tweet ID to get replies for. - name: cursor in: query schema: type: string description: Cursor for pagination. responses: '200': description: Successful response content: application/json: schema: type: object properties: has_next_page: type: boolean next_cursor: type: string status: type: string tweets: type: array items: $ref: '#/components/schemas/Tweet' description: Array of reply tweets. msg: type: string x-x402: path: /apis/v2/twitter/tweet/replies source: https://github.com/AIsa-team/aisa-proxy /twitter/tweet/quotes: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.00015 p50: 0.0022 p95: 0.0039 max: 0.006 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Tweet Quotations operationId: get_twitter_tweet_quotes description: Get quote tweets of a given tweet — posts that embedded it with added commentary — cursor-paginated. Use this to see how a post is being reframed or argued about, which is often more revealing than plain replies. Returns full tweet objects with engagement counts. For direct replies use `get_twitter_tweet_replies_v2`; for accounts that amplified it without comment use `get_twitter_tweet_retweeters`. parameters: - name: tweetId in: query required: true schema: type: string description: The tweet ID to get quotes for. - name: cursor in: query schema: type: string description: Cursor for pagination. responses: '200': description: Successful response content: application/json: schema: type: object properties: tweets: type: array items: $ref: '#/components/schemas/Tweet' has_next_page: type: boolean next_cursor: type: string status: type: string msg: type: string x-x402: path: /apis/v2/twitter/tweet/quotes source: https://github.com/AIsa-team/aisa-proxy /twitter/tweet/retweeters: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.0022 p50: 0.0022 p95: 0.0072 max: 0.0072 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Tweet Retweeters operationId: get_twitter_tweet_retweeters description: List the accounts that retweeted a given tweet, cursor-paginated. Use this to map who amplified a message and how influential they are. Returns user objects (handle, name, bio, follower count, verification) — not tweets. For retweets that added commentary use `get_twitter_tweet_quotes`. parameters: - name: tweetId in: query required: true schema: type: string description: The tweet ID to get retweeters for. - name: cursor in: query schema: type: string description: Cursor for pagination. responses: '200': description: Successful response content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' has_next_page: type: boolean next_cursor: type: string status: type: string msg: type: string x-x402: path: /apis/v2/twitter/tweet/retweeters source: https://github.com/AIsa-team/aisa-proxy /twitter/tweet/thread_context: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.007 observed_usd: min: 0.00015 p50: 0.007 p95: 0.007 max: 0.0111 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Tweet Thread Context operationId: get_twitter_tweet_thread_context description: Reconstruct the conversation around a tweet. Accepts either a reply or an original tweet and returns the surrounding thread, cursor-paginated. Use this when a tweet lacks context on its own and you need the parent chain to interpret it correctly. Returns tweets under `tweets` with `has_next_page` and `next_cursor`. For only the replies below a post use `get_twitter_tweet_replies_v2`. parameters: - name: tweetId in: query required: true schema: type: string description: The tweet ID to get. Can be a reply tweet or an original tweet. - name: cursor in: query required: false schema: type: string description: The cursor to paginate through the results. First page is empty. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TweetThreadContextResponse' x-x402: path: /apis/v2/twitter/tweet/thread_context source: https://github.com/AIsa-team/aisa-proxy /twitter/article: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0022 observed_usd: min: 0.001 p50: 0.0022 p95: 0.0022 max: 0.0022 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Article operationId: get_twitter_article description: Get the full body of an X Article (long-form post) by its tweet ID. Use this when a tweet links to or is an Article and the 280-character preview is not enough — this returns the complete text rather than the truncated tweet. Returns the article under `article`. For ordinary tweets use `get_twitter_tweets`. parameters: - name: tweet_id in: query required: true schema: type: string description: The tweet ID of the article. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ArticleResponse' x-x402: path: /apis/v2/twitter/article source: https://github.com/AIsa-team/aisa-proxy /twitter/tweet/advanced_search: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0022 observed_usd: min: 0.00015 p50: 0.0022 p95: 0.006 max: 0.006 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Advanced Search operationId: get_twitter_tweet_advanced_search description: Search X posts by keyword or query with X's advanced search operators, sorted by Latest (default) or Top. This is the primary entry point for X content research when you do not yet have tweet IDs or handles. Supports operators in the query string such as `from:`, `to:`, `since:`, `until:`, `min_faves:`, and `-filter:replies`. Cursor-paginated; returns tweets with `has_next_page` and `next_cursor`. To search accounts rather than posts use `get_twitter_user_search`. To read one account's own posts use `get_twitter_user_tweet_timeline`. parameters: - name: query in: query required: true schema: type: string description: The query to search for. - name: queryType in: query required: true schema: type: string enum: - Latest - Top default: Latest description: The query type to search for. - name: cursor in: query required: false schema: type: string description: The cursor to paginate through the results. First page is empty. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AdvancedSearchResponse' x-x402: path: /apis/v2/twitter/tweet/advanced_search source: https://github.com/AIsa-team/aisa-proxy /twitter/tweet/replies/v2: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0036 observed_usd: min: 0.00015 p50: 0.0036 p95: 0.0108 max: 0.0225 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get Tweet Replies V2 operationId: get_twitter_tweet_replies_v2 description: 'Get replies to a tweet with control over sort order — Relevance (default), Latest, or Likes — 20 per page, cursor-paginated. Use this instead of `get_twitter_tweet_replies` whenever ordering matters: Likes surfaces the community''s top responses, Latest gives a live view of an unfolding thread. Returns full tweet objects with engagement counts.' parameters: - name: tweetId in: query required: true schema: type: string description: The tweet ID to get replies for. e.g. 1846987139428634858 - name: cursor in: query required: false schema: type: string description: Cursor for paginating through results. Leave empty for the first page. - name: queryType in: query required: false schema: type: string enum: - Relevance - Latest - Likes default: Relevance description: Sort order for replies. Default is Relevance. responses: '200': description: Tweet replies response content: application/json: schema: type: object properties: has_next_page: type: boolean description: Indicates if there are more results available next_cursor: type: string description: Cursor for fetching the next page of results status: type: string enum: - success - error example: success description: Status of the request tweets: type: array items: $ref: '#/components/schemas/Tweet' description: Array of reply tweets. msg: type: string description: Error message if status is error. x-x402: path: /apis/v2/twitter/tweet/replies/v2 source: https://github.com/AIsa-team/aisa-proxy /twitter/user_about: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.00044 observed_usd: min: 0.00018 p50: 0.00044 p95: 0.00044 max: 0.00044 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Profile About operationId: get_twitter_user_about description: Get the extended 'About this account' panel for an X user by @handle. Use this for provenance and trust checks — it surfaces signals the standard profile does not, such as the account's country, verification details, and username-change history. Returns a single profile object under `data`. For the standard profile (bio, follower counts, avatar), use `get_twitter_user_info` instead. parameters: - name: userName in: query required: true schema: type: string description: The screen name of the user responses: '200': description: User profile information content: application/json: schema: $ref: '#/components/schemas/UserProfileAboutResponse' x-x402: path: /apis/v2/twitter/user_about source: https://github.com/AIsa-team/aisa-proxy /twitter/user/batch_info_by_ids: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.00044 observed_usd: min: 0.00036 p50: 0.00044 p95: 0.00044 max: 0.0334 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Batch Get User Info By UserIds operationId: get_twitter_user_batch_info_by_ids description: Resolve many X users at once from their numeric user IDs, passed as a comma-separated `userIds` string. Use this when a previous call (timeline, retweeters, followers) gave you IDs and you need to turn them into full profiles in one request instead of looping. Returns an array of user objects under `users`. Note this endpoint takes numeric IDs, not @handles — to look up by handle use `get_twitter_user_info`. parameters: - name: userIds in: query required: true schema: type: string description: Comma-separated user IDs responses: '200': description: Batch user information content: application/json: schema: $ref: '#/components/schemas/BatchUserInfoResponse' x-x402: path: /apis/v2/twitter/user/batch_info_by_ids source: https://github.com/AIsa-team/aisa-proxy /twitter/user/info: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.00044 observed_usd: min: 0.00018 p50: 0.00044 p95: 0.00044 max: 0.00044 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Info operationId: get_twitter_user_info description: Look up one X (Twitter) user's public profile by @handle (screen name). Use this when you need to know who an account is — identity, reach, or credibility — before deciding whether to trust or analyze their content. Returns display name, bio, follower/following counts, verification status, account creation date, location, and profile images. If you only have a numeric user ID, use `get_twitter_user_batch_info_by_ids` instead. If you need extended profile metadata such as country or username-change history, use `get_twitter_user_about`. If you want their posts rather than their profile, use `get_twitter_user_tweet_timeline`. parameters: - name: userName in: query required: true schema: type: string description: The screen name of the user responses: '200': description: User information content: application/json: schema: $ref: '#/components/schemas/UserInfoResponse' x-x402: path: /apis/v2/twitter/user/info source: https://github.com/AIsa-team/aisa-proxy /twitter/user/tweet_timeline: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0036 observed_usd: min: 0.00015 p50: 0.0036 p95: 0.0036 max: 0.0114 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Tweet Timeline operationId: get_twitter_user_tweet_timeline description: Retrieve a user's own tweets by numeric `userId`, newest first, matching the order shown on their profile in the X app. Up to 20 tweets per page; pass the returned cursor for more. Optionally include replies and the parent tweet of each reply. Use this to read what an account publishes over time. Time-range filtering is NOT supported here — if you need tweets within a specific time window, use `get_twitter_user_mentions` (which accepts `sinceTime`/`untilTime`) or `get_twitter_tweet_advanced_search` with date operators in the query. If you only have a @handle, `get_twitter_user_last_tweets` accepts either handle or ID. parameters: - name: userId in: query required: false schema: type: string description: User ID of the user whose timeline to retrieve. - name: includeReplies in: query required: false schema: type: boolean default: false description: Whether to include replies in the results. Defaults to false. - name: includeParentTweet in: query required: false schema: type: boolean default: false description: Whether to include the parent tweet when a tweet is a reply. Defaults to false. - name: cursor in: query required: false schema: type: string description: Cursor for paginating through results. Leave empty for the first page. responses: '200': description: User tweet timeline content: application/json: schema: $ref: '#/components/schemas/UserTweetsResponse' x-x402: path: /apis/v2/twitter/user/tweet_timeline source: https://github.com/AIsa-team/aisa-proxy /twitter/user/last_tweets: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0036 observed_usd: min: 0.00015 p50: 0.0036 p95: 0.006 max: 0.006 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Last Tweets operationId: get_twitter_user_last_tweets description: Get a user's most recent tweets, accepting either `userName` (@handle) or `userId` — useful when you have not resolved the handle to an ID yet. Optionally include replies. Cursor-paginated. Returns tweets under `data` with `has_next_page` and `next_cursor`. Use `get_twitter_user_tweet_timeline` instead when you already have the numeric ID and want the full profile-order timeline with parent-tweet expansion. parameters: - name: userId in: query schema: type: string description: User ID of the user - name: userName in: query schema: type: string description: Screen name of the user - name: cursor in: query schema: type: string description: Cursor for pagination - name: includeReplies in: query schema: type: boolean default: false description: Include replies in the results responses: '200': description: User tweets content: application/json: schema: $ref: '#/components/schemas/UserTweetsResponse' x-x402: path: /apis/v2/twitter/user/last_tweets source: https://github.com/AIsa-team/aisa-proxy /twitter/user/followers: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.036 observed_usd: min: 0.0006 p50: 0.002 p95: 0.036 max: 0.036 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Followers operationId: get_twitter_user_followers description: List the accounts that follow a given X user, identified by @handle, newest follower first. Returns up to 200 per page by default with `has_next_page` and `next_cursor`; each entry is a full user object (handle, name, bio, follower count, verification). Use this for audience analysis, mapping a competitor's follower base, or finding influential followers. For the reverse direction (who this user follows) use `get_twitter_user_followings`. For only the verified subset use `get_twitter_user_verified_followers` — note that one takes a numeric `user_id`, not a handle. parameters: - name: userName in: query required: true schema: type: string description: Screen name of the user - name: cursor in: query schema: type: string description: Cursor for pagination - name: pageSize in: query schema: type: integer default: 200 minimum: 20 maximum: 200 description: Number of followers per page responses: '200': description: User followers content: application/json: schema: $ref: '#/components/schemas/UserFollowersResponse' x-x402: path: /apis/v2/twitter/user/followers source: https://github.com/AIsa-team/aisa-proxy /twitter/user/followings: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.036 observed_usd: min: 0.0006 p50: 0.036 p95: 0.036 max: 0.036 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Followings operationId: get_twitter_user_followings description: List the accounts a given X user follows, identified by @handle. Returns 200 entries per page with `has_next_page` and `next_cursor`. Use this to infer a user's interests, information sources, or professional network — who someone follows is usually a stronger signal of intent than who follows them. For the opposite direction use `get_twitter_user_followers`. To test a single specific pair without paging through thousands of records, use `get_twitter_user_check_follow_relationship`. parameters: - name: userName in: query required: true schema: type: string description: Screen name of the user. - name: cursor in: query schema: type: string description: The cursor to paginate through the results. First page is empty. - name: pageSize in: query schema: type: integer default: 200 minimum: 20 maximum: 200 description: The number of followings to return per page. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/UserFollowingsResponse' x-x402: path: /apis/v2/twitter/user/followings source: https://github.com/AIsa-team/aisa-proxy /twitter/user/mentions: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0036 observed_usd: min: 0.00015 p50: 0.0021 p95: 0.0036 max: 0.006 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Mentions operationId: get_twitter_user_mentions description: 'Get tweets that mention a given @handle, 20 per page. This is the only user-scoped X endpoint that supports a time window: pass `sinceTime` and/or `untilTime` as Unix timestamps in seconds to bound the range. Use this for monitoring — brand mentions, inbound replies, reputation tracking, or ''what happened to this account in the last 24 hours''. Returns tweets with `has_next_page` and `next_cursor`. For the account''s own posts rather than mentions of it, use `get_twitter_user_tweet_timeline`.' parameters: - name: userName in: query required: true schema: type: string description: The user screen name to get mentions for. - name: sinceTime in: query schema: type: integer format: int64 description: On or after a specified unix timestamp in seconds. - name: untilTime in: query schema: type: integer format: int64 description: Before a specified unix timestamp in seconds. - name: cursor in: query schema: type: string description: The cursor to paginate through the results. First page is empty. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/UserMentionsResponse' x-x402: path: /apis/v2/twitter/user/mentions source: https://github.com/AIsa-team/aisa-proxy /twitter/user/check_follow_relationship: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.0012 observed_usd: min: 0.001 p50: 0.001 p95: 0.0012 max: 0.0012 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Check Follow Relationship operationId: get_twitter_user_check_follow_relationship description: Check whether one X user follows another, in both directions, by @handle. Use this for a single targeted lookup instead of paging through `get_twitter_user_followers` or `get_twitter_user_followings` — it answers 'does A follow B, and does B follow A' in one request. Returns the relationship flags under `data`. parameters: - name: source_user_name in: query required: true schema: type: string description: Screen name of the source user. - name: target_user_name in: query required: true schema: type: string description: Screen name of the target user. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FollowRelationshipResponse' x-x402: path: /apis/v2/twitter/user/check_follow_relationship source: https://github.com/AIsa-team/aisa-proxy /twitter/user/search: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.0012 observed_usd: min: 0.00015 p50: 0.0012 p95: 0.0072 max: 0.0072 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Search User by Keyword operationId: get_twitter_user_search description: Search X user accounts by keyword and get back matching profiles. Use this when you know roughly who you are looking for — a company name, a topic, a partial handle — but not the exact @handle. Cursor-paginated; returns full user objects under `users`. This searches accounts, not posts; to search tweet content use `get_twitter_tweet_advanced_search`. parameters: - name: query in: query required: true schema: type: string description: The keyword to search. - name: cursor in: query schema: type: string description: The cursor to paginate through the results. First page is empty. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchUserResponse' x-x402: path: /apis/v2/twitter/user/search source: https://github.com/AIsa-team/aisa-proxy /twitter/user/verifiedFollowers: get: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.00044 observed_usd: min: 0.00044 p50: 0.00044 p95: 0.012 max: 0.012 cost_drivers: - param: result count effect: charge scales with number of tweets/users returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Twitter / X summary: Get User Verified Followers operationId: get_twitter_user_verified_followers description: List only the verified accounts following a given X user, in reverse chronological order. Use this to gauge the quality rather than the size of an audience — verified followers are a better credibility signal than raw follower count. Cursor-paginated. Takes a numeric `user_id`, not a @handle; resolve the handle first with `get_twitter_user_info`. For the complete follower list use `get_twitter_user_followers`. parameters: - name: user_id in: query required: true schema: type: string description: User ID of the user. - name: cursor in: query schema: type: string description: The cursor to paginate through the results. First page is empty. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/VerifiedFollowersResponse' x-x402: path: /apis/v2/twitter/user/verifiedFollowers source: https://github.com/AIsa-team/aisa-proxy /waveinflu/email-lookup: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 2 nominal_usd: 0.005 observed_usd: min: 0.005 p50: 0.005 p95: 0.009092 max: 0.09092 cost_drivers: - param: records returned effect: charge scales with number of records/creators returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Email Lookup description: Looks up contact emails for one TikTok, Instagram or YouTube creator from a profile URL. Returns `platform` parsed from the URL, `username`, `profileLink`, `platformUserId`, `region`, a primary `email`, an `emails` array of every address found, and a `contacts` array of external links each shaped `{url, type}` (personal sites, WhatsApp links), plus `quota.cost` in credits and `quota.remainingQuota`. Measured at 533 bytes and about 2 seconds for one Instagram creator. `email` is null and `emails` empty when the creator publishes no address — a normal result, not an error. Handles one creator per call. To assemble a creator list first use `post_waveinflu_similar_creators`, which already returns an `email` for most matches; call this endpoint for the ones that come back null, and for Instagram creators, which the similar-creators endpoint does not cover. operationId: post_waveinflu_email_lookup requestBody: required: true content: application/json: schema: type: object required: - url properties: url: type: string description: TikTok, Instagram, or YouTube creator profile URL. example: https://www.instagram.com/onkimia/ responses: '200': description: Email lookup completed content: application/json: schema: type: object properties: code: type: number example: 1000 message: type: string example: Email lookup completed data: $ref: '#/components/schemas/EmailLookupData' tags: - WaveInflu x-x402: path: /apis/v2/waveinflu/email-lookup source: https://github.com/AIsa-team/aisa-proxy /waveinflu/similar: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1.5 nominal_usd: 0.02 observed_usd: min: 0.02 p50: 0.02 p95: 0.061367 max: 4.0911 cost_drivers: - param: records returned effect: charge scales with number of records/creators returned cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower summary: Similar Creators description: 'Finds creators similar to a seed profile, a natural-language content direction, or both, on YouTube or TikTok. `platform` is required; supply `seedProfileUrl`, `contentDirection` (max 800 characters) or both, with `limit` (1–100, default 25) and optional `filters` for regions, languages, follower and average-view ranges. The response echoes the resolved `mode` — `homepage` for a seed alone, `direction` for a direction alone, `homepage_direction` for both — and sets `sourceUserId` only when a seed resolved. Each match carries `username`, `platformHandle`, `description`, `email`, `profileUrl`, `avatar`, `similarityScore` (sorted descending), `followerCount`, `averagePlayCount`, `lastPublishedTime`, `region` and `language`. Field shape differs by platform: YouTube matches add `channelId` and `channelTitle`; TikTok matches add `userId`, `uniqueId`, `nickname` and `averageLikeCount`, none of which YouTube returns. Measured at 4.2 KB for 5 YouTube matches (about 8 seconds) and 2.5 KB for 3 TikTok matches. Most matches already include an `email`; use `post_waveinflu_email_lookup` for the ones that come back null and for Instagram creators, which this endpoint does not match.' operationId: post_waveinflu_similar_creators requestBody: required: true content: application/json: schema: type: object required: - platform properties: platform: type: string enum: - youtube - tiktok description: Target platform. Currently supports youtube and tiktok. example: youtube limit: type: number minimum: 1 maximum: 100 default: 25 description: Maximum number of creators to return. Default 25, range 1–100. example: 10 seedProfileUrl: type: string description: YouTube or TikTok creator profile URL as the seed for matching. example: https://www.youtube.com/@mkbhd contentDirection: type: string maxLength: 800 description: Natural-language description of the creator type you are looking for. Max 800 characters. example: consumer tech creators covering AI apps, Android phones, productivity gadgets, and honest product reviews filters: $ref: '#/components/schemas/SimilarCreatorFilters' responses: '200': description: Similar creators completed content: application/json: schema: type: object properties: code: type: number example: 1000 message: type: string example: Similar creators completed data: $ref: '#/components/schemas/SimilarData' tags: - WaveInflu x-x402: path: /apis/v2/waveinflu/similar source: https://github.com/AIsa-team/aisa-proxy /anthropic-websearch/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.3 observed_usd: min: 0.002427 p50: 0.038825 p95: 0.111352 max: 0.132285 cost_drivers: - param: response size effect: charge scales with provider search response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Web & News Search summary: Model-grounded web search (Anthropic). operationId: post_anthropic_websearch_search description: 'Ask a question and get an answer that Claude wrote after searching the live web. Send a normal Messages request — a `messages` array plus `max_tokens` — and the endpoint injects a fixed, server-pinned model and the `web_search` tool for you; you cannot override the model or add tools, which keeps cost bounded. Claude decides when to search (up to `max_uses` searches, default 5), reads the results, and answers with inline citations. The response is a standard Anthropic Messages object: `content[]` contains `server_tool_use` (the queries issued), `web_search_tool_result` (the sources found) and `text` blocks (the answer with `citations`), and `usage.server_tool_use.web_search_requests` reports how many searches were billed. Billing is pay-as-you-go at exact cost: `web_search_requests × $0.01` plus the model''s own token cost, with no markup; a failed search (HTTP 200 `web_search_tool_result_error`) is not billed. Use this when you want a written, cited answer grounded in current web content — for open-web research that returns ranked links and page text in one call use [`post_tavily_search`](/api-reference/search/post_tavily-search) instead, and for the OpenAI-model equivalent see [`post_openai_websearch_search`](/api-reference/search/post_openai-websearch-search).' requestBody: required: true content: application/json: schema: type: object required: - messages - max_tokens properties: messages: type: array description: Conversation messages, same format as the Anthropic Messages API. The user turn holds your question. items: type: object properties: role: type: string enum: - user - assistant content: type: string description: Message text. Structured content blocks are also accepted. example: - role: user content: What are the three biggest AI announcements this week? Give one sentence each with sources. max_tokens: type: integer description: Maximum number of tokens to generate in the answer. Required by the upstream Messages API. default: 1024 example: 1024 system: type: string description: Optional system prompt to steer the answer's tone or format. example: max_tokens: 1024 messages: - role: user content: What are the three biggest AI announcements this week? Give one sentence each with sources. responses: '200': description: A standard Anthropic Messages response. `content[]` interleaves the searches performed and the cited answer; `usage.server_tool_use.web_search_requests` is the billed search count. headers: X-AISA-Web-Search-Count: description: Number of web searches billed for this request. schema: type: integer X-AISA-Price-USD: description: Amount charged to your account for this request, in USD. schema: type: string content: application/json: schema: type: object properties: id: type: string type: type: string example: message role: type: string example: assistant stop_reason: type: string example: end_turn content: type: array description: 'Ordered blocks: server_tool_use (search queries), web_search_tool_result (sources), and text (the cited answer).' items: type: object usage: type: object properties: input_tokens: type: integer output_tokens: type: integer cache_read_input_tokens: type: integer cache_creation_input_tokens: type: integer server_tool_use: type: object properties: web_search_requests: type: integer description: Billed web search count. x-x402: path: /apis/v2/anthropic-websearch/search source: https://github.com/AIsa-team/aisa-proxy /openai-websearch/search: post: x-aisa-pricing: model: dynamic currency: USD basis: provider_cost x 1 nominal_usd: 0.3 observed_usd: min: 0.00104 p50: 0.054415 p95: 0.095127 max: 0.09519 cost_drivers: - param: response size effect: charge scales with provider search response size cost_tier: variable note: nominal_usd is a static reference, NOT a guaranteed minimum; actual charge = provider_cost x multiplier and can be higher or lower tags: - Web & News Search summary: Model-grounded web search (OpenAI). operationId: post_openai_websearch_search description: 'Ask a question and get an answer that an OpenAI model wrote after searching the live web. Send a Responses request — an `input` string (or message array) — and the endpoint injects a fixed, server-pinned model and the `web_search` tool for you; the model, tool and per-request search cap are server-controlled to keep cost bounded. The reply is a standard OpenAI Responses object: `output[]` contains `web_search_call` items (each a search that ran) and a `message` item with the answer text and URL citations, and the billed search count equals the number of `web_search_call` items. Billing is pay-as-you-go at exact cost: `web_search_calls × $0.01` plus the model''s own token cost (fresh input = `input_tokens − cached`), with no markup. Use this when you want a written, cited answer grounded in current web content from an OpenAI model — for the Anthropic-model equivalent see [`post_anthropic_websearch_search`](/api-reference/search/post_anthropic-websearch-search), and for raw ranked links with extracted page text use [`post_tavily_search`](/api-reference/search/post_tavily-search).' requestBody: required: true content: application/json: schema: type: object required: - input properties: input: type: string description: Your question or instruction, same format as the OpenAI Responses API `input`. A message array is also accepted. example: What are the three biggest AI announcements this week? Give one sentence each with sources. max_output_tokens: type: integer description: Optional cap on the number of tokens generated in the answer. example: 1024 instructions: type: string description: Optional high-level instructions to steer the answer's tone or format. example: input: What are the three biggest AI announcements this week? Give one sentence each with sources. max_output_tokens: 1024 responses: '200': description: A standard OpenAI Responses object. `output[]` interleaves web_search_call items and the cited answer message; the number of web_search_call items is the billed search count. headers: X-AISA-Web-Search-Count: description: Number of web searches billed for this request. schema: type: integer X-AISA-Price-USD: description: Amount charged to your account for this request, in USD. schema: type: string content: application/json: schema: type: object properties: id: type: string object: type: string example: response status: type: string example: completed output: type: array description: 'Ordered items: web_search_call (searches performed) and message (the cited answer).' items: type: object usage: type: object properties: input_tokens: type: integer output_tokens: type: integer input_tokens_details: type: object properties: cached_tokens: type: integer x-x402: path: /apis/v2/openai-websearch/search source: https://github.com/AIsa-team/aisa-proxy /youtube/search: get: x-aisa-pricing: model: per_request currency: USD price_usd: 0.0029 cost_tier: low summary: YouTube Search operationId: get_youtube_search description: 'Search YouTube and get back matching videos, channels, and playlists. Set `engine=youtube` and pass the query in `q`; both are required. Optionally narrow by country (`gl`) and interface language (`hl`), or pass a YouTube filter token in `sp` for pagination and advanced filters such as upload date, duration, or result type. Use this to find video content on a topic, track a channel''s recent uploads, or gauge how much video coverage a subject has. Note: this is served through the AIsa mapped path `/apis/v1/youtube/search`; the upstream provider''s canonical path is not mounted directly.' tags: - YouTube Search parameters: - name: engine in: query required: true schema: type: string enum: - youtube description: SearchApi engine identifier. Use `youtube` for this YouTube endpoint. - name: q in: query required: true schema: type: string description: Search query. Required by runtime and upstream SearchApi. - name: sp in: query required: false schema: type: string description: YouTube filter token (pagination or advanced filters) - name: gl in: query required: false schema: type: string description: Country code (e.g. us, jp) - name: hl in: query required: false schema: type: string description: Interface language responses: '200': description: Successful YouTube search response content: application/json: schema: type: object description: YouTube search result payload returned by SearchApi through the AIsa wrapper. additionalProperties: true properties: search_metadata: type: object additionalProperties: true properties: id: type: string status: type: string created_at: type: string request_time_taken: type: number parsing_time_taken: type: number total_time_taken: type: number request_url: type: string html_url: type: string json_url: type: string search_parameters: type: object additionalProperties: true search_information: type: object additionalProperties: true properties: total_results: type: integer videos: type: array items: type: object additionalProperties: true properties: position: type: integer id: type: string title: type: string link: type: string description: type: string thumbnail: type: string published_time: type: string length: type: string views: oneOf: - type: integer - type: string channel: type: object additionalProperties: true is_live: type: boolean badges: type: array items: type: string channels: type: array items: type: object additionalProperties: true properties: position: type: integer id: type: string title: type: string link: type: string description: type: string thumbnail: type: string subscribers: type: string shorts: type: array items: type: object additionalProperties: true properties: position: type: integer section_title: type: string items: type: array items: type: object additionalProperties: true sections: type: array items: type: object additionalProperties: true properties: position: type: integer section_title: type: string items: type: array items: type: object additionalProperties: true playlists: type: array items: type: object additionalProperties: true ads: type: array items: type: object additionalProperties: true pagination: type: object additionalProperties: true properties: next_page_token: type: string '400': description: Invalid request parameters '401': description: Unauthorized / Invalid API key security: - bearerAuth: [] x-x402: path: /apis/v2/youtube/search source: https://github.com/AIsa-team/aisa-proxy components: securitySchemes: BearerAuth: type: http scheme: bearer description: AIsa API key. Get yours at https://aisa.one Account_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key or OAuth access token Bearer: type: http scheme: bearer Ahrefs_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key bearerAuth: type: http scheme: bearer Apollo_BearerAuth: type: http scheme: bearer ChatImageGeneration_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key ClaudeMessages_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key description: Your AIsa API key as a Bearer token. Coingecko_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key Dataforseo_BearerAuth: type: http scheme: bearer GeminiOpenapi_BearerAuth: type: http scheme: bearer bearerFormat: API Key Instagram_bearerAuth: type: http scheme: bearer description: AIsa API key. Get yours at https://aisa.one Jina_BearerAuth: type: http scheme: bearer bearerFormat: API Key KalshiOpenapi_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key description: Your AIsa API key as a Bearer token. MatchingMarketsOpenapi_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key description: Your AIsa API key as a Bearer token. OpenaiChat_BearerAuth: type: http scheme: bearer bearerFormat: API Key OpenaiImagesGenerations_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key Pinterest_bearerAuth: type: http scheme: bearer description: AIsa API key. Get yours at https://aisa.one PlatformTxyzOpenapi_BearerAuth: type: http scheme: bearer bearerFormat: JWT PolymarketOpenapi_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key description: Your AIsa API key as a Bearer token. Reddit_bearerAuth: type: http scheme: bearer description: AIsa API key. Get yours at https://aisa.one Semrush_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key Similarweb_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key TwitterActions_BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key description: Your AIsa API key. The authenticated source user (the account doing the follow) is determined by the OAuth session attached to your key. TwitterList_BearerAuth: type: http scheme: bearer TwitterTrend_BearerAuth: type: http scheme: bearer TwitterTweetRepliesV2_BearerAuth: type: http scheme: bearer TwitterUserBatch01_BearerAuth: type: http scheme: bearer TwitterUserBatch02_BearerAuth: type: http scheme: bearer schemas: type_agent_AgentSignupRequest: type: object properties: human_email: type: string description: Email address of the human who owns the agent. A 6-digit OTP will be sent to this address. username: type: string description: Username for the auto-created inbox (e.g. "my-agent" creates my-agent@agentmail.to). source: type: string description: |- The SDK, framework, or platform issuing this sign-up (e.g. `agentmail-python`, `agentmail-cli`, `agentmail-mcp`). Identifies the caller — answers "who is signing up". Max 2048 characters. referrer: type: string description: |- The channel that drove this sign-up — where the agent or its developer discovered AgentMail (e.g. `agent.email`, a partner URL, a campaign tag). Answers "where did this sign-up come from". Max 2048 characters. required: - human_email - username description: Request body to sign up an agent. title: AgentSignupRequest type_agent_AgentSignupResponse: type: object properties: organization_id: type: string description: ID of the created organization. inbox_id: type: string description: ID of the auto-created inbox. api_key: type: string description: API key for authenticating subsequent requests. Store this securely, it cannot be retrieved again. required: - organization_id - inbox_id - api_key description: Response after successful agent sign-up. title: AgentSignupResponse type__ErrorName: type: string description: Name of error. title: ErrorName type__ValidationErrorResponse: type: object properties: name: $ref: '#/components/schemas/type__ErrorName' errors: description: Validation errors. required: - name - errors title: ValidationErrorResponse type_agent_AgentVerifyRequest: type: object properties: otp_code: type: string description: 6-digit verification code sent to the human's email address. required: - otp_code description: Request body to verify an agent with an OTP code. title: AgentVerifyRequest type_agent_AgentVerifyResponse: type: object properties: verified: type: boolean description: Whether the organization was verified. required: - verified description: Response after successful agent verification. title: AgentVerifyResponse type__Limit: type: integer description: Limit of number of items returned. title: Limit type__PageToken: type: string description: Page token for pagination. title: PageToken type__Ascending: type: boolean description: Sort in ascending temporal order. title: Ascending type__Count: type: integer description: Number of items returned. title: Count type_pods_PodId: type: string description: ID of pod. title: PodId type_inboxes_InboxId: type: string description: The ID of the inbox. title: InboxId type_inboxes_Email: type: string description: Email address of the inbox. title: Email type_inboxes_DisplayName: type: string description: 'Display name: `Display Name `.' title: DisplayName type_inboxes_ClientId: type: string description: Client ID of inbox. title: ClientId type_inboxes_MetadataValue: oneOf: - type: string - type: number format: double - type: boolean description: A metadata value. May be a string, number, or boolean. title: MetadataValue type_inboxes_Metadata: type: object additionalProperties: $ref: '#/components/schemas/type_inboxes_MetadataValue' description: |- Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and string values are each limited to 256 characters. When updating metadata, send a key with a null value to remove that key. title: Metadata type_inboxes_Inbox: type: object properties: pod_id: $ref: '#/components/schemas/type_pods_PodId' inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' email: $ref: '#/components/schemas/type_inboxes_Email' display_name: $ref: '#/components/schemas/type_inboxes_DisplayName' client_id: $ref: '#/components/schemas/type_inboxes_ClientId' metadata: $ref: '#/components/schemas/type_inboxes_Metadata' description: Custom metadata attached to the inbox. updated_at: type: string format: date-time description: Time at which inbox was last updated. created_at: type: string format: date-time description: Time at which inbox was created. required: - pod_id - inbox_id - email - updated_at - created_at title: Inbox type_inboxes_ListInboxesResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' inboxes: type: array items: $ref: '#/components/schemas/type_inboxes_Inbox' description: Ordered by `created_at` descending. required: - count - inboxes title: ListInboxesResponse type__ErrorMessage: type: string description: Error message. title: ErrorMessage type__ErrorResponse: type: object properties: name: $ref: '#/components/schemas/type__ErrorName' message: $ref: '#/components/schemas/type__ErrorMessage' required: - name - message title: ErrorResponse type_inboxes_CreateInboxRequest: type: object properties: username: type: string description: Username of address. Randomly generated if not specified. domain: type: string description: Domain of address. Must be verified domain. Defaults to `agentmail.to`. display_name: $ref: '#/components/schemas/type_inboxes_DisplayName' client_id: $ref: '#/components/schemas/type_inboxes_ClientId' metadata: $ref: '#/components/schemas/type_inboxes_Metadata' description: Custom metadata to attach to the inbox. title: CreateInboxRequest type_inboxes_UpdateMetadata: type: object additionalProperties: allOf: - $ref: '#/components/schemas/type_inboxes_MetadataValue' nullable: true description: |- Custom key-value pairs to merge into the inbox's existing metadata. A value may be a string, number, boolean, or null. Setting a key to null removes it. Up to 256 keys; keys and string values are each limited to 256 characters. title: UpdateMetadata type_inboxes_UpdateInboxRequest: type: object properties: display_name: $ref: '#/components/schemas/type_inboxes_DisplayName' metadata: description: |- Metadata to merge into the inbox's existing metadata. Keys you include are added or overwritten; keys you omit are left unchanged. To remove a single key, send it with a null value. To clear all metadata, send `metadata` as null. Sending an empty object is rejected; use null to clear. Each update must include at least one of `display_name` or `metadata`. allOf: - $ref: '#/components/schemas/type_inboxes_UpdateMetadata' nullable: true title: UpdateInboxRequest type__Labels: type: array items: type: string description: Labels to filter by. title: Labels type__Before: type: string format: date-time description: Timestamp before which to filter by. title: Before type__After: type: string format: date-time description: Timestamp after which to filter by. title: After type__IncludeSpam: type: boolean description: Include spam in results. title: IncludeSpam type__IncludeBlocked: type: boolean description: Include blocked in results. title: IncludeBlocked type__IncludeUnauthenticated: type: boolean description: Include unauthenticated in results. title: IncludeUnauthenticated type__IncludeTrash: type: boolean description: Include trash in results. title: IncludeTrash type_threads_ThreadId: type: string description: ID of thread. title: ThreadId type_threads_ThreadLabels: type: array items: type: string description: Labels of thread. title: ThreadLabels type_threads_ThreadTimestamp: type: string format: date-time description: Timestamp of last sent or received message. title: ThreadTimestamp type_threads_ThreadReceivedTimestamp: type: string format: date-time description: Timestamp of last received message. title: ThreadReceivedTimestamp type_threads_ThreadSentTimestamp: type: string format: date-time description: Timestamp of last sent message. title: ThreadSentTimestamp type_threads_ThreadSenders: type: array items: type: string description: Senders in thread. In format `username@domain.com` or `Display Name `. title: ThreadSenders type_threads_ThreadRecipients: type: array items: type: string description: Recipients in thread. In format `username@domain.com` or `Display Name `. title: ThreadRecipients type_threads_ThreadSubject: type: string description: Subject of thread. title: ThreadSubject type_threads_ThreadPreview: type: string description: Text preview of last message in thread. title: ThreadPreview type_attachments_AttachmentId: type: string description: ID of attachment. title: AttachmentId type_attachments_AttachmentFilename: type: string description: Filename of attachment. title: AttachmentFilename type_attachments_AttachmentSize: type: integer description: Size of attachment in bytes. title: AttachmentSize type_attachments_AttachmentContentType: type: string description: Content type of attachment. title: AttachmentContentType type_attachments_AttachmentContentDisposition: type: string enum: - inline - attachment description: Content disposition of attachment. title: AttachmentContentDisposition type_attachments_AttachmentContentId: type: string description: Content ID of attachment. title: AttachmentContentId type_attachments_Attachment: type: object properties: attachment_id: $ref: '#/components/schemas/type_attachments_AttachmentId' filename: $ref: '#/components/schemas/type_attachments_AttachmentFilename' size: $ref: '#/components/schemas/type_attachments_AttachmentSize' content_type: $ref: '#/components/schemas/type_attachments_AttachmentContentType' content_disposition: $ref: '#/components/schemas/type_attachments_AttachmentContentDisposition' content_id: $ref: '#/components/schemas/type_attachments_AttachmentContentId' required: - attachment_id - size title: Attachment type_threads_ThreadAttachments: type: array items: $ref: '#/components/schemas/type_attachments_Attachment' description: Attachments in thread. title: ThreadAttachments type_threads_ThreadLastMessageId: type: string description: ID of last message in thread. title: ThreadLastMessageId type_threads_ThreadMessageCount: type: integer description: Number of messages in thread. title: ThreadMessageCount type_threads_ThreadSize: type: integer description: Size of thread in bytes. title: ThreadSize type_threads_ThreadUpdatedAt: type: string format: date-time description: Time at which thread was last updated. title: ThreadUpdatedAt type_threads_ThreadCreatedAt: type: string format: date-time description: Time at which thread was created. title: ThreadCreatedAt type_threads_ThreadItem: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' labels: $ref: '#/components/schemas/type_threads_ThreadLabels' timestamp: $ref: '#/components/schemas/type_threads_ThreadTimestamp' received_timestamp: $ref: '#/components/schemas/type_threads_ThreadReceivedTimestamp' sent_timestamp: $ref: '#/components/schemas/type_threads_ThreadSentTimestamp' senders: $ref: '#/components/schemas/type_threads_ThreadSenders' recipients: $ref: '#/components/schemas/type_threads_ThreadRecipients' subject: $ref: '#/components/schemas/type_threads_ThreadSubject' preview: $ref: '#/components/schemas/type_threads_ThreadPreview' attachments: $ref: '#/components/schemas/type_threads_ThreadAttachments' last_message_id: $ref: '#/components/schemas/type_threads_ThreadLastMessageId' message_count: $ref: '#/components/schemas/type_threads_ThreadMessageCount' size: $ref: '#/components/schemas/type_threads_ThreadSize' updated_at: $ref: '#/components/schemas/type_threads_ThreadUpdatedAt' created_at: $ref: '#/components/schemas/type_threads_ThreadCreatedAt' required: - inbox_id - thread_id - labels - timestamp - senders - recipients - last_message_id - message_count - size - updated_at - created_at title: ThreadItem type_threads_ListThreadsResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' threads: type: array items: $ref: '#/components/schemas/type_threads_ThreadItem' description: Ordered by `timestamp` descending. required: - count - threads title: ListThreadsResponse type_messages_MessageId: type: string description: ID of message. title: MessageId type_messages_MessageLabels: type: array items: type: string description: Labels of message. title: MessageLabels type_messages_MessageTimestamp: type: string format: date-time description: Time at which message was sent or drafted. title: MessageTimestamp type_messages_MessageFrom: type: string description: Address of sender. In format `username@domain.com` or `Display Name `. title: MessageFrom type_messages_MessageTo: type: array items: type: string description: Addresses of recipients. In format `username@domain.com` or `Display Name `. title: MessageTo type_messages_MessageCc: type: array items: type: string description: Addresses of CC recipients. In format `username@domain.com` or `Display Name `. title: MessageCc type_messages_MessageBcc: type: array items: type: string description: Addresses of BCC recipients. In format `username@domain.com` or `Display Name `. title: MessageBcc type_messages_MessageSubject: type: string description: Subject of message. title: MessageSubject type_messages_MessagePreview: type: string description: Text preview of message. title: MessagePreview type_messages_MessageText: type: string description: Plain text body of message. title: MessageText type_messages_MessageHtml: type: string description: HTML body of message. title: MessageHtml type_messages_MessageAttachments: type: array items: $ref: '#/components/schemas/type_attachments_Attachment' description: Attachments in message. title: MessageAttachments type_messages_MessageInReplyTo: type: string description: ID of message being replied to. title: MessageInReplyTo type_messages_MessageReferences: type: array items: type: string description: IDs of previous messages in thread. title: MessageReferences type_messages_MessageHeaders: type: object additionalProperties: type: string description: Headers in message. title: MessageHeaders type_messages_MessageSize: type: integer description: Size of message in bytes. title: MessageSize type_messages_MessageUpdatedAt: type: string format: date-time description: Time at which message was last updated. title: MessageUpdatedAt type_messages_MessageCreatedAt: type: string format: date-time description: Time at which message was created. title: MessageCreatedAt type_messages_Message: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' labels: $ref: '#/components/schemas/type_messages_MessageLabels' timestamp: $ref: '#/components/schemas/type_messages_MessageTimestamp' from: $ref: '#/components/schemas/type_messages_MessageFrom' reply_to: type: array items: type: string description: Reply-to addresses. In format `username@domain.com` or `Display Name `. to: $ref: '#/components/schemas/type_messages_MessageTo' cc: $ref: '#/components/schemas/type_messages_MessageCc' bcc: $ref: '#/components/schemas/type_messages_MessageBcc' subject: $ref: '#/components/schemas/type_messages_MessageSubject' preview: $ref: '#/components/schemas/type_messages_MessagePreview' text: $ref: '#/components/schemas/type_messages_MessageText' html: $ref: '#/components/schemas/type_messages_MessageHtml' extracted_text: type: string description: Extracted new text content. extracted_html: type: string description: Extracted new HTML content. attachments: $ref: '#/components/schemas/type_messages_MessageAttachments' in_reply_to: $ref: '#/components/schemas/type_messages_MessageInReplyTo' references: $ref: '#/components/schemas/type_messages_MessageReferences' headers: $ref: '#/components/schemas/type_messages_MessageHeaders' size: $ref: '#/components/schemas/type_messages_MessageSize' updated_at: $ref: '#/components/schemas/type_messages_MessageUpdatedAt' created_at: $ref: '#/components/schemas/type_messages_MessageCreatedAt' required: - inbox_id - thread_id - message_id - labels - timestamp - from - to - size - updated_at - created_at title: Message type_threads_Thread: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' labels: $ref: '#/components/schemas/type_threads_ThreadLabels' timestamp: $ref: '#/components/schemas/type_threads_ThreadTimestamp' received_timestamp: $ref: '#/components/schemas/type_threads_ThreadReceivedTimestamp' sent_timestamp: $ref: '#/components/schemas/type_threads_ThreadSentTimestamp' senders: $ref: '#/components/schemas/type_threads_ThreadSenders' recipients: $ref: '#/components/schemas/type_threads_ThreadRecipients' subject: $ref: '#/components/schemas/type_threads_ThreadSubject' preview: $ref: '#/components/schemas/type_threads_ThreadPreview' attachments: $ref: '#/components/schemas/type_threads_ThreadAttachments' last_message_id: $ref: '#/components/schemas/type_threads_ThreadLastMessageId' message_count: $ref: '#/components/schemas/type_threads_ThreadMessageCount' size: $ref: '#/components/schemas/type_threads_ThreadSize' updated_at: $ref: '#/components/schemas/type_threads_ThreadUpdatedAt' created_at: $ref: '#/components/schemas/type_threads_ThreadCreatedAt' messages: type: array items: $ref: '#/components/schemas/type_messages_Message' description: Messages in thread. Ordered by `timestamp` ascending. required: - inbox_id - thread_id - labels - timestamp - senders - recipients - last_message_id - message_count - size - updated_at - created_at - messages title: Thread type_attachments_AttachmentResponse: type: object properties: attachment_id: $ref: '#/components/schemas/type_attachments_AttachmentId' filename: $ref: '#/components/schemas/type_attachments_AttachmentFilename' size: $ref: '#/components/schemas/type_attachments_AttachmentSize' content_type: $ref: '#/components/schemas/type_attachments_AttachmentContentType' content_disposition: $ref: '#/components/schemas/type_attachments_AttachmentContentDisposition' content_id: $ref: '#/components/schemas/type_attachments_AttachmentContentId' download_url: type: string description: URL to download the attachment. expires_at: type: string format: date-time description: Time at which the download URL expires. required: - attachment_id - size - download_url - expires_at title: AttachmentResponse type_threads_UpdateThreadRequest: type: object properties: add_labels: type: array items: type: string description: Labels to add to thread. Cannot be system labels. remove_labels: type: array items: type: string description: Labels to remove from thread. Cannot be system labels. Takes priority over `add_labels` (in the event of duplicate labels passed in). title: UpdateThreadRequest type_threads_UpdateThreadResponse: type: object properties: thread_id: $ref: '#/components/schemas/type_threads_ThreadId' labels: $ref: '#/components/schemas/type_threads_ThreadLabels' required: - thread_id - labels title: UpdateThreadResponse type_messages_MessageItem: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' labels: $ref: '#/components/schemas/type_messages_MessageLabels' timestamp: $ref: '#/components/schemas/type_messages_MessageTimestamp' from: $ref: '#/components/schemas/type_messages_MessageFrom' to: $ref: '#/components/schemas/type_messages_MessageTo' cc: $ref: '#/components/schemas/type_messages_MessageCc' bcc: $ref: '#/components/schemas/type_messages_MessageBcc' subject: $ref: '#/components/schemas/type_messages_MessageSubject' preview: $ref: '#/components/schemas/type_messages_MessagePreview' attachments: $ref: '#/components/schemas/type_messages_MessageAttachments' in_reply_to: $ref: '#/components/schemas/type_messages_MessageInReplyTo' references: $ref: '#/components/schemas/type_messages_MessageReferences' headers: $ref: '#/components/schemas/type_messages_MessageHeaders' size: $ref: '#/components/schemas/type_messages_MessageSize' updated_at: $ref: '#/components/schemas/type_messages_MessageUpdatedAt' created_at: $ref: '#/components/schemas/type_messages_MessageCreatedAt' required: - inbox_id - thread_id - message_id - labels - timestamp - from - to - size - updated_at - created_at title: MessageItem type_messages_ListMessagesResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' messages: type: array items: $ref: '#/components/schemas/type_messages_MessageItem' description: Ordered by `timestamp` descending. required: - count - messages title: ListMessagesResponse type_messages_BatchGetMessagesMessageIds: type: array items: $ref: '#/components/schemas/type_messages_MessageId' description: |- IDs of messages to fetch. Maximum 500 ids per request. Duplicates are rejected with a validation error. IDs not found in the inbox (including cross-inbox or permission-restricted) are silently omitted from the response; callers detect misses by comparing `count` against `limit`. title: BatchGetMessagesMessageIds type_messages_BatchGetMessagesRequest: type: object properties: message_ids: $ref: '#/components/schemas/type_messages_BatchGetMessagesMessageIds' required: - message_ids title: BatchGetMessagesRequest type_messages_BatchGetMessagesResponse: type: object properties: limit: $ref: '#/components/schemas/type__Limit' count: $ref: '#/components/schemas/type__Count' messages: type: array items: $ref: '#/components/schemas/type_messages_Message' description: |- Found messages. Order matches `message_ids` in the request. Body fields (`text`, `html`, `extracted_text`, `extracted_html`) are never populated; use the single-message endpoint to retrieve bodies. required: - limit - count - messages title: BatchGetMessagesResponse type_messages_RawMessageResponse: type: object properties: message_id: $ref: '#/components/schemas/type_messages_MessageId' description: ID of the message. size: $ref: '#/components/schemas/type_messages_MessageSize' description: Size of the raw message in bytes. download_url: type: string description: S3 presigned URL to download the raw message. Expires at expires_at. expires_at: type: string format: date-time description: Time at which the download URL expires. required: - message_id - size - download_url - expires_at description: S3 presigned URL to download the raw .eml file. title: RawMessageResponse type_messages_UpdateMessageLabels: oneOf: - type: string - type: array items: type: string description: Label or list of labels. title: UpdateMessageLabels type_messages_UpdateMessageRequest: type: object properties: add_labels: $ref: '#/components/schemas/type_messages_UpdateMessageLabels' description: Label or labels to add to message. remove_labels: $ref: '#/components/schemas/type_messages_UpdateMessageLabels' description: Label or labels to remove from message. title: UpdateMessageRequest type_messages_UpdateMessageResponse: type: object properties: message_id: $ref: '#/components/schemas/type_messages_MessageId' labels: $ref: '#/components/schemas/type_messages_MessageLabels' required: - message_id - labels title: UpdateMessageResponse type_messages_Addresses: oneOf: - type: string - type: array items: type: string title: Addresses type_messages_SendMessageReplyTo: $ref: '#/components/schemas/type_messages_Addresses' description: Reply-to address or addresses. title: SendMessageReplyTo type_messages_SendMessageTo: $ref: '#/components/schemas/type_messages_Addresses' description: Recipient address or addresses. title: SendMessageTo type_messages_SendMessageCc: $ref: '#/components/schemas/type_messages_Addresses' description: CC recipient address or addresses. title: SendMessageCc type_messages_SendMessageBcc: $ref: '#/components/schemas/type_messages_Addresses' description: BCC recipient address or addresses. title: SendMessageBcc type_attachments_SendAttachment: type: object properties: filename: $ref: '#/components/schemas/type_attachments_AttachmentFilename' content_type: $ref: '#/components/schemas/type_attachments_AttachmentContentType' content_disposition: $ref: '#/components/schemas/type_attachments_AttachmentContentDisposition' content_id: $ref: '#/components/schemas/type_attachments_AttachmentContentId' content: type: string description: Base64 encoded content of attachment. url: type: string description: URL to the attachment. title: SendAttachment type_messages_SendMessageAttachments: type: array items: $ref: '#/components/schemas/type_attachments_SendAttachment' description: Attachments to include in message. title: SendMessageAttachments type_messages_SendMessageHeaders: type: object additionalProperties: type: string description: Headers to include in message. title: SendMessageHeaders type_messages_SendMessageRequest: type: object properties: labels: $ref: '#/components/schemas/type_messages_MessageLabels' reply_to: $ref: '#/components/schemas/type_messages_SendMessageReplyTo' to: $ref: '#/components/schemas/type_messages_SendMessageTo' cc: $ref: '#/components/schemas/type_messages_SendMessageCc' bcc: $ref: '#/components/schemas/type_messages_SendMessageBcc' subject: $ref: '#/components/schemas/type_messages_MessageSubject' text: $ref: '#/components/schemas/type_messages_MessageText' html: $ref: '#/components/schemas/type_messages_MessageHtml' attachments: $ref: '#/components/schemas/type_messages_SendMessageAttachments' headers: $ref: '#/components/schemas/type_messages_SendMessageHeaders' title: SendMessageRequest type_messages_SendMessageResponse: type: object properties: message_id: $ref: '#/components/schemas/type_messages_MessageId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' required: - message_id - thread_id title: SendMessageResponse type_messages_ReplyAll: type: boolean description: Reply to all recipients of the original message. title: ReplyAll type_messages_ReplyToMessageRequest: type: object properties: labels: $ref: '#/components/schemas/type_messages_MessageLabels' reply_to: $ref: '#/components/schemas/type_messages_SendMessageReplyTo' to: $ref: '#/components/schemas/type_messages_SendMessageTo' cc: $ref: '#/components/schemas/type_messages_SendMessageCc' bcc: $ref: '#/components/schemas/type_messages_SendMessageBcc' reply_all: $ref: '#/components/schemas/type_messages_ReplyAll' text: $ref: '#/components/schemas/type_messages_MessageText' html: $ref: '#/components/schemas/type_messages_MessageHtml' attachments: $ref: '#/components/schemas/type_messages_SendMessageAttachments' headers: $ref: '#/components/schemas/type_messages_SendMessageHeaders' title: ReplyToMessageRequest type_messages_ReplyAllMessageRequest: type: object properties: labels: $ref: '#/components/schemas/type_messages_MessageLabels' reply_to: $ref: '#/components/schemas/type_messages_SendMessageReplyTo' text: $ref: '#/components/schemas/type_messages_MessageText' html: $ref: '#/components/schemas/type_messages_MessageHtml' attachments: $ref: '#/components/schemas/type_messages_SendMessageAttachments' headers: $ref: '#/components/schemas/type_messages_SendMessageHeaders' title: ReplyAllMessageRequest type_drafts_DraftId: type: string description: ID of draft. title: DraftId type_drafts_DraftLabels: type: array items: type: string description: Labels of draft. title: DraftLabels type_drafts_DraftTo: type: array items: type: string description: Addresses of recipients. In format `username@domain.com` or `Display Name `. title: DraftTo type_drafts_DraftCc: type: array items: type: string description: Addresses of CC recipients. In format `username@domain.com` or `Display Name `. title: DraftCc type_drafts_DraftBcc: type: array items: type: string description: Addresses of BCC recipients. In format `username@domain.com` or `Display Name `. title: DraftBcc type_drafts_DraftSubject: type: string description: Subject of draft. title: DraftSubject type_drafts_DraftPreview: type: string description: Text preview of draft. title: DraftPreview type_drafts_DraftAttachments: type: array items: $ref: '#/components/schemas/type_attachments_Attachment' description: Attachments in draft. title: DraftAttachments type_drafts_DraftInReplyTo: type: string description: ID of message being replied to. title: DraftInReplyTo type_drafts_DraftSendStatus: type: string enum: - scheduled - sending - failed description: Schedule send status of draft. title: DraftSendStatus type_drafts_DraftSendAt: type: string format: date-time description: Time at which to schedule send draft. title: DraftSendAt type_drafts_DraftUpdatedAt: type: string format: date-time description: Time at which draft was last updated. title: DraftUpdatedAt type_drafts_DraftItem: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' draft_id: $ref: '#/components/schemas/type_drafts_DraftId' labels: $ref: '#/components/schemas/type_drafts_DraftLabels' to: $ref: '#/components/schemas/type_drafts_DraftTo' cc: $ref: '#/components/schemas/type_drafts_DraftCc' bcc: $ref: '#/components/schemas/type_drafts_DraftBcc' subject: $ref: '#/components/schemas/type_drafts_DraftSubject' preview: $ref: '#/components/schemas/type_drafts_DraftPreview' attachments: $ref: '#/components/schemas/type_drafts_DraftAttachments' in_reply_to: $ref: '#/components/schemas/type_drafts_DraftInReplyTo' send_status: $ref: '#/components/schemas/type_drafts_DraftSendStatus' send_at: $ref: '#/components/schemas/type_drafts_DraftSendAt' updated_at: $ref: '#/components/schemas/type_drafts_DraftUpdatedAt' required: - inbox_id - draft_id - labels - updated_at title: DraftItem type_drafts_ListDraftsResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' drafts: type: array items: $ref: '#/components/schemas/type_drafts_DraftItem' description: Ordered by `updated_at` descending. required: - count - drafts title: ListDraftsResponse type_drafts_DraftClientId: type: string description: Client ID of draft. title: DraftClientId type_drafts_DraftReplyTo: type: array items: type: string description: Reply-to addresses. In format `username@domain.com` or `Display Name `. title: DraftReplyTo type_drafts_DraftText: type: string description: Plain text body of draft. title: DraftText type_drafts_DraftHtml: type: string description: HTML body of draft. title: DraftHtml type_drafts_Draft: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' draft_id: $ref: '#/components/schemas/type_drafts_DraftId' client_id: $ref: '#/components/schemas/type_drafts_DraftClientId' labels: $ref: '#/components/schemas/type_drafts_DraftLabels' reply_to: $ref: '#/components/schemas/type_drafts_DraftReplyTo' to: $ref: '#/components/schemas/type_drafts_DraftTo' cc: $ref: '#/components/schemas/type_drafts_DraftCc' bcc: $ref: '#/components/schemas/type_drafts_DraftBcc' subject: $ref: '#/components/schemas/type_drafts_DraftSubject' preview: $ref: '#/components/schemas/type_drafts_DraftPreview' text: $ref: '#/components/schemas/type_drafts_DraftText' html: $ref: '#/components/schemas/type_drafts_DraftHtml' attachments: $ref: '#/components/schemas/type_drafts_DraftAttachments' in_reply_to: $ref: '#/components/schemas/type_drafts_DraftInReplyTo' references: type: array items: type: string description: IDs of previous messages in thread. send_status: $ref: '#/components/schemas/type_drafts_DraftSendStatus' send_at: $ref: '#/components/schemas/type_drafts_DraftSendAt' updated_at: $ref: '#/components/schemas/type_drafts_DraftUpdatedAt' created_at: type: string format: date-time description: Time at which draft was created. required: - inbox_id - draft_id - labels - updated_at - created_at title: Draft type_drafts_CreateDraftRequest: type: object properties: labels: $ref: '#/components/schemas/type_drafts_DraftLabels' reply_to: $ref: '#/components/schemas/type_drafts_DraftReplyTo' to: $ref: '#/components/schemas/type_drafts_DraftTo' cc: $ref: '#/components/schemas/type_drafts_DraftCc' bcc: $ref: '#/components/schemas/type_drafts_DraftBcc' subject: $ref: '#/components/schemas/type_drafts_DraftSubject' text: $ref: '#/components/schemas/type_drafts_DraftText' html: $ref: '#/components/schemas/type_drafts_DraftHtml' attachments: type: array items: $ref: '#/components/schemas/type_attachments_SendAttachment' description: Attachments to include in draft. in_reply_to: $ref: '#/components/schemas/type_drafts_DraftInReplyTo' send_at: $ref: '#/components/schemas/type_drafts_DraftSendAt' client_id: $ref: '#/components/schemas/type_drafts_DraftClientId' title: CreateDraftRequest type_drafts_UpdateDraftRequest: type: object properties: reply_to: $ref: '#/components/schemas/type_drafts_DraftReplyTo' to: $ref: '#/components/schemas/type_drafts_DraftTo' cc: $ref: '#/components/schemas/type_drafts_DraftCc' bcc: $ref: '#/components/schemas/type_drafts_DraftBcc' subject: $ref: '#/components/schemas/type_drafts_DraftSubject' text: $ref: '#/components/schemas/type_drafts_DraftText' html: $ref: '#/components/schemas/type_drafts_DraftHtml' send_at: $ref: '#/components/schemas/type_drafts_DraftSendAt' title: UpdateDraftRequest type_lists_Direction: type: string enum: - send - receive - reply description: Direction of list entry. title: Direction type_lists_ListType: type: string enum: - allow - block description: Type of list entry. title: ListType type__OrganizationId: type: string description: ID of organization. title: OrganizationId type_lists_EntryType: type: string enum: - email - domain description: Whether the entry is an email address or domain. title: EntryType type_lists_PodListEntry: type: object properties: entry: type: string description: Email address or domain of list entry. organization_id: $ref: '#/components/schemas/type__OrganizationId' reason: type: string description: Reason for adding the entry. direction: $ref: '#/components/schemas/type_lists_Direction' list_type: $ref: '#/components/schemas/type_lists_ListType' entry_type: $ref: '#/components/schemas/type_lists_EntryType' created_at: type: string format: date-time description: Time at which entry was created. read_only: type: boolean description: Whether the entry is read-only and cannot be deleted via the API. pod_id: type: string description: ID of pod. inbox_id: type: string description: ID of inbox, if entry is inbox-scoped. required: - entry - organization_id - direction - list_type - entry_type - created_at - pod_id title: PodListEntry type_lists_PodListListEntriesResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' entries: type: array items: $ref: '#/components/schemas/type_lists_PodListEntry' description: Ordered by entry ascending. required: - count - entries title: PodListListEntriesResponse type_lists_CreateListEntryRequest: type: object properties: entry: type: string description: Email address or domain to add. reason: type: string description: Reason for adding the entry. required: - entry title: CreateListEntryRequest type_metrics_MetricEventType: type: string enum: - message.sent - message.delivered - message.bounced - message.delayed - message.rejected - message.complained - message.received description: Type of metric event. title: MetricEventType type_metrics_MetricEventTypes: type: array items: $ref: '#/components/schemas/type_metrics_MetricEventType' description: List of metric event types to query. title: MetricEventTypes type_metrics_Start: type: string format: date-time description: Start timestamp for the query. title: Start type_metrics_End: type: string format: date-time description: End timestamp for the query. title: End type_metrics_Period: type: string description: Period in number of seconds for the query. title: Period type_metrics_MetricLimit: type: integer description: Limit on number of buckets to return. title: MetricLimit type_metrics_Descending: type: boolean description: Sort in descending order. title: Descending type_metrics_MetricBucket: type: object properties: timestamp: type: string format: date-time description: Timestamp of the bucket. count: type: integer description: Count of events in the bucket. required: - timestamp - count title: MetricBucket type_metrics_QueryMetricsResponse: type: object additionalProperties: type: array items: $ref: '#/components/schemas/type_metrics_MetricBucket' description: Metrics grouped by event type. title: QueryMetricsResponse type_inbox-events_InboxEventId: type: string description: ID of event. title: InboxEventId type_inbox-events_InboxEventType: type: string enum: - label.added - label.removed description: |- Type of inbox event. Wire format is dot.case to match the convention used by webhook events (`message.received`, `domain.verified`, etc. in events.yml). Pre-2026-04 these were `label_added`/`label_removed` (snake_case). The Fern enum's `name` field stays uppercase-snake (Fern convention); only the wire `value` changed. title: InboxEventType type_inbox-events_InboxEvent: type: object properties: organization_id: $ref: '#/components/schemas/type__OrganizationId' pod_id: type: string description: ID of pod. inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' event_id: $ref: '#/components/schemas/type_inbox-events_InboxEventId' event_type: $ref: '#/components/schemas/type_inbox-events_InboxEventType' message_id: type: string description: ID of message. label: type: string description: Label added or removed. event_at: type: string format: date-time description: Time at which the event occurred. created_at: type: string format: date-time description: Time at which the event was recorded. required: - organization_id - pod_id - inbox_id - event_id - event_type - message_id - label - event_at - created_at title: InboxEvent type_inbox-events_ListInboxEventsResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' events: type: array items: $ref: '#/components/schemas/type_inbox-events_InboxEvent' description: Ordered by `event_id` descending. required: - count - events title: ListInboxEventsResponse type_api-keys_ApiKeyId: type: string description: ID of api key. title: ApiKeyId type_api-keys_Prefix: type: string description: Prefix of api key. title: Prefix type_api-keys_Name: type: string description: Name of api key. title: Name type_api-keys_ApiKeyPermissions: type: object properties: inbox_read: type: boolean description: Read inbox details. inbox_create: type: boolean description: Create new inboxes. inbox_update: type: boolean description: Update inbox settings. inbox_delete: type: boolean description: Delete inboxes. thread_read: type: boolean description: Read threads. thread_delete: type: boolean description: Delete threads. message_read: type: boolean description: Read messages. message_send: type: boolean description: Send messages. message_update: type: boolean description: Update message labels. label_spam_read: type: boolean description: Access messages labeled spam. label_blocked_read: type: boolean description: Access messages labeled blocked. label_trash_read: type: boolean description: Access messages labeled trash. draft_read: type: boolean description: Read drafts. draft_create: type: boolean description: Create drafts. draft_update: type: boolean description: Update drafts. draft_delete: type: boolean description: Delete drafts. draft_send: type: boolean description: Send drafts. webhook_read: type: boolean description: Read webhook configurations. webhook_create: type: boolean description: Create webhooks. webhook_update: type: boolean description: Update webhooks. webhook_delete: type: boolean description: Delete webhooks. domain_read: type: boolean description: Read domain details. domain_create: type: boolean description: Create domains. domain_update: type: boolean description: Update domains. domain_delete: type: boolean description: Delete domains. list_entry_read: type: boolean description: Read list entries. list_entry_create: type: boolean description: Create list entries. list_entry_delete: type: boolean description: Delete list entries. metrics_read: type: boolean description: Read metrics. api_key_read: type: boolean description: Read API keys. api_key_create: type: boolean description: Create API keys. api_key_delete: type: boolean description: Delete API keys. pod_read: type: boolean description: Read pods. pod_create: type: boolean description: Create pods. pod_delete: type: boolean description: Delete pods. description: Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted. title: ApiKeyPermissions type_api-keys_CreatedAt: type: string format: date-time description: Time at which api key was created. title: CreatedAt type_api-keys_ApiKey: type: object properties: api_key_id: $ref: '#/components/schemas/type_api-keys_ApiKeyId' prefix: $ref: '#/components/schemas/type_api-keys_Prefix' name: $ref: '#/components/schemas/type_api-keys_Name' pod_id: type: string description: Pod ID the api key is scoped to. If set, the key can only access resources within this pod. inbox_id: type: string description: Inbox ID the api key is scoped to. If set, the key can only access resources within this inbox. used_at: type: string format: date-time description: Time at which api key was last used. permissions: $ref: '#/components/schemas/type_api-keys_ApiKeyPermissions' created_at: $ref: '#/components/schemas/type_api-keys_CreatedAt' required: - api_key_id - prefix - name - created_at title: ApiKey type_api-keys_ListApiKeysResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' next_page_token: $ref: '#/components/schemas/type__PageToken' api_keys: type: array items: $ref: '#/components/schemas/type_api-keys_ApiKey' description: Ordered by `created_at` descending. required: - count - api_keys title: ListApiKeysResponse type_api-keys_CreateApiKeyRequest: type: object properties: name: $ref: '#/components/schemas/type_api-keys_Name' permissions: $ref: '#/components/schemas/type_api-keys_ApiKeyPermissions' title: CreateApiKeyRequest type_api-keys_CreateApiKeyResponse: type: object properties: api_key_id: $ref: '#/components/schemas/type_api-keys_ApiKeyId' api_key: type: string description: API key. prefix: $ref: '#/components/schemas/type_api-keys_Prefix' name: $ref: '#/components/schemas/type_api-keys_Name' pod_id: type: string description: Pod ID the api key is scoped to. inbox_id: type: string description: Inbox ID the api key is scoped to. permissions: $ref: '#/components/schemas/type_api-keys_ApiKeyPermissions' created_at: $ref: '#/components/schemas/type_api-keys_CreatedAt' required: - api_key_id - api_key - prefix - name - created_at title: CreateApiKeyResponse type_webhooks_WebhookId: type: string description: ID of webhook. title: WebhookId type_webhooks_Url: type: string description: URL of webhook endpoint. title: Url type_events_EventType: type: string enum: - message.received - message.received.spam - message.received.blocked - message.received.unauthenticated - message.sent - message.delivered - message.bounced - message.complained - message.rejected - domain.verified title: EventType type_events_EventTypes: type: array items: $ref: '#/components/schemas/type_events_EventType' description: Event types for which to send events. title: EventTypes type_events_PodIds: type: array items: type: string description: Pods for which to send events. Maximum 10 per webhook. title: PodIds type_events_InboxIds: type: array items: type: string description: Inboxes for which to send events. Maximum 10 per webhook. title: InboxIds type_webhooks_ClientId: type: string description: Client ID of webhook. title: ClientId type_webhooks_Webhook: type: object properties: webhook_id: $ref: '#/components/schemas/type_webhooks_WebhookId' url: $ref: '#/components/schemas/type_webhooks_Url' event_types: $ref: '#/components/schemas/type_events_EventTypes' pod_ids: $ref: '#/components/schemas/type_events_PodIds' inbox_ids: $ref: '#/components/schemas/type_events_InboxIds' secret: type: string description: Secret for webhook signature verification. enabled: type: boolean description: Webhook is enabled. updated_at: type: string format: date-time description: Time at which webhook was last updated. created_at: type: string format: date-time description: Time at which webhook was created. client_id: $ref: '#/components/schemas/type_webhooks_ClientId' required: - webhook_id - url - secret - enabled - updated_at - created_at title: Webhook type_webhooks_ListWebhooksResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' webhooks: type: array items: $ref: '#/components/schemas/type_webhooks_Webhook' description: Ordered by `created_at` descending. required: - count - webhooks title: ListWebhooksResponse type_webhooks_CreateWebhookRequest: type: object properties: url: $ref: '#/components/schemas/type_webhooks_Url' event_types: $ref: '#/components/schemas/type_events_EventTypes' description: |- Full list of event types this webhook should receive. At least one type is required. Send every type you want in this array (not incremental). See [Webhooks overview](https://docs.agentmail.to/webhooks-overview) for spam, blocked, and unauthenticated events and required permissions. pod_ids: $ref: '#/components/schemas/type_events_PodIds' inbox_ids: $ref: '#/components/schemas/type_events_InboxIds' client_id: $ref: '#/components/schemas/type_webhooks_ClientId' required: - url - event_types title: CreateWebhookRequest type_webhooks_UpdateWebhookRequest: type: object properties: add_inbox_ids: $ref: '#/components/schemas/type_events_InboxIds' description: Inbox IDs to subscribe to the webhook. remove_inbox_ids: $ref: '#/components/schemas/type_events_InboxIds' description: Inbox IDs to unsubscribe from the webhook. add_pod_ids: $ref: '#/components/schemas/type_events_PodIds' description: Pod IDs to subscribe to the webhook. remove_pod_ids: $ref: '#/components/schemas/type_events_PodIds' description: Pod IDs to unsubscribe from the webhook. event_types: $ref: '#/components/schemas/type_events_EventTypes' description: |- When you send a non-empty list, it replaces the webhook's subscribed event types in full (the same "set the list" behavior as create). It is not a merge or diff: include every event type you want after the update. Sending a one-element array means the webhook will only receive that one type afterward. Omit this field or send an empty array to leave event types unchanged. Clearing all types with an empty list is not supported. Subscribing to `message.received.spam`, `message.received.blocked`, or `message.received.unauthenticated` requires the matching label permission on the API key. title: UpdateWebhookRequest type_domains_DomainId: type: string description: The ID of the domain. title: DomainId type_domains_DomainName: type: string description: The name of the domain (e.g., `example.com`). title: DomainName type_domains_FeedbackEnabled: type: boolean description: Bounce and complaint notifications are sent to your inboxes. title: FeedbackEnabled type_domains_ClientId: type: string description: Client ID of domain. title: ClientId type_domains_DomainItem: type: object properties: pod_id: $ref: '#/components/schemas/type_pods_PodId' domain_id: $ref: '#/components/schemas/type_domains_DomainId' domain: $ref: '#/components/schemas/type_domains_DomainName' feedback_enabled: $ref: '#/components/schemas/type_domains_FeedbackEnabled' client_id: $ref: '#/components/schemas/type_domains_ClientId' updated_at: type: string format: date-time description: Time at which the domain was last updated. created_at: type: string format: date-time description: Time at which the domain was created. required: - domain_id - domain - feedback_enabled - updated_at - created_at title: DomainItem type_domains_ListDomainsResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' domains: type: array items: $ref: '#/components/schemas/type_domains_DomainItem' description: Ordered by `created_at` descending. required: - count - domains title: ListDomainsResponse type_domains_VerificationStatus: type: string enum: - NOT_STARTED - PENDING - INVALID - FAILED - VERIFYING - VERIFIED title: VerificationStatus type_domains_Status: $ref: '#/components/schemas/type_domains_VerificationStatus' description: The verification status of the domain. title: Status type_domains_RecordType: type: string enum: - TXT - CNAME - MX title: RecordType type_domains_RecordStatus: type: string enum: - MISSING - INVALID - VALID title: RecordStatus type_domains_VerificationRecord: type: object properties: type: $ref: '#/components/schemas/type_domains_RecordType' description: The type of the DNS record. name: type: string description: The name or host of the record. value: type: string description: The value of the record. status: $ref: '#/components/schemas/type_domains_RecordStatus' description: The verification status of this specific record. priority: type: integer description: The priority of the MX record. required: - type - name - value - status title: VerificationRecord type_domains_Domain: type: object properties: pod_id: $ref: '#/components/schemas/type_pods_PodId' domain_id: $ref: '#/components/schemas/type_domains_DomainId' domain: $ref: '#/components/schemas/type_domains_DomainName' status: $ref: '#/components/schemas/type_domains_Status' feedback_enabled: $ref: '#/components/schemas/type_domains_FeedbackEnabled' records: type: array items: $ref: '#/components/schemas/type_domains_VerificationRecord' description: A list of DNS records required to verify the domain. client_id: $ref: '#/components/schemas/type_domains_ClientId' updated_at: type: string format: date-time description: Time at which the domain was last updated. created_at: type: string format: date-time description: Time at which the domain was created. required: - domain_id - domain - status - feedback_enabled - records - updated_at - created_at title: Domain type_domains_CreateDomainRequest: type: object properties: domain: $ref: '#/components/schemas/type_domains_DomainName' feedback_enabled: $ref: '#/components/schemas/type_domains_FeedbackEnabled' required: - domain - feedback_enabled title: CreateDomainRequest type_domains_UpdateDomainRequest: type: object properties: feedback_enabled: $ref: '#/components/schemas/type_domains_FeedbackEnabled' title: UpdateDomainRequest type_lists_ListEntry: type: object properties: entry: type: string description: Email address or domain of list entry. organization_id: $ref: '#/components/schemas/type__OrganizationId' reason: type: string description: Reason for adding the entry. direction: $ref: '#/components/schemas/type_lists_Direction' list_type: $ref: '#/components/schemas/type_lists_ListType' entry_type: $ref: '#/components/schemas/type_lists_EntryType' created_at: type: string format: date-time description: Time at which entry was created. read_only: type: boolean description: Whether the entry is read-only and cannot be deleted via the API. required: - entry - organization_id - direction - list_type - entry_type - created_at title: ListEntry type_lists_ListListEntriesResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' entries: type: array items: $ref: '#/components/schemas/type_lists_ListEntry' description: Ordered by entry ascending. required: - count - entries title: ListListEntriesResponse type_pods_Name: type: string description: Name of pod. title: Name type_pods_ClientId: type: string description: Client ID of pod. title: ClientId type_pods_Pod: type: object properties: pod_id: $ref: '#/components/schemas/type_pods_PodId' name: $ref: '#/components/schemas/type_pods_Name' updated_at: type: string format: date-time description: Time at which pod was last updated. created_at: type: string format: date-time description: Time at which pod was created. client_id: $ref: '#/components/schemas/type_pods_ClientId' required: - pod_id - name - updated_at - created_at title: Pod type_pods_ListPodsResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' pods: type: array items: $ref: '#/components/schemas/type_pods_Pod' description: Ordered by `created_at` descending. required: - count - pods title: ListPodsResponse type_pods_CreatePodRequest: type: object properties: name: $ref: '#/components/schemas/type_pods_Name' client_id: $ref: '#/components/schemas/type_pods_ClientId' title: CreatePodRequest type_organizations_Organization: type: object properties: organization_id: $ref: '#/components/schemas/type__OrganizationId' inbox_count: type: integer description: Current number of inboxes. domain_count: type: integer description: Current number of domains. inbox_limit: type: integer description: Maximum number of inboxes allowed. domain_limit: type: integer description: Maximum number of domains allowed. billing_id: type: string description: Provider-agnostic billing customer ID. billing_type: type: string description: Billing provider type (e.g. "stripe"). billing_subscription_id: type: string description: Active billing subscription ID. authentication_id: type: string description: Provider-agnostic authentication ID. authentication_type: type: string description: Authentication provider type. updated_at: type: string format: date-time description: Time at which organization was last updated. created_at: type: string format: date-time description: Time at which organization was created. required: - organization_id - inbox_count - domain_count - updated_at - created_at description: Organization details with usage limits and counts. title: Organization type_webhooks_events_SvixId: type: string description: ID of webhook message. title: SvixId type_webhooks_events_SvixSignature: type: string description: Signature of webhook message. title: SvixSignature type_webhooks_events_SvixTimestamp: type: string format: date-time description: Timestamp of webhook message. title: SvixTimestamp type_events_MessageReceivedEventType: type: string enum: - message.received - message.received.spam - message.received.blocked - message.received.unauthenticated title: MessageReceivedEventType type_events_EventId: type: string description: ID of event. title: EventId type_events_MessageReceivedEvent: type: object properties: type: type: string enum: - event event_type: $ref: '#/components/schemas/type_events_MessageReceivedEventType' event_id: $ref: '#/components/schemas/type_events_EventId' message: $ref: '#/components/schemas/type_messages_Message' thread: $ref: '#/components/schemas/type_threads_ThreadItem' required: - type - event_type - event_id - message - thread description: A message was received. Spam, blocked, and unauthenticated received-message events use the same payload shape with different `event_type` values. title: MessageReceivedEvent type_events_Timestamp: type: string format: date-time description: Timestamp of event. title: Timestamp type_events_Send: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' timestamp: $ref: '#/components/schemas/type_events_Timestamp' recipients: type: array items: type: string description: Sent recipients. required: - inbox_id - thread_id - message_id - timestamp - recipients title: Send type_events_MessageSentEvent: type: object properties: type: type: string enum: - event event_type: type: string enum: - message.sent event_id: $ref: '#/components/schemas/type_events_EventId' send: $ref: '#/components/schemas/type_events_Send' required: - type - event_type - event_id - send title: MessageSentEvent type_events_Delivery: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' timestamp: $ref: '#/components/schemas/type_events_Timestamp' recipients: type: array items: type: string description: Delivered recipients. required: - inbox_id - thread_id - message_id - timestamp - recipients title: Delivery type_events_MessageDeliveredEvent: type: object properties: type: type: string enum: - event event_type: type: string enum: - message.delivered event_id: $ref: '#/components/schemas/type_events_EventId' delivery: $ref: '#/components/schemas/type_events_Delivery' required: - type - event_type - event_id - delivery title: MessageDeliveredEvent type_events_Recipient: type: object properties: address: type: string description: Recipient address. status: type: string description: Recipient status. required: - address - status title: Recipient type_events_Bounce: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' timestamp: $ref: '#/components/schemas/type_events_Timestamp' type: type: string description: Bounce type. sub_type: type: string description: Bounce sub-type. recipients: type: array items: $ref: '#/components/schemas/type_events_Recipient' description: Bounced recipients. required: - inbox_id - thread_id - message_id - timestamp - type - sub_type - recipients title: Bounce type_events_MessageBouncedEvent: type: object properties: type: type: string enum: - event event_type: type: string enum: - message.bounced event_id: $ref: '#/components/schemas/type_events_EventId' bounce: $ref: '#/components/schemas/type_events_Bounce' required: - type - event_type - event_id - bounce title: MessageBouncedEvent type_events_Complaint: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' timestamp: $ref: '#/components/schemas/type_events_Timestamp' type: type: string description: Complaint type. sub_type: type: string description: Complaint sub-type. recipients: type: array items: type: string description: Complained recipients. required: - inbox_id - thread_id - message_id - timestamp - type - sub_type - recipients title: Complaint type_events_MessageComplainedEvent: type: object properties: type: type: string enum: - event event_type: type: string enum: - message.complained event_id: $ref: '#/components/schemas/type_events_EventId' complaint: $ref: '#/components/schemas/type_events_Complaint' required: - type - event_type - event_id - complaint title: MessageComplainedEvent type_events_Reject: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' timestamp: $ref: '#/components/schemas/type_events_Timestamp' reason: type: string description: Reject reason. required: - inbox_id - thread_id - message_id - timestamp - reason title: Reject type_events_MessageRejectedEvent: type: object properties: type: type: string enum: - event event_type: type: string enum: - message.rejected event_id: $ref: '#/components/schemas/type_events_EventId' reject: $ref: '#/components/schemas/type_events_Reject' required: - type - event_type - event_id - reject title: MessageRejectedEvent type_events_DomainVerifiedEvent: type: object properties: type: type: string enum: - event event_type: type: string enum: - domain.verified event_id: $ref: '#/components/schemas/type_events_EventId' domain: $ref: '#/components/schemas/type_domains_Domain' required: - type - event_type - event_id - domain title: DomainVerifiedEvent type__Query: type: string description: |- Full-text search query. Matched against the sender, recipients, and subject (substring) and the message body (tokenized full text). title: Query type_threads_SearchThreadsResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' threads: type: array items: $ref: '#/components/schemas/type_threads_SearchThreadItem' description: Ordered by relevance, best match first. required: - count - threads title: SearchThreadsResponse type_messages_SearchMessagesResponse: type: object properties: count: $ref: '#/components/schemas/type__Count' limit: $ref: '#/components/schemas/type__Limit' next_page_token: $ref: '#/components/schemas/type__PageToken' messages: type: array items: $ref: '#/components/schemas/type_messages_SearchMessageItem' description: Ordered by relevance, best match first. required: - count - messages title: SearchMessagesResponse type_threads_SearchThreadItem: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' labels: $ref: '#/components/schemas/type_threads_ThreadLabels' timestamp: $ref: '#/components/schemas/type_threads_ThreadTimestamp' received_timestamp: $ref: '#/components/schemas/type_threads_ThreadReceivedTimestamp' sent_timestamp: $ref: '#/components/schemas/type_threads_ThreadSentTimestamp' senders: $ref: '#/components/schemas/type_threads_ThreadSenders' recipients: $ref: '#/components/schemas/type_threads_ThreadRecipients' subject: $ref: '#/components/schemas/type_threads_ThreadSubject' preview: $ref: '#/components/schemas/type_threads_ThreadPreview' attachments: $ref: '#/components/schemas/type_threads_ThreadAttachments' last_message_id: $ref: '#/components/schemas/type_threads_ThreadLastMessageId' message_count: $ref: '#/components/schemas/type_threads_ThreadMessageCount' size: $ref: '#/components/schemas/type_threads_ThreadSize' updated_at: $ref: '#/components/schemas/type_threads_ThreadUpdatedAt' created_at: $ref: '#/components/schemas/type_threads_ThreadCreatedAt' highlights: $ref: '#/components/schemas/type_threads_SearchThreadHighlights' description: Matched fragments per field. Present only when the query matched an indexed field. required: - inbox_id - thread_id - labels - timestamp - senders - recipients - last_message_id - message_count - size - updated_at - created_at title: SearchThreadItem type_messages_SearchMessageItem: type: object properties: inbox_id: $ref: '#/components/schemas/type_inboxes_InboxId' thread_id: $ref: '#/components/schemas/type_threads_ThreadId' message_id: $ref: '#/components/schemas/type_messages_MessageId' labels: $ref: '#/components/schemas/type_messages_MessageLabels' timestamp: $ref: '#/components/schemas/type_messages_MessageTimestamp' from: $ref: '#/components/schemas/type_messages_MessageFrom' to: $ref: '#/components/schemas/type_messages_MessageTo' cc: $ref: '#/components/schemas/type_messages_MessageCc' bcc: $ref: '#/components/schemas/type_messages_MessageBcc' subject: $ref: '#/components/schemas/type_messages_MessageSubject' preview: $ref: '#/components/schemas/type_messages_MessagePreview' attachments: $ref: '#/components/schemas/type_messages_MessageAttachments' in_reply_to: $ref: '#/components/schemas/type_messages_MessageInReplyTo' references: $ref: '#/components/schemas/type_messages_MessageReferences' headers: $ref: '#/components/schemas/type_messages_MessageHeaders' size: $ref: '#/components/schemas/type_messages_MessageSize' updated_at: $ref: '#/components/schemas/type_messages_MessageUpdatedAt' created_at: $ref: '#/components/schemas/type_messages_MessageCreatedAt' highlights: $ref: '#/components/schemas/type_messages_SearchMessageHighlights' description: Matched fragments per field. Present only when the query matched an indexed field. required: - inbox_id - thread_id - message_id - labels - timestamp - from - to - size - updated_at - created_at title: SearchMessageItem type_threads_SearchThreadHighlights: type: object properties: from: type: array items: type: string description: Matched fragments from a sender address in the thread. recipients: type: array items: type: string description: Matched fragments from a recipient address in the thread (to, cc, or bcc). subject: type: array items: type: string description: Matched fragments from the subject. text: type: array items: type: string description: Matched fragments from a message body in the thread. description: |- Matched fragments per field on a thread search result, with matched terms wrapped in `**`. A field key is present only when the query matched that field, so the present keys also tell you which fields produced the hit. title: SearchThreadHighlights type_messages_SearchMessageHighlights: type: object properties: from: type: array items: type: string description: Matched fragments from the sender address. recipients: type: array items: type: string description: Matched fragments from the recipient addresses (to, cc, or bcc). subject: type: array items: type: string description: Matched fragments from the subject. text: type: array items: type: string description: Matched fragments from the message body. description: |- Matched fragments per field on a message search result, with matched terms wrapped in `**`. A field key is present only when the query matched that field, so the present keys also tell you which fields produced the hit. title: SearchMessageHighlights AnalystEstimatesResponse: type: object properties: analyst_estimates: type: array items: $ref: '#/components/schemas/AnalystEstimate' AnalystEstimate: type: object properties: fiscal_period: type: string format: date description: The fiscal period of the analyst estimate. period: type: string enum: - annual - quarterly description: The period of the analyst estimate. revenue: type: integer description: The estimated revenue. earnings_per_share: type: number description: The estimated earnings per share. ErrorResponse: type: object properties: error: type: string description: A short error message. message: type: string description: A more detailed error message. CoinsContractAddressDataBase: type: object properties: id: type: string description: coin ID symbol: type: string description: coin symbol name: type: string description: coin name web_slug: type: string description: coin web slug asset_platform_id: type: string description: coin asset platform ID platforms: type: object description: coin asset platform and contract address additionalProperties: type: string nullable: true detail_platforms: type: object description: detailed coin asset platform and contract address additionalProperties: type: object properties: decimal_place: type: number nullable: true contract_address: type: string block_time_in_minutes: type: number description: blockchain block time in minutes hashing_algorithm: type: string nullable: true description: blockchain hashing algorithm categories: type: array description: coin categories items: type: string preview_listing: type: boolean description: preview listing coin public_notice: type: string nullable: true description: public notice additional_notices: type: array description: additional notices items: type: string localization: type: object description: coin name localization additionalProperties: type: string description: type: object description: coin description additionalProperties: type: string links: type: object description: links properties: homepage: type: array description: coin website url items: type: string whitepaper: type: string description: coin whitepaper url blockchain_site: type: array description: coin block explorer url items: type: string official_forum_url: type: array description: coin official forum url items: type: string chat_url: type: array description: coin chat url items: type: string announcement_url: type: array description: coin announcement url items: type: string snapshot_url: type: string description: coin snapshot url nullable: true twitter_screen_name: type: string description: coin twitter handle facebook_username: type: string description: coin facebook username bitcointalk_thread_identifier: type: string description: coin bitcointalk thread identifier nullable: true telegram_channel_identifier: type: string description: coin telegram channel identifier subreddit_url: type: string description: coin subreddit url nullable: true repos_url: type: object description: coin repository url properties: github: type: array description: coin github repository url items: type: string bitbucket: type: array description: coin bitbucket repository url items: type: string image: type: object description: coin image url properties: thumb: type: string small: type: string large: type: string country_origin: type: string description: coin country of origin genesis_date: type: string nullable: true description: coin genesis date format: date-time contract_address: type: string description: coin contract address sentiment_votes_up_percentage: type: number description: coin sentiment votes up percentage sentiment_votes_down_percentage: type: number description: coin sentiment votes down percentage watchlist_portfolio_users: type: number description: number of users watching this coin in portfolio market_cap_rank: type: number description: coin rank by market cap market_cap_rank_with_rehypothecated: type: number description: coin rank by market cap including rehypothecated tokens market_data: type: object description: coin market data properties: current_price: type: object description: coin current price in currency properties: btc: type: number eur: type: number usd: type: number total_value_locked: type: number nullable: true description: total value locked mcap_to_tvl_ratio: type: number nullable: true description: market cap to total value locked ratio fdv_to_tvl_ratio: type: number nullable: true description: fully diluted valuation to total value locked ratio roi: type: number nullable: true description: coin return on investment ath: type: object description: coin all time high (ATH) in currency properties: btc: type: number eur: type: number usd: type: number ath_change_percentage: type: object description: coin all time high (ATH) change in percentage properties: btc: type: number eur: type: number usd: type: number ath_date: type: object description: coin all time high (ATH) date properties: btc: type: string eur: type: string usd: type: string atl: type: object description: coin all time low (atl) in currency properties: btc: type: number eur: type: number usd: type: number atl_change_percentage: type: object description: coin all time low (atl) change in percentage properties: btc: type: number eur: type: number usd: type: number atl_date: type: object description: coin all time low (atl) date properties: btc: type: string eur: type: string usd: type: string market_cap: type: object description: coin market cap in currency properties: btc: type: number eur: type: number usd: type: number market_cap_rank: type: number description: coin rank by market cap outstanding_token_value_usd: type: number nullable: true description: outstanding token value in USD market_cap_rank_with_rehypothecated: type: number description: coin rank by market cap including rehypothecated tokens fully_diluted_valuation: type: object description: coin fully diluted valuation (fdv) in currency properties: btc: type: number eur: type: number usd: type: number market_cap_fdv_ratio: type: number description: market cap to fully diluted valuation ratio total_volume: type: object description: coin total trading volume in currency properties: btc: type: number eur: type: number usd: type: number high_24h: type: object description: coin 24hr price high in currency properties: btc: type: number eur: type: number usd: type: number low_24h: type: object description: coin 24hr price low in currency properties: btc: type: number eur: type: number usd: type: number price_change_24h: type: number description: coin 24hr price change in currency price_change_percentage_24h: type: number description: coin 24hr price change in percentage price_change_percentage_7d: type: number description: coin 7d price change in percentage price_change_percentage_14d: type: number description: coin 14d price change in percentage price_change_percentage_30d: type: number description: coin 30d price change in percentage price_change_percentage_60d: type: number description: coin 60d price change in percentage price_change_percentage_200d: type: number description: coin 200d price change in percentage price_change_percentage_1y: type: number description: coin 1y price change in percentage market_cap_change_24h: type: number description: coin 24hr market cap change in currency market_cap_change_percentage_24h: type: number description: coin 24hr market cap change in percentage price_change_24h_in_currency: type: object description: coin 24hr price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_1h_in_currency: type: object description: coin 1h price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_24h_in_currency: type: object description: coin 24hr price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_7d_in_currency: type: object description: coin 7d price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_14d_in_currency: type: object description: coin 14d price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_30d_in_currency: type: object description: coin 30d price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_60d_in_currency: type: object description: coin 60d price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_200d_in_currency: type: object description: coin 200d price change in currency properties: btc: type: number eur: type: number usd: type: number price_change_percentage_1y_in_currency: type: object description: coin 1y price change in currency properties: btc: type: number eur: type: number usd: type: number market_cap_change_24h_in_currency: type: object description: coin 24hr market cap change in currency properties: btc: type: number eur: type: number usd: type: number market_cap_change_percentage_24h_in_currency: type: object description: coin 24hr market cap change in percentage properties: btc: type: number eur: type: number usd: type: number total_supply: type: number description: coin total supply max_supply: type: number nullable: true description: coin max supply max_supply_infinite: type: boolean description: whether max supply is infinite circulating_supply: type: number description: coin circulating supply outstanding_supply: type: number nullable: true description: tokens outstanding in the market, circulated/tradable or planned for circulation last_updated: type: string description: coin market data last updated timestamp format: date-time community_data: type: object description: coin community data properties: facebook_likes: type: number description: coin facebook likes nullable: true reddit_average_posts_48h: type: number description: coin reddit average posts in 48 hours reddit_average_comments_48h: type: number description: coin reddit average comments in 48 hours reddit_subscribers: type: number description: coin reddit subscribers reddit_accounts_active_48h: type: number description: coin reddit active accounts in 48 hours telegram_channel_user_count: type: number description: coin telegram channel user count nullable: true developer_data: type: object description: coin developer data properties: forks: type: number description: coin repository forks stars: type: number description: coin repository stars subscribers: type: number description: coin repository subscribers total_issues: type: number description: coin repository total issues closed_issues: type: number description: coin repository closed issues pull_requests_merged: type: number description: coin repository pull requests merged pull_request_contributors: type: number description: coin repository pull request contributors code_additions_deletions_4_weeks: type: object description: coin code additions and deletions in 4 weeks properties: additions: type: number nullable: true deletions: type: number nullable: true commit_count_4_weeks: type: number description: coin repository commit count in 4 weeks last_4_weeks_commit_activity_series: type: array description: coin repository last 4 weeks commit activity series items: type: number status_updates: type: array description: coin status updates items: type: string last_updated: type: string description: coin last updated timestamp format: date-time tickers: type: array description: coin tickers items: type: object properties: base: type: string description: coin ticker base currency target: type: string description: coin ticker target currency market: type: object description: coin ticker exchange properties: name: type: string description: coin ticker exchange name identifier: type: string description: coin ticker exchange identifier has_trading_incentive: type: boolean description: coin ticker exchange trading incentive last: type: number description: coin ticker last price volume: type: number description: coin ticker volume converted_last: type: object description: coin ticker converted last price properties: btc: type: number eth: type: number usd: type: number converted_volume: type: object description: coin ticker converted volume properties: btc: type: number eth: type: number usd: type: number trust_score: type: string nullable: true description: coin ticker trust score bid_ask_spread_percentage: type: number description: coin ticker bid ask spread percentage timestamp: type: string description: coin ticker timestamp format: date-time last_traded_at: type: string description: coin ticker last traded timestamp format: date-time last_fetch_at: type: string description: coin ticker last fetch timestamp format: date-time is_anomaly: type: boolean description: coin ticker anomaly is_stale: type: boolean description: coin ticker stale trade_url: type: string description: coin ticker trade url nullable: true token_info_url: type: string description: coin ticker token info url nullable: true coin_id: type: string description: coin ticker base currency coin ID target_coin_id: type: string description: coin ticker target currency coin ID coin_mcap_usd: type: number description: coin market cap in USD CoinsContractAddress: allOf: - $ref: '#/components/schemas/CoinsContractAddressDataBase' example: id: usd-coin symbol: usdc name: USDC web_slug: usdc asset_platform_id: ethereum platforms: ethereum: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' polkadot: '1337' flow: A.b19436aae4d94622.FiatToken avalanche: '0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e' optimistic-ethereum: '0x0b2c639c533813f4aa9d7837caf62653d097ff85' stellar: USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN near-protocol: 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 hedera-hashgraph: 0.0.456858 zksync: '0x1d17cbcf0d6d143135ae902365d2e5e2a16538d4' tron: TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 celo: '0xceba9300f2b948710d2653dd7b07f33a8b32118c' arbitrum-one: '0xaf88d065e77c8cc2239327c5edb3a432268e5831' base: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' polygon-pos: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359' solana: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v detail_platforms: ethereum: decimal_place: 6 contract_address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' polkadot: decimal_place: 6 contract_address: '1337' flow: decimal_place: 8 contract_address: A.b19436aae4d94622.FiatToken avalanche: decimal_place: 6 contract_address: '0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e' optimistic-ethereum: decimal_place: 6 contract_address: '0x0b2c639c533813f4aa9d7837caf62653d097ff85' stellar: decimal_place: null contract_address: USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN near-protocol: decimal_place: 6 contract_address: 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 hedera-hashgraph: decimal_place: 6 contract_address: 0.0.456858 zksync: decimal_place: 6 contract_address: '0x1d17cbcf0d6d143135ae902365d2e5e2a16538d4' tron: decimal_place: 6 contract_address: TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 celo: decimal_place: 6 contract_address: '0xceba9300f2b948710d2653dd7b07f33a8b32118c' arbitrum-one: decimal_place: 6 contract_address: '0xaf88d065e77c8cc2239327c5edb3a432268e5831' base: decimal_place: 6 contract_address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' polygon-pos: decimal_place: 6 contract_address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359' solana: decimal_place: 6 contract_address: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v block_time_in_minutes: 0 hashing_algorithm: null categories: - Ronin Ecosystem - Osmosis Ecosystem - Mantle Ecosystem - Kava Ecosystem - Tron Ecosystem - Base Ecosystem - Neon Ecosystem - Hedera Ecosystem - Stellar Ecosystem - Rollux Ecosystem - Stablecoins - USD Stablecoin - BNB Chain Ecosystem - Cosmos Ecosystem - Polkadot Ecosystem - Avalanche Ecosystem - Solana Ecosystem - Gnosis Chain Ecosystem - Near Protocol Ecosystem - Fantom Ecosystem - Moonriver Ecosystem - Polygon Ecosystem - Arbitrum Ecosystem - Harmony Ecosystem - Ethereum Ecosystem - Velas Ecosystem - Arbitrum Nova Ecosystem - Moonbeam Ecosystem - Optimism Ecosystem - Metis Ecosystem - Cronos Ecosystem - Canto Ecosystem - ZkSync Ecosystem preview_listing: false public_notice: USD Coin (USDC) has rebranded to USDC (USDC). For more information, please refer to this announcement from the Circle Blog. additional_notices: [] localization: en: USDC de: USDC es: USDC fr: USDC it: USDC pl: USDC ro: USDC hu: USDC nl: USDC pt: USDC sv: USDC vi: USDC tr: USDC ru: USDC ja: USDコイン zh: USDC zh-tw: USDC ko: USDC ar: USDC th: USDC id: USDC cs: USDC da: USDC el: USDC hi: USDC 'no': USDC sk: USDC uk: USDC he: USDC fi: USDC bg: USDC hr: USDC lt: USDC sl: USDC description: en: USDC is a fully collateralized US dollar stablecoin ... de: USDC is a fully collateralized US dollar stablecoin... links: homepage: - https://www.circle.com/en/usdc - '' - '' whitepaper: '' blockchain_site: - https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - https://bscscan.com/token/0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d - https://nearblocks.io/token/17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1 - https://ethplorer.io/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 - https://arbiscan.io/token/0xaf88d065e77c8cc2239327c5edb3a432268e5831 - https://binplorer.com/address/0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d - https://explorer.kava.io/token/0xfa9343c3897324496a05fc75abed6bac29f8a40f - https://ftmscan.com/token/0x04068da6c83afcfa0e13ba15a6696662335d5b75 - https://explorer.energi.network/token/0xffd7510ca0a3279c7a5f50018a26c21d5bc1dbcf official_forum_url: - '' - '' - '' chat_url: - https://discord.com/invite/buildoncircle - '' - '' announcement_url: - https://medium.com/centre-blog - https://blog.circle.com/2018/09/26/introducing-usd-coin/ snapshot_url: null twitter_screen_name: circle facebook_username: '' bitcointalk_thread_identifier: null telegram_channel_identifier: '' subreddit_url: https://www.reddit.com repos_url: github: - https://github.com/centrehq/centre-tokens bitbucket: [] image: thumb: https://assets.coingecko.com/coins/images/6319/thumb/usdc.png?1696506694 small: https://assets.coingecko.com/coins/images/6319/small/usdc.png?1696506694 large: https://assets.coingecko.com/coins/images/6319/large/usdc.png?1696506694 country_origin: US genesis_date: null contract_address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' sentiment_votes_up_percentage: 33.33 sentiment_votes_down_percentage: 66.67 watchlist_portfolio_users: 126374 market_cap_rank: 7 market_cap_rank_with_rehypothecated: 7 market_data: current_price: aed: 3.68 ars: 863.06 aud: 1.52 bch: 0.00145232 bdt: 109.92 bhd: 0.377611 bmd: 1.003 bnb: 0.00170967 brl: 5.08 btc: 1.429e-05 cad: 1.36 chf: 0.904508 clp: 942.53 cny: 7.25 czk: 23.43 dkk: 6.9 dot: 0.11492405 eos: 0.96236821 eth: 0.00029377 eur: 0.924434 gbp: 0.793567 gel: 2.69 hkd: 7.85 huf: 361.11 idr: 15933.99 ils: 3.76 inr: 83.54 jpy: 152.05 krw: 1355.2 kwd: 0.308189 lkr: 299.48 ltc: 0.00973467 mmk: 2103.16 mxn: 16.5 myr: 4.76 ngn: 1298.4 nok: 10.76 nzd: 1.67 php: 56.75 pkr: 278.35 pln: 3.96 rub: 92.78 sar: 3.76 sek: 10.71 sgd: 1.35 sol: 23.88 thb: 36.73 try: 32.16 twd: 32.22 uah: 38.89 usd: 1.003 vef: 0.100421 vnd: 25038 xag: 0.0364874 xau: 0.00043045 xdr: 0.756423 xlm: 7.701256 xrp: 1.669349 yfi: 0.0001188 zar: 18.75 bits: 14.29 link: 0.05630197 sats: 1428.76 total_value_locked: null mcap_to_tvl_ratio: null fdv_to_tvl_ratio: null roi: null ath: aed: 4.31 ars: 868.65 aud: 1.83 bch: 0.01345435 bdt: 113.46 bhd: 0.442094 bmd: 1.17 bnb: 0.25455702 brl: 5.97 btc: 0.00033582 cad: 1.61 chf: 1.2 clp: 1057.99 cny: 8.09 czk: 27.1 dkk: 7.88 dot: 0.34808619 eos: 1.89444 eth: 0.01282697 eur: 1.059 gbp: 0.96424 gel: 2.74 hkd: 9.2 huf: 455.32 idr: 17341.09 ils: 4.26 inr: 87.19 jpy: 154.07 krw: 1466.8 kwd: 0.356866 lkr: 380.81 ltc: 0.04751509 mmk: 2166.16 mxn: 25.72 myr: 4.95 ngn: 1641.1 nok: 12.06 nzd: 1.88 php: 61.66 pkr: 309.03 pln: 5.09 rub: 155.25 sar: 4.4 sek: 11.61 sgd: 1.47 sol: 26.45 thb: 38.98 try: 32.76 twd: 36.3 uah: 39.61 usd: 1.17 vef: 291403 vnd: 27332 xag: 0.086151 xau: 0.00093093 xdr: 0.842866 xlm: 37.482414 xrp: 9.1105 yfi: 0.00126639 zar: 19.92 bits: 313.39 link: 4.9423 sats: 31339 ath_change_percentage: aed: -14.38389 ars: -0.51451 aud: -16.54715 bch: -89.16472 bdt: -2.99363 bhd: -14.475 bmd: -14.36801 bnb: -99.3281 brl: -14.79026 btc: -95.73352 cad: -15.1066 chf: -24.25592 clp: -10.79724 cny: -10.23969 czk: -13.42505 dkk: -12.26647 dot: -66.90313 eos: -49.11664 eth: -97.70715 eur: -12.61023 gbp: -17.59352 gel: -1.74226 hkd: -14.57313 huf: -20.58833 idr: -7.99505 ils: -11.60085 inr: -4.06203 jpy: -1.18617 krw: -7.48817 kwd: -13.52804 lkr: -21.25532 ltc: -79.49459 mmk: -2.78254 mxn: -35.75175 myr: -3.75781 ngn: -20.77937 nok: -10.67094 nzd: -11.13856 php: -7.84159 pkr: -9.81151 pln: -22.06943 rub: -40.1645 sar: -14.34456 sek: -7.62797 sgd: -7.93611 sol: -9.70201 thb: -5.64291 try: -1.67562 twd: -11.13084 uah: -1.68827 usd: -14.36801 vef: -99.99997 vnd: -8.27313 xag: -57.59221 xau: -53.7014 xdr: -10.13941 xlm: -79.45084 xrp: -81.6335 yfi: -90.62471 zar: -5.73322 bits: -95.42817 link: -98.85859 sats: -95.42817 ath_date: aed: '2019-05-08T00:40:28.300Z' ars: '2024-04-04T18:05:51.232Z' aud: '2020-03-13T02:35:16.858Z' bch: '2018-12-15T16:04:56.312Z' bdt: '2023-10-23T22:45:06.087Z' bhd: '2019-05-08T00:40:28.300Z' bmd: '2019-05-08T00:40:28.300Z' bnb: '2018-12-08T12:49:29.078Z' brl: '2020-05-14T14:07:45.849Z' btc: '2018-12-08T12:54:40.339Z' cad: '2020-03-13T02:35:16.858Z' chf: '2019-05-08T00:40:28.300Z' clp: '2022-07-19T00:53:26.862Z' cny: '2020-03-13T02:35:16.858Z' czk: '2020-03-13T02:35:16.858Z' dkk: '2022-09-27T16:25:08.674Z' dot: '2020-08-22T00:00:00.000Z' eos: '2023-10-19T07:35:20.838Z' eth: '2018-12-08T12:49:29.078Z' eur: '2022-09-27T16:25:08.674Z' gbp: '2022-09-26T01:00:46.182Z' gel: '2024-03-20T20:40:24.283Z' hkd: '2019-05-08T00:40:28.300Z' huf: '2022-10-13T12:54:39.018Z' idr: '2018-10-15T13:29:31.772Z' ils: '2020-03-13T02:35:16.858Z' inr: '2020-03-13T02:35:16.858Z' jpy: '2023-10-23T22:45:06.087Z' krw: '2022-09-30T02:11:16.560Z' kwd: '2019-05-08T00:40:28.300Z' lkr: '2022-05-12T07:24:27.813Z' ltc: '2018-12-08T12:49:29.078Z' mmk: '2022-09-13T12:36:28.482Z' mxn: '2020-04-06T05:20:12.159Z' myr: '2020-03-13T02:35:16.858Z' ngn: '2024-02-28T17:01:26.911Z' nok: '2020-03-19T09:32:58.419Z' nzd: '2020-03-13T02:35:16.858Z' php: '2018-10-15T13:29:31.772Z' pkr: '2023-09-06T17:10:41.513Z' pln: '2022-10-13T12:54:39.018Z' rub: '2022-03-07T17:44:50.584Z' sar: '2019-05-08T00:40:28.300Z' sek: '2022-10-13T12:54:39.018Z' sgd: '2022-05-12T07:24:27.813Z' sol: '2023-10-19T07:35:20.838Z' thb: '2022-09-30T02:11:16.560Z' try: '2024-03-13T05:46:55.999Z' twd: '2019-05-08T00:40:28.300Z' uah: '2024-03-25T14:01:08.978Z' usd: '2019-05-08T00:40:28.300Z' vef: '2019-05-08T00:40:28.300Z' vnd: '2019-05-08T00:40:28.300Z' xag: '2020-03-16T12:07:54.295Z' xau: '2018-10-15T13:29:31.772Z' xdr: '2019-05-08T00:40:28.300Z' xlm: '2020-03-13T02:27:51.989Z' xrp: '2020-03-13T02:27:51.989Z' yfi: '2020-07-18T00:00:00.000Z' zar: '2023-06-01T07:50:09.345Z' bits: '2018-12-16T00:00:00.000Z' link: '2018-12-16T00:00:00.000Z' sats: '2018-12-16T00:00:00.000Z' atl: aed: 3.22 ars: 35.1 aud: 1.15 bch: 0.00061874 bdt: 75.64 bhd: 0.330818 bmd: 0.877647 bnb: 0.00145528 brl: 3.66 btc: 1.358e-05 cad: 1.079 chf: 0.803831 clp: 641.06 cny: 5.74 czk: 18.6 dkk: 5.43 dot: 0.01824728 eos: 0.06823362 eth: 0.00020588 eur: 0.730265 gbp: 0.629869 gel: 2.59 hkd: 6.89 huf: 255.57 idr: 12829.05 ils: 2.91 inr: 65.31 jpy: 97.05 krw: 1008.25 kwd: 0.268173 lkr: 169.86 ltc: 0.0024386 mmk: 1262.08 mxn: 16.23 myr: 3.69 ngn: 306.14 nok: 7.39 nzd: 1.24 php: 42.68 pkr: 122.98 pln: 3.3 rub: 50.72 sar: 3.29 sek: 7.43 sgd: 1.18 sol: 20.4 thb: 28.03 try: 5.12 twd: 24.94 uah: 23.13 usd: 0.877647 vef: 0.087879 vnd: 20544 xag: 0.03215085 xau: 0.00042766 xdr: 0.618198 xlm: 1.266586 xrp: 0.51131826 yfi: 1.103e-05 zar: 12.52 bits: 13.58 link: 0.01893714 sats: 1357.66 atl_change_percentage: aed: 14.41627 ars: 2361.81893 aud: 32.49086 bch: 135.6116 bdt: 45.50042 bhd: 14.29254 bmd: 14.42094 bnb: 17.52902 brl: 39.00819 btc: 5.53325 cad: 26.5285 chf: 12.67067 clp: 47.21742 cny: 26.53016 czk: 26.123 dkk: 27.27694 dot: 531.35789 eos: 1312.72686 eth: 42.84868