{"openapi":"3.0.3","info":{"title":"AdGhost Vigil API","version":"1","description":"Read your bot-detection numbers from your own programs. The same numbers the Vigil dashboard shows."},"servers":[{"url":"https://tq.theadghost.com"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-AdGhost-Key","description":"An account API key (agk_…), created in the dashboard under Settings → API keys."}}},"paths":{"/v1/tq/me":{"get":{"summary":"Who this key belongs to","description":"Your company, its contract limits and this month's use.","parameters":[],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"who":{"key":"key:BI export","role":"analyst","publisherId":null},"companies":[{"id":7,"name":"Example Ads","role":"analyst"}],"company":{"id":7,"name":"Example Ads","status":"active","limits":{"sites":25,"visitsPerMonth":20000000},"usage":{"sites":9,"visitsThisMonth":4120000,"overLimit":false}}}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/overview":{"get":{"summary":"Everything at once","description":"Totals, the same period before, a point per day, and a row per publisher, per site and per reason. One call is enough to build a whole screen.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":396,"default":7},"description":"How many days back from today, today included."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"First day, like 2026-09-01. Use with `to` instead of `days`."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Last day, included. Defaults to today."},{"name":"publisher","in":"query","schema":{"type":"integer"},"description":"Only this publisher (its id from /v1/tq/publishers)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"range":{"from":"2026-09-25","to":"2026-10-01","days":7,"timezone":"UTC"},"totals":{"visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0},"previous":{"visits":1000,"clean":990,"suspect":60,"invalid":20,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.02,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0},"change":2.55,"series":[{"day":"2026-09-25","visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0}],"publishers":[{"id":3,"name":"Example Media","sites":3,"visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0,"change":2.1,"trend":[0.02,0.0455],"status":"watch"}],"sites":[{"siteKey":"news-example-com-x7k2mq","domain":"news.example.com","publisher":{"id":3,"name":"Example Media"},"visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0,"change":2.1,"trend":[0.021,0.024,0.03,0.045,0.05,0.048,0.0455],"status":"watch","tag":{"state":"live","lastReport":"2026-10-01T09:00:00.000Z"},"topReason":{"reason":"robot_browser","name":"Robot browser"}}],"reasons":[{"reason":"robot_browser","name":"Robot browser","count":30,"share":0.0273,"why":"The browser says it is being driven by a program…","checks":[{"id":"f1.webdriver","label":"navigator.webdriver is true","count":30}]}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/publishers":{"get":{"summary":"Publishers with their totals","description":"For companies with many clients.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":396,"default":7},"description":"How many days back from today, today included."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"First day, like 2026-09-01. Use with `to` instead of `days`."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Last day, included. Defaults to today."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"range":{"from":"2026-09-25","to":"2026-10-01","days":7,"timezone":"UTC"},"publishers":[{"id":3,"name":"Example Media","sites":3,"visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0,"change":2.1,"trend":[0.02,0.0455],"status":"watch"}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/sites":{"get":{"summary":"Sites with clean, suspect and invalid","description":"One row per site, busiest first.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":396,"default":7},"description":"How many days back from today, today included."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"First day, like 2026-09-01. Use with `to` instead of `days`."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Last day, included. Defaults to today."},{"name":"publisher","in":"query","schema":{"type":"integer"},"description":"Only this publisher (its id from /v1/tq/publishers)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"range":{"from":"2026-09-25","to":"2026-10-01","days":7,"timezone":"UTC"},"sites":[{"siteKey":"news-example-com-x7k2mq","domain":"news.example.com","publisher":{"id":3,"name":"Example Media"},"visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0,"change":2.1,"trend":[0.021,0.024,0.03,0.045,0.05,0.048,0.0455],"status":"watch","tag":{"state":"live","lastReport":"2026-10-01T09:00:00.000Z"},"topReason":{"reason":"robot_browser","name":"Robot browser"}}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/sites/{siteKey}":{"get":{"summary":"One site","description":"Its history (by hour for 1 or 2 days, otherwise by day), where the bots are (page type, device, country, network), how visits went (`engagement`: how long visitors stayed and whether they did anything), and what was detected.","parameters":[{"name":"siteKey","in":"path","required":true,"schema":{"type":"string"},"description":"The site key shown in Settings, for example news-example-com-x7k2mq."},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":396,"default":7},"description":"How many days back from today, today included."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"First day, like 2026-09-01. Use with `to` instead of `days`."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Last day, included. Defaults to today."},{"name":"grain","in":"query","schema":{"type":"string","enum":["day"]},"description":"Force a point per day even for 1 or 2 days."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"site":{"siteKey":"news-example-com-x7k2mq","domain":"news.example.com","publisher":{"id":3,"name":"Example Media"},"reportingShare":1,"tag":{"state":"live","lastReport":"2026-10-01T09:00:00.000Z"}},"range":{"from":"2026-09-25","to":"2026-10-01","days":7,"grain":"day","timezone":"UTC"},"totals":{"visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0},"change":2.1,"status":"watch","series":[{"at":"2026-09-25","visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0}],"where":{"page":[{"value":"article","visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0}],"device":[{"value":"mobile","visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0}],"country":[{"value":"GB","visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0}],"network":[{"value":"datacentre","visits":1100,"clean":990,"suspect":60,"invalid":50,"excluded":4,"reports":1104,"cleanShare":0.9,"suspectShare":0.0545,"invalidShare":0.0455,"averageScore":12.4,"adsHeldBack":31,"clickBombs":0}]},"engagement":[{"value":"d0e0","stayed":"Under 5 seconds","active":false,"visits":140,"share":0.1273,"invalidShare":0.2}],"reasons":[{"reason":"robot_browser","name":"Robot browser","count":30,"share":0.0273,"why":"The browser says it is being driven by a program…","checks":[{"id":"f1.webdriver","label":"navigator.webdriver is true","count":30}]}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/sites/{siteKey}/signals":{"get":{"summary":"What was detected on one site","description":"Reasons in plain words, each with the checks behind it and their counts.","parameters":[{"name":"siteKey","in":"path","required":true,"schema":{"type":"string"},"description":"The site key shown in Settings, for example news-example-com-x7k2mq."},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":396,"default":7},"description":"How many days back from today, today included."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"First day, like 2026-09-01. Use with `to` instead of `days`."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Last day, included. Defaults to today."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"siteKey":"news-example-com-x7k2mq","range":{"from":"2026-09-25","to":"2026-10-01"},"reasons":[{"reason":"robot_browser","name":"Robot browser","count":30,"share":0.0273,"why":"The browser says it is being driven by a program…","checks":[{"id":"f1.webdriver","label":"navigator.webdriver is true","count":30}]}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/sites/{siteKey}/events":{"get":{"summary":"Alerts and events on one site","description":"Click bombing, spikes, silence. Newest first.","parameters":[{"name":"siteKey","in":"path","required":true,"schema":{"type":"string"},"description":"The site key shown in Settings, for example news-example-com-x7k2mq."},{"name":"open","in":"query","schema":{"type":"string","enum":["1"]},"description":"Only the ones nobody has dealt with."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"events":[{"id":41,"kind":"spike","name":"Spike in invalid traffic","site":{"siteKey":"news-example-com-x7k2mq","domain":"news.example.com"},"detail":{"invalidPercent":9.1,"normalPercent":2,"visits":38680},"at":"2026-10-01T04:07:00.000Z","open":true,"handledBy":null}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/events":{"get":{"summary":"Alerts across all your sites","description":"Newest first, up to 200.","parameters":[{"name":"open","in":"query","schema":{"type":"string","enum":["1"]},"description":"Only the ones nobody has dealt with."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"events":[{"id":41,"kind":"tag_silent","name":"Tag silent","site":{"siteKey":"shop-example-com-p3n8ra","domain":"shop.example.com"},"detail":{"hoursSilent":52,"lastReport":"2026-09-29T00:00:00.000Z"},"at":"2026-10-01T04:07:00.000Z","open":true,"handledBy":null}]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}},"/v1/tq/report":{"get":{"summary":"A report, as JSON or a spreadsheet","description":"The same numbers grouped your way. With format=csv the answer is a CSV file.","parameters":[{"name":"group","in":"query","schema":{"type":"string","enum":["publisher","site","day","reason"],"default":"site"},"description":"What each row is."},{"name":"format","in":"query","schema":{"type":"string","enum":["csv"]},"description":"Leave out for JSON."},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":396,"default":7},"description":"How many days back from today, today included."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"First day, like 2026-09-01. Use with `to` instead of `days`."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Last day, included. Defaults to today."},{"name":"publisher","in":"query","schema":{"type":"integer"},"description":"Only this publisher (its id from /v1/tq/publishers)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"range":{"from":"2026-09-25","to":"2026-10-01","days":7,"timezone":"UTC"},"group":"day","columns":["Day (UTC)","Visits","Clean","Suspect","Invalid","Clean %","Suspect %","Invalid %","Ads held back","Click-bombing events"],"rows":[["2026-09-25",1100,990,60,50,"90.00","5.45","4.55",31,0]]}}}},"401":{"description":"No key, or a key that is wrong or revoked."},"404":{"description":"Not found. Also the answer for a site that is not yours."},"429":{"description":"Too many requests: wait a minute."}}}}}}