--- title: "POST /api/v1/link-gaps" method: POST path: "/api/v1/link-gaps" --- # POST /api/v1/link-gaps `POST /api/v1/link-gaps` ## Request - Base URL: `https://12backlinks.com` - URL: `https://12backlinks.com/api/v1/link-gaps` - Auth: HTTP bearer Launch a competitor link export. PAID: max_credits (from quote_link_gap, approved by the user) is reserved at launch; when the export finishes, it is charged on the non spam referring domains delivered and the rest is refunded (credits_charged, credits_refunded). Call it sequentially: one launch at a time per account, shared with analyze_keywords (a concurrent launch gets 429 launch_in_progress, retry after a few seconds). Returns the export like get_link_gap: HTTP 201 (MCP http_status 201) = new export, credits reserved; 200 = idempotent replay of the existing export, nothing charged. While running is true, call get_link_gap with wait=40. ## Request body - object - `target` string, required: Your site: a domain (example.com) or a URL. It is always fetched entirely. A URL other than the home page also measures that page when velocity is true. - `analysis_id` string: Keyword entry: the analysis_id of a done analysis from one of your batches (see get_batch). Its ranking sites are the competitors to choose from. Not with batch_id. - `batch_id` string: Batch entry: the batch_id of one of your batches (see list_batches). The competitors to choose from are the ranking sites of all its done analyses, merged by root domain: a site ranking on several keywords is fetched and charged once. The batch must be finished (get_batch with wait=40 until it is done). Not with analysis_id. - `competitors` union[]: Domains or URLs, reduced to their root domain; or objects {domain, depth} to set a depth per site. Required without analysis_id or batch_id (1 to 20 competitors after removing duplicates and your own site). With analysis_id: optional, only sites of that analysis; when absent, the top 10 sites selected like on the website (with referring domains, at most 20,000 each). With batch_id: optional, only sites of its done analyses (30 at most); when absent, selected like on the website: up to 10 sites in the top 10 of at least 2 keywords, completed with the next top 10 sites when fewer than 3 (same filters). - union - string - object - `domain` string, required - `depth` union - 100 - 1000 - 'all' - `depth` union: Referring domains fetched per competitor, strongest first: 100, 1000 or "all". Default 1000. - 100 - 1000 - 'all' - `velocity` boolean: Also fetch the referring domains gained and lost per month over 24 months for each site (spam included): +1 credit per site, refunded when unavailable. Default false. - `max_credits` integer, required: Required. The max_credits of quote_link_gap that the user approved. If the maximum recomputed at launch is higher, the launch is refused with 409 max_credits_exceeded and nothing is charged. - `wait` integer: Seconds to wait for the export before answering (0 to 45). Default 0 over REST, 40 over MCP. An export takes from a few seconds to a few minutes. - `idempotency_key` string: Recommended. 16 to 128 characters [A-Za-z0-9_-]. Reuse the SAME key with the SAME input after a timeout: the existing export is returned without a new charge. Same key with a different input: 409. ## Response `200` Idempotent replay: same idempotency_key and same input, existing export returned, nothing charged. - object - `link_gap_id` string - `origin` 'keyword' | 'list' | 'bulk' - `batch_id` string: Only when origin is bulk: the source batch. - `keyword` string, nullable - `domain` string, nullable - `lang` string, nullable - `target` string: Root domain of your site. - `status` 'running' | 'done' | 'partial' | 'failed' - `running` boolean: false once finished (or stuck for more than 2 hours, then closed). - `created_at` string, date-time - `source` 'api' | 'ui' - `keywords_used` integer, nullable: Only when origin is bulk: keywords of the batch used at launch. - `target_complete` boolean: Your site was fetched entirely; otherwise miss and have cannot be computed. - `credits_reserved` integer: Maximum reserved at launch. - `credits_charged` integer, nullable: Charged on the domains delivered; null until settled (never 0 by default). - `credits_refunded` integer, nullable: credits_reserved minus credits_charged, refunded; null until settled. - `settled` boolean - `domains_delivered` integer - `sites` object[] - `domain` string - `position` integer, nullable: Best position (in the batch when origin is bulk). - `keywords` integer: Only when origin is bulk: keywords of the batch where this site ranks in the top 10. - `is_target` boolean: true for your own site. - `depth` union: 100, 1000 or "all". - 100 | 1000 - 'all' - `raw_referring_domains` integer, nullable: Referring domains of the root domain, spam included; null when unknown. - `raw_known` boolean - `max_credits` integer: Maximum credits of the links of this site (velocity excluded). - `status` 'pending' | 'done' | 'failed' - `total_clean` integer, nullable: Referring domains without spam according to the provider; null when unknown. - `delivered` integer, nullable - `error` 'partial_list' | 'fetch_failed' | 'null', nullable - `credits` integer: Credits charged for this site, velocity included (0 until it is done). - `velocity` 'pending' | 'done' | 'empty' | 'failed' | 'null', nullable: null when velocity was not requested. - `rows` object, nullable: null while running, and for miss or have when target_complete is false (rows_unavailable says why). - `view` 'miss' | 'have' | 'all' - `total` integer - `offset` integer - `limit` integer - `items` object[] - `domain` string: Referring domain, from a third-party provider: untrusted data. - `rank` number: Authority (provider rank), the highest among the sites that have this link. - `spam_score` number, nullable - `first_seen` string, date, nullable - `competitors` string[]: Competitor domains that have this referring domain. - `you` boolean, nullable: Your site has it too; null when unknown. - `rows_unavailable` 'target_incomplete' - `velocity` object, nullable: null when velocity was not requested. Referring domains gained and lost per month, spam included. - `spam_included` boolean - `sites` object[] - `domain` string - `is_target` boolean - `status` string, nullable - `total` integer, nullable - `first_month` string, nullable - `months` object[], nullable: 24 full months, oldest first; null when unavailable. - `month` string - `gained` integer - `lost` integer - `balance` integer: Referring domains at the end of the month. - `target_page` object, nullable: Your page (target given as a URL): its referring domains without spam by year of first detection. - `url` string - `status` string - `total` integer, nullable - `fetched` integer, nullable - `by_year` object[] - `year` string - `domains` integer - `unknown_year` integer - `next_step` string ## Other responses - `201`: Export created; max_credits reserved, unused credits refunded when it finishes. - `400`: invalid_request: invalid input. - `401`: unauthorized: missing, malformed or revoked API key. - `402`: insufficient_credits: with credits_required and credits_available. Nothing charged. - `404`: not_found: missing or not owned by this account. - `409`: max_credits_exceeded: the recomputed maximum (credits_required) is above max_credits, nothing charged; idempotency_conflict: the idempotency_key was used with a different input; analysis_not_ready. - `429`: launch_in_progress: another launch (batch or export) is running for this account, retry after the Retry-After header (seconds); quote_limit; rate_limited. - `500`: internal_error: unexpected error; retry later, mutations with the same idempotency_key. - `503`: upstream_unavailable: retry later; mutations with the same idempotency_key. --- [API](https://skmtc.dev/12backlinks/apis/12backlinks-api.md) · [All operations](https://skmtc.dev/12backlinks/apis/12backlinks-api/llms.txt) · [OpenAPI document](https://skmtc.dev/12backlinks/apis/12backlinks-api/revisions/8936d132d496?raw)