Start a technical audit

Scan this brand’s primary domain for technical / AI-crawlability issues — the same audit the “Run audit” button triggers. Only one audit may run per brand at a time. Returns a job_id; poll List technical issues once it completes to see the results.


POST /brands/{brand_id}/technical/audits

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required on every write. See Idempotency

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands

Body parameters

Parameter	Type	Required	Description
`include_link_analysis`	`boolean`	optional	Also check internal-link health. Defaults to `true`, matching the “Run audit” dialog.

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/technical/audits' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: 9c2e5f1a-3b7d-4a6e-8c1f-2d5b7a9e6f30' \
  --header 'Content-Type: application/json' \
  --data '{}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/technical/audits"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "9c2e5f1a-3b7d-4a6e-8c1f-2d5b7a9e6f30",
    "Content-Type": "application/json",
}
 
response = requests.post(url, headers=headers, json={})
 
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '9c2e5f1a-3b7d-4a6e-8c1f-2d5b7a9e6f30',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/technical/audits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/technical/audits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{}",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: 9c2e5f1a-3b7d-4a6e-8c1f-2d5b7a9e6f30",
    "Content-Type: application/json"
  ],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go


package main
 
import (
    "fmt"
    "net/http"
    "strings"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/technical/audits"
 
    payload := strings.NewReader("{}")
 
    req, _ := http.NewRequest("POST", url, payload)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "9c2e5f1a-3b7d-4a6e-8c1f-2d5b7a9e6f30")
    req.Header.Add("Content-Type", "application/json")
 
    res, _ := http.DefaultClient.Do(req)
 
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
 
    fmt.Println(string(body))
 
}

Ruby


require 'uri'
require 'net/http'
 
url = URI("https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/technical/audits")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api-key>'
request["Idempotency-Key"] = '9c2e5f1a-3b7d-4a6e-8c1f-2d5b7a9e6f30'
request["Content-Type"] = 'application/json'
request.body = "{}"
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "job_id": "3f8a1c2e-9b4d-4a6f-8c1e-2d5b7a9e6f30",
    "domain": "example.com",
    "total_urls": 214,
    "credit_cost": 20,
    "is_free_scan": false,
    "included_pages_remaining": 0
  },
  "request_id": "req_7c9e1f3a4b2d46f08a1c"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "This brand has no active domain. Add one before starting an audit.",
    "request_id": "req_2a7c5e91b8d04f36ac10"
  }
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it from the API tab on the Connections page to get a replacement.",
    "request_id": "req_8f21c0aa47b1490d2e63"
  }
}

403


{
  "error": {
    "code": "quota_exceeded",
    "message": "Insufficient credits: this audit is estimated at 15, 8 available.",
    "request_id": "req_4e8c1a3f7b2d46f0ba9c"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

409


{
  "error": {
    "code": "conflict",
    "message": "An audit is already running for this brand. Wait for it to finish.",
    "request_id": "req_31c9ba7f0e5d4a118cc2"
  }
}

429


{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 24 seconds.",
    "request_id": "req_9a3f5e21c0aa47b190d2"
  }
}

Response fields

Field	Type	Description
`data.job_id`	`uuid`	required. Pass to Get technical issue queries once the audit completes to see fresh results
`data.domain`	`string`	required. The domain that was scanned — always the brand’s primary domain, never a choice
`data.total_urls`	`integer`	required. Pages found across the domain’s own sitemap(s) at the common locations (`/sitemap.xml` etc). `0` if none were found
`data.credit_cost`	`integer`	required. Estimated credits for the pages beyond the plan’s included pages this billing period, at 10 credits per 100 extra pages. `0` when the included pages cover the estimate
`data.is_free_scan`	`boolean`	required. `true` when `credit_cost` is `0`: the plan’s included pages cover the estimate
`data.included_pages_remaining`	`integer \| null`	required. Included audit pages left in the current billing period before this audit. `null` when the plan includes unlimited pages
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
400	`invalid_request`	The brand has no active domain
401	`invalid_token`	The key is missing, malformed, or does not exist
401	`token_expired`	The key passed its expiry date
401	`token_revoked`	The key was revoked
403	`quota_exceeded`	Insufficient credits for this audit’s estimated cost
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
409	`conflict`	An audit is already running for this brand
429	`rate_limited`	Over 300 requests per minute. See the `Retry-After` header

Notes

Sitemap discovery is scoped to the brand’s primary domain only. This checks the common sitemap locations (/sitemap.xml, /sitemap_index.xml, /sitemap1.xml, /sitemap-index.xml) against the domain on file — not robots.txt-referenced sitemaps, a custom sitemap URL, or the www/apex alternate host. If your sitemap lives somewhere else, this will undercount total_urls and the audit will still run, just against whatever it discovers plus link-following during the crawl itself.

total_urls is a discovery estimate, not the final page count. The real page count — and the real charge — is based on how many pages the crawl actually visits, which can differ from what the sitemap claimed.

There is no page-count or crawl-speed override. Every audit through this endpoint uses the platform’s own cap and normal crawl speed, the same defaults the “Run audit” dialog ships with — there is no equivalent of result_count here.

Every plan includes a number of audit pages per billing period, shared across the workspace’s brands. Pages inside the allowance cost nothing; pages beyond it cost 10 credits per 100, billed per started 10 pages (1 credit per 10), charged on completion for the pages actually scanned. This matches the “Run audit” dialog exactly.