The Rightlander API gives you programmatic access to the partner intelligence you already see in the workbench: the domains and social profiles connected to your programme, everything we hold on any one of them, and the alerts we raise about them.
It is a REST API. Resources live under /apis/rightlander/v1, responses are JSON, and every response carries an "ok" boolean so a failure is never mistaken for an empty result.
There are four things you can do. List your assets. Retrieve one asset in as much or as little detail as you want. Ask us to refresh a social profile. Read your alerts.
And one way to keep up without asking about each asset in turn: the activity feed lists what changed across your whole programme, newest first.
Affiliate networks can also send us domains to scan, for themselves and for each of their clients, and read one client's feed at a time. See Networks and clients.
Compliance teams can read what they see in the Compliance Workbench, with the actions taken on each item, by market and month or for the current scan cycle. See Compliance Workbench.
Domains are scanned on a schedule set by your subscription, so there is no endpoint to force a domain rescan. Social profiles can be refreshed on demand because the cost of doing so is yours to decide.
Give your AI assistant our API instructions and it can answer questions about your data, chart it or help you connect it to the other tools you use. The instructions and the OpenAPI spec are built from this documentation, so they always match the live API.
Start by creating a key on the API Access page for the tool you are connecting. Give it the Read permission only and a time limit, then revoke it when you have finished. Where the tool has a place for secrets or connection settings, put the key there rather than typing it into a chat.
For a chat assistant, paste in the starter prompt below. It points the assistant at the instructions, which tell it how to authenticate, how to page through results, which calls cost credits and to ask you before making one.
For custom assistants, actions and MCP servers, import the OpenAPI spec and set Bearer authentication with your key. Spreadsheet, BI and automation tools can call the same addresses: tools that cannot set a header can send the key as apikey on the query string.
Paste this into your assistant to begin. It will ask for your key when it needs it.
| Instructions for your assistant How to authenticate and which calls cost credits, with the endpoints and their parameters. |
Open Download |
| Full instructions The same with the fields each endpoint returns. Longer, so use it when your assistant needs the detail. |
Open Download |
| OpenAPI 3.1 spec For custom assistants and actions, MCP servers that read a spec, Postman, Zapier and Make. |
Open Download |
If your assistant cannot open links, use Copy text and paste the instructions in. Never paste your key where other people can see it: create one for the tool on the API Access page and revoke it when you have finished.
Every request needs an API key. Create one on the API Access page; it is shown once and stored only as a one-way hash, so keep a copy somewhere safe.
Send it as a bearer token: Authorization: Bearer rl_xxxxxxxxxxxx_...
Your account is resolved from the key. You do not need to send an account code, and if you do send one it must match the key or the request is rejected with 403 account_mismatch.
If your tool cannot set request headers - a spreadsheet import, for example - you can pass the key as ?apikey= instead. It works, but the key then appears in browser history and server logs, so prefer the header wherever you can.
Each key carries permissions. A key with read only cannot trigger a refresh, which makes it safe to hand to a reporting tool or a partner.
A key can also be given a time limit when you create it: 24 hours, 7 days, 30 days or 90 days. Once it passes, requests with the key are refused with 401 key_expired. Use one for a test or a prototype so it stops working on its own. The limit cannot be extended, so create a new key when you need longer.
Create and manage your keys on the API Access page.
Your account has a daily request allowance. Every response tells you where you stand: request.rate_limit in the body, and X-RateLimit-Limit / X-RateLimit-Remaining in the headers. The allowance resets at 00:00 UTC.
Exceed it and you get 429 rate_limited with a Retry-After header. Failed authentication does not count against the allowance, so a misconfigured client cannot exhaust your day before you notice.
Per-second burst limiting is coming. The daily allowance is a quota, not a rate limit: today it stops you using more than you bought, but it does not stop you spending it all in one minute. When burst limiting arrives it will use the same 429 response and its own headers, so a client written against the current behaviour will keep working.
In the meantime, if you are backfilling, please pace your requests. A few per second is fine.
The compliance endpoints have an allowance of their own, set for your account and 250 calls a day unless agreed otherwise. It is shared by the three of them and a compliance call does not use any of the allowance above. On a compliance call request.rate_limit and request.compliance_limit both show where you stand against it. Going past it returns 429 compliance_limit_reached.
Asset detail endpoints return a lot. Rather than asking you to name individual fields, they group the response into three sets, and you ask for the ones you want with ?sets=.
intel - what the asset is. Traffic, partner and ownership, connected domains and social profiles, brands found, commercial viability, the markets we have scanned, and brand exposure: where your brand appears across the asset.
risk - what is wrong with it. The risk score and the evidence behind it, compliance review findings, and PPC brand bidding.
growth - what to do about it. Target pages, offers, and AI influence: how the asset shows up in LLM answers.
Ask for one (?sets=risk), several (?sets=intel,risk) or leave it off for everything. ?sets=core returns only the identity and status header, which is the cheapest call you can make against an asset.
A social profile assessment is not a property of the profile. When we assess an account we do it against YOUR brands, your tracked competitors and the sectors you have configured, and the brand relevance in the result is judged against exactly those. The same TikTok account assessed for two customers produces two different answers, and we store them separately.
That means a scan date on its own does not tell you what you need to know, so every social reference in this API carries an assessed_for block saying which of three things it is.
basis your_account - we assessed this profile against your brands and sectors. Everything on the row is yours.
basis generic - an assessment exists, but it was not made for you. Audience, posting activity, risk, quality and our read of what the account is are common to any account, so they are returned. The brand relevance is not: those tags were judged against somebody else, so we remove them and recompute relevance and sector fit from your own configuration instead. You get an answer, and it is yours.
basis not_assessed - nobody has assessed this profile. There is a fourth value, unknown, which means we could not match the handle to a profile we hold. It is deliberately not the same as not_assessed, which would claim we had looked.
last_assessed_for_you is null unless basis is your_account. last_assessed dates whatever data is actually being returned. Where a successful assessment was followed by a failed one, both dates report the successful one - a failure does not replace an assessment we already hold.
rescan_recommended is true for anything that is not your_account. Requesting a refresh on a generic profile is what turns it into yours, and it costs the same as any other refresh.
We never tell you which other account holds a generic assessment. basis is a fixed set of values and the dates carry no owner, because that would tell one customer something about another customer.
Reading data does not cost credits. It is covered by your daily request allowance.
The one exception is the activity feed, at 1 credit per day of history per account. It is charged only when the feed returns something - an empty window is free - and never on a trial.
Credits pay for the two operations that make us go and do new work: a social profile refresh at 10 credits, and an LLM influence refresh at 1,500 credits. The gap is real - an LLM refresh runs twelve searches, a social refresh is one fetch.
Credits are taken when the job is accepted, not when it finishes, and returned in full if we cannot start it. Your balance and a full statement are on the API Access page.
A request that would leave you short is refused with 402 insufficient_credits before any work starts, and tells you the cost and your balance.
An affiliate network uses the API on behalf of the advertisers it works with. Three things make that work.
Guided setup. Once we have set your account up as a network, sign in at https://aw1.rightlander.com/intelv2/partnerIntelNetworkAdmin.php with your usual Rightlander username and password (the main user of your account). The guided setup opens straight away and takes you through everything on this page: your branding, getting your partner domains to us, the daily feed, the "Personalise my feed" button and the daily job for each client. Each step says up front who does it and what to have ready. Progress is saved, so you can stop and come back from the same address.
Your API key is generated automatically during the setup, so there is no key to create first. It is shown at the top of every step and every example already carries it (and your signing secret), whenever you sign in to the setup. The Test step shows which of your server's calls have succeeded. If you ever need to replace the key, make a new one from the setup: it goes straight into the examples and the old one stops working.
Your domains. Send your affiliate domains with POST /v1/partner-domains and we scan them under your account. Your activity feed then covers them, and every item carries the affiliate_id you sent with the domain.
Your clients. You know each advertiser by your own ID; send it as client_ref. Send that client's partner domains with the same call and client_ref, and once the client signs up for a personalised feed they are scanned under the client's own account, against its own brands. GET /v1/clients lists who has signed up.
One feed per client. GET /v1/activity?client_ref=... returns that client's feed: items from its own account marked scope client, and items from your scans marked scope network, both limited to the domains you sent for it. A client who has not signed up, or has cancelled, gets the network items only.
Keep client_ref out of anything your client can edit. It is how one client's feed is kept from another's, so it must come from your own record of who is logged in, never from a URL.
The button. Put a "Personalise my feed" button beside the feed on your site. We give you its link ready-made: your daily job sends your client list with GET /v1/clients?client_refs=A,B,C (up to 100 per call, including clients you have not sent us before) and saves each one's personalise_url for the day. It is signed for that client and works for 7 days, so your page only has to show the saved link, with no call of its own. To fill in the request form for the client, add any of email, name, company, brand and domain (the brand's website) to the end of the link, URL-encoded, with no signing: for example personalise_url + '&email=jo%40brand.com&brand=Brand&domain=brand.com'. The email is then shown read-only; the others can be changed by the client. An email at a free email service such as hotmail.com is refused unless you sign it (gmail.com is accepted). An email that is not at the brand's website or one of your own domains is accepted, but the client is asked why and its feed waits until Rightlander has checked it. If you want the name and company locked as well, you can instead build and sign the link on your own server with your signing secret (GET /v1/network gives you both). Either way the link opens our pages in your branding. Mark the link with data-rl-personalise and add our script once to the page (<script src="https://aw1.rightlander.com/intelv2/networkModal.js" async></script>), and the link opens in a modal over your page, 80% of the screen, instead of a new tab: the client fills in its request, tells us about its products and ends on a review of what it asked for, with no login. Your page reloads when a client who finished closes the modal; RightlanderPersonalise.open(url), .close() and .onClose let your own code drive it instead. If your clients are billed through Rightlander or trackback.io the personalised feed starts straight away; if you bill your own clients we tell you, and the feed starts when you approve it with POST /v1/clients.
Users. A network can personalise per user instead of per client (agreed with Rightlander). Send each user's id as uid with client_ref: POST /v1/partner-domains with uid sends that user's partner domains (its suggested scan credits come from that list), GET /v1/activity?client_ref=...&uid=... returns that user's feed, and the personalise_url we give you is signed for that user. A user who personalises joins its company's account with us as a user of it; the first from a company is asked for the company's brand, and later colleagues just join. A request with client_ref and no uid is for the client as a whole. Webhooks and GET /v1/clients carry uid for user subscriptions.
Webhooks. Set a webhook URL with POST /v1/network and we post client.requested, client.approved, client.declined, client.activated, client.setup_completed, client.allocation_changed, client.deactivated and client.cancelled to it, signed in X-RL-Signature with your signing secret. The guided setup can send a test event, test.ping, to check your URL. A delivery that does not get a 2xx answer is tried again after 5 minutes, 15 minutes, 1 hour, 4 hours and 12 hours, with the same body; X-RL-Delivery carries the event id and X-RL-Attempt the try, so you can ignore a repeat you have already processed.
Usage. One scan credit covers one partner domain in one market for a month: we examine the domain for pages relevant to the client's products and brands, then scan up to 50 of those pages for links, competitors, risk and influence (more by arrangement), plus up to 40 posts on up to 4 social profiles found on it, where it has them; for a client that is social only, a credit covers the social profile you send us. A client's full cycle is its domains times its markets. A client can have more partner domains than credits: we scan as many as its credits cover each month and work through the rest over the following months, then start round again, so its credits set the pace. We suggest an amount from the domains you send, and each client has its own monthly allocation.
Scan credits and product profiles. A client buys a monthly allowance of scan credits in units of 1,000 (1,000, 2,000, 3,000 and so on, up to 500,000). One scan credit covers one partner domain in one market, with its pages and social profiles (see Usage). The client chooses its credits when it clicks "Personalise my feed" (we suggest an amount from the partner domains you sent), and each client gets 3 product profiles per market unless agreed otherwise, with extra product profiles available as a monthly add-on. A profile for a product in another country means scanning partner domains in that market too, so it can need more credits. If you bill your own clients, Rightlander bills you each client's credits at your price per scan credit, plus each extra product profile at your profile price, both agreed with you and shown on your admin screen and in GET /v1/network (pricing); you set and keep your own price to your clients. Change an approved or active client's credits or extra profiles with POST /v1/clients action=change, or on your admin screen. More applies straight away and is charged from the current month - the difference, invoiced separately; fewer takes effect on the 1st of next month. Scan credits are separate from the API credits below, which pay for your API calls.
Item links. Every item in your feed, and in each client feed, carries a link: a read-only page showing that one item, which your client can open without a Rightlander login. It shows your name, logo and colour, or a plain page if you set item_branding to neutral, and nothing on it leads into Rightlander. A link works for 30 days, and the same item keeps the same link each time the feed returns it.
Ready-made HTML. Choose how your feed looks in the Network feed step of your guided setup, which previews one item of each kind, or with feed_style on POST /v1/network. Add render=html to GET /v1/activity and each item comes back as ready-made HTML in that style (events[].html), with the whole page in a wrapper (render.html). Download the stylesheet once from that step and add it to your feed page: it is not sent with the daily feed. Category colours match ours. The data is still all there if you would rather build your own.
What the network feed carries. Critical risks on partner sites and social profiles; Brand bidding indicators (the partner domain has been seen bidding on brand searches - never which brands, for privacy, so these rows carry brands_hidden and no ad text or links; brand bidding on a client's own brands is a paid add-on the client buys outside its subscription, and then appears in its personalised feed); AI influence (partner domains AI assistants trust in general); and Relevant content. Offer changes and link anomalies are in personalised feeds only: they are about one client's own offers and affiliate IDs, and a site can rightly work with two clients on one network.
Relevant content. Indications of topic or brand relevance that help clients spot publishers whose content fits their products or verticals: brand mentions, product relevance and growth opportunities found by generic product profiles we set up for your verticals. They have scope example, scope_label Relevant content and an example_note to show beside them, up to 5 per category a day. Once a client personalises, its own items take their place and its AI influence is for its own verticals - except growth opportunities: those stay, from across your whole programme, with scope_label Partner discovery, so the client can find publishers it does not work with yet.
Client usernames. A client is never shown a Rightlander username unless you allow it (show_username on POST /v1/network, or your admin screen). By default the client only chooses a password at setup, so you need not name the service.
Credits. The activity feed costs 1 credit per day of feed, for your own feed and for each client feed you fetch, and sending partner domains costs 1 credit per send (one POST /v1/partner-domains, up to 1,000 domains). Everything else a network uses - the client list, its settings, approving clients and the personalise links - is free. A network package includes a monthly credit allowance, added on the 1st of each month; monthly credits not used by the end of the month expire. Credits bought separately do not.
Sending domains needs the domains permission on your key, and approving or cancelling clients needs the clients permission. A read-only key carries neither. The key the guided setup makes has both.
The compliance endpoints return what your team sees in the Compliance Workbench: the issues found on partner pages and the action taken on each.
Our compliance data is held by market and by month. Read one month with GET /v1/compliance/{iso}/{yyyymm}, or the current scan cycle with GET /v1/compliance/{iso}/cycle. The scan cycle is this month and last month together, the same items the workbench shows. It moves on the 1st of each month, so read the closing month by month if you need its final state.
An issue found in both months of the cycle is returned once, from the newer month. also_reported_in names the other one. issue_key stays the same for the same issue on the same page from one month to the next, so you can follow it while the item id changes.
Each item has a status: unresolved, flagged, non_issue or ignored. An actioned item carries action, with its scope (the whole site or one page), whether an ignore is temporary, a plain description, the name of the person who took it and when. origin carried_forward means the action was made in an earlier month and still applies. A flag or an ignore carried forward is not shown, as in the workbench: read the month the action was made to see it.
Each item also has a source. discovery is our scanning across the market as a whole and requested is the scanning set up for your account alone, including the Batch Workbench. Both are returned together unless you ask for one with source.
Screenshot links open the workbench's own screenshot after you sign in to Rightlander, so they are safe to store and share inside your team.
The compliance API is switched on for your account separately from the rest of the API, so you can have one without the other. Compliance calls do not cost credits. They have their own daily allowance, 250 calls a day unless agreed otherwise. They do not count against your other API requests.
The endpoints are read only: actions are still taken in the workbench.
Errors return the HTTP status you would expect plus a JSON body with ok:false, a human-readable "error" and a stable "error_code" to branch on. Match on error_code, not on the message text.
missing_key / invalid_key / key_revoked / key_expired - 401. The key is absent, malformed, wrong, turned off or past its time limit.
api_not_enabled - 403. API access is not switched on for the account.
account_mismatch - 403. You sent an account code that does not belong to the key.
scope_denied - 403. The key does not carry the permission this endpoint needs.
insufficient_credits / daily_credit_cap - 402. Not enough credits, or the daily credit ceiling would be crossed.
rate_limited - 429. Daily request allowance used. Retry-After tells you when it resets.
invalid_parameter / invalid_category - 400. A parameter was malformed or out of range. The message names the problem and, for a category, lists the valid ones. Not counted and not charged.
not_found - 404. We hold nothing for that asset, in that market, for your account.
unknown_client - 404. You have not sent us that client_ref. Send its domains with POST /v1/partner-domains first.
invalid_state / not_applicable - 409. The client is not in a state that allows this (only a requested client can be approved), or the action does not apply to your network (approval is for networks that bill their own clients).
too_many_domains / invalid_json - 400. More domains than one request takes, or a body that is not valid JSON. Nothing is recorded.
method_not_allowed - 405. The endpoint does not answer that HTTP method.
not_subscribed - 403. The compliance API is not switched on for your account.
month_not_found - 404. We hold no report table for that market and month. GET /v1/compliance/markets lists the months that exist.
compliance_limit_reached - 429. Your compliance calls for the day have been used. Retry-After tells you when they reset.
source_unavailable - 503. Compliance data could not be read. Nothing was counted. Retry shortly.
server_error - 500. Ours. Retry with backoff; if it persists, tell us.
feed_unavailable / billing_unavailable / intake_unavailable - 503. We could not read the data, bill the request or accept domains, so it was not run. Nothing is charged or recorded. Retry shortly.
Rightlander has its own MCP server, so your AI assistant can answer questions about your partners from your Rightlander data. There is no code to write: you add one address to your assistant and sign in with your Rightlander login.
It uses OAuth sign-in. Leave any client ID, client secret or API key fields empty: your assistant registers itself and then asks you to log in to Rightlander and allow it. You can check the address is reachable from your network on the server page.
On ChatGPT Business, Enterprise and Edu a workspace admin first allows Create plugins with MCPs under Workspace settings > Permissions & roles, or adds Rightlander for the workspace.
Or let ChatGPT guide you. Paste this into a chat:
On Claude Team and Enterprise an Owner adds it once in Organization settings > Connectors (Add > Custom > Web). Each person then clicks Connect and signs in with their own Rightlander login. The Free plan allows one custom connector. Once added it also works in the Claude phone apps.
Or let Claude guide you. Paste this into a chat:
Google is still rolling custom apps out: for now they are offered on some personal accounts and plans only. If you do not see Add a custom app, use one of these instead.
Gemini Enterprise. An admin adds it once: Settings & help > Manage team > Connected apps > Add MCP Server, with the server address above. Each person then signs in with their own Rightlander login the first time they use it.
Gemini CLI. Run this, then type /mcp auth rightlander inside Gemini CLI to sign in:
Or let Gemini guide you. Paste this into a chat:
Start with What can Rightlander Partner Intelligence tell me? Your assistant will list what your account covers, with example questions for each product you have. Partner lists come with a spreadsheet link holding the full list and partners link to their page in Rightlander.
Copy one into your assistant. Add a market to narrow it, for example "in GB". In Claude they are also in the menu of ready-made questions for Rightlander.
| What it can see | Your account's Rightlander data only, the same as your login. It cannot change anything in Rightlander. |
| Sign-in | Your own Rightlander login. Nobody shares a key and leaving the company ends access with your login. |
| Allowance | A daily number of questions for the account, separate from API credits. The assistant tells you if it is used up and when it resets. |
| Disconnecting | Log in and open Connected AI apps to see your connections and disconnect any of them. Removing the connector in your assistant works too. |
The apps move these menus from time to time. If a step does not match what you see, the prompt for your assistant will get you there, or ask your account manager at [email protected].
Every report the API can run, with the id to pass to ?report=, what one row in it is, and the views it offers.
This is the full published set - 70 reports. What YOUR account can run is a subset of it, decided by your vertical, the audit priorities you have configured and what your subscription includes, so ask GET /v1/reports for the authoritative list rather than hardcoding ids from this page.
| Report | Category | One row is | Views | Periods |
|---|---|---|---|---|
|
Competitor Footprints
growth_competitor_position
Pages on your partner sites where a tracked competitor appears, with how many are on each page and which they are. The shortlist for a displacement conversation. |
Growth
Page level opportunities |
Pages | page | Current state |
|
Opportunities Already Raised
growth_outreach_done
Outreach you have already sent - who sent it, when, to whom, what it was about and what was offered - so a follow-up picks up the conversation rather than starting it again. |
Growth
Outreach |
Pages | page | 7d, 30d |
|
Opportunities Not Yet Actioned
growth_outreach_notsent
Everything sitting in your outreach queue that nobody has written to yet. The same partners the outreach board offers you, in the same order, minus the ones already contacted. |
Growth
Outreach |
Domains | domain | Current state |
|
Pages AI Assistants Quote
growth_ai_pages
The exact pages assistants pull their answers from in the most recent sweep, with the search that surfaced each one, what kind of question it was, and how often the page is cited. These are the pages worth being featured on, and the ones worth getting corrected when they are wrong about you. |
Growth
AI visibility |
Pages | page | Current state |
|
Partner Opportunity Scores
growth_opportunity_value
Your partners ranked by the size of the opportunity we can see behind them, with the gap pages that make up the number - so a week of outreach starts with the largest rather than the newest. |
Growth
Page level opportunities |
Domains | domain | Current state |
|
Partner Sales Funnels
growth_reach_route
Where each partner actually sends a buyer - to you, to a reseller, or to both - with how many pages route through a reseller and which resellers they are. The gap between a click you pay for and a sale you keep. |
Growth
New markets |
Domains | domain | Current state |
|
Placement Gaps
growth_accepted_pages
Pages a reviewer has accepted as relevant to you, with who reviewed each one and when. The work that has been done and is ready to take to a partner. |
Growth
Page level opportunities |
Pages | page | Current state |
|
Social Growth Opportunities
growth_social_reach
Your partners' social accounts ranked by the audience they reach, with how often they post and how much engagement they get - and a link straight to that account on the outreach board. |
Growth
New markets |
Social Posts | social | Current state |
|
Social Post Alerts: Brands
growth_social_alert_brands
Recent posts on your partners' social accounts that mention one of your brands or a tracked competitor - the profile, which brand, and when it was posted. One row per post, so this is longer than the count on the action card, which counts profiles. |
Growth
AI visibility |
Pages | page | Current state |
|
Social Post Alerts: Topics
growth_social_alert_topics
Recent posts on your partners' social accounts about the topics you track - the profile, which keyword matched, and when it was posted. The same window and the same profiles as the brand alerts, matched on your topic list instead. |
Growth
AI visibility |
Pages | page | Current state |
|
Top Growth Opportunities Assessed
growth_outreach_ready
Partners ranked by how much is open against them right now - placement gaps, AI citations and findings together - so one conversation covers all of it instead of three. |
Growth
Outreach |
Your Partners | domain | Current state |
|
Unlinked Brand Mentions
growth_exp_nolink
Pages naming your brand with no tracking link we could find - traffic and credit you are already earning and not capturing. There may be a link we cannot see behind a script or a redirect, so treat it as a list to check. |
Growth
Page level opportunities |
Pages | page | Current state |
|
Untapped Market Reach
growth_reach_untapped
Partners already reaching audiences in markets you do not currently run, with how much traffic over the last month and from where. An expansion shortlist built from partners who already know you. |
Growth
New markets |
Domains | domain | Current state |
|
Who AI Recommends in Your Category
growth_ai_cited
AI assistants now answer the questions your customers used to type into a search box, and the sites they cite are the ones shaping that answer. This is who they cite for your tracked searches in the most recent sweep, how often, whether you already work with them, and which are worth approaching. |
Growth
AI visibility |
Domains | domain | Current state |
|
App-Based Publishers
intel_pub_app
Partners advertising a mobile app, with the store listing we found - a channel your tracking may not follow. |
Intelligence
Publisher networks |
Domains | domain | Current state |
|
Brand Presence
intel_exp_presence
Partner sites where we have found your brand - either written about on a page, or linked to. Shows how many pages do each, so you can tell a publisher who writes about you from one who only carries a banner. |
Intelligence
Brand exposure |
Domains | domain | Current state |
|
Broken Affiliate Links
intel_exp_broken
Affiliate links on your partner sites that did not resolve when we followed them. Traffic you have already paid to create, going nowhere. |
Intelligence
Brand exposure |
Pages | page | Current state |
|
Browser Extension Publishers
intel_pub_extension
Partners advertising a browser extension, with the extension and the store behind it. Extensions rewrite attribution at the last click, so it pays to know who runs one. |
Intelligence
Publisher networks |
Domains | domain | Current state |
|
Competitor Exclusives
intel_comp_only
Partner sites where a tracked competitor appears and your brand does not - no mention of you on any page, and no link to you either. The clearest list of where an hour of outreach pays. |
Intelligence
Competitor strategies |
Domains | domain | Current state |
|
Competitor Mentions in Social
intel_comp_social
Social profiles posting about a tracked competitor, with which competitor, their following, and how relevant the profile is to your verticals. |
Intelligence
Competitor strategies |
Social Posts | social | Current state |
|
Competitor Presence
intel_comp_present
Which tracked competitors appear on which of your partner sites, in which markets, and how many pages each holds. |
Intelligence
Competitor strategies |
Domains | domain | Current state |
|
Connected Publisher Assets
intel_partner_connected
Which of your partners own more than one asset - other sites, social accounts - resolved from shared affiliate IDs, links and ownership signals. One partner behind six domains is one conversation, not six. |
Intelligence
Partner strategies |
Pages | page | Current state |
|
Coverage Gaps
intel_partner_nodata
Sites on your programme with no completed scan, and which of the three reasons applies - never queued, waiting, or scanned and failed. What the rest of this board cannot see. |
Intelligence
Partner strategies |
Domains | domain | Current state |
|
Deal and Incentive Publishers
intel_pub_coupon
Partners whose model is built on an incentive rather than on content - coupon and voucher sites, cashback, loyalty and rewards - with the site category and subtype the scan assigned, and what they publish about. The segment most likely to be capturing a sale you had already won. |
Intelligence
Publisher networks |
Domains | domain | Current state |
|
Dormant Social Profiles
intel_aud_socialdormant
Profiles with a real following that have stopped posting, ranked by how long it has been. A dormant profile with 40,000 followers is a different conversation from a small active one. |
Intelligence
Audience and value |
Social Profiles | social | Current state |
|
Paid Media Publishers
intel_pub_adnetworks
Partner sites running third-party advertising, and which networks were detected. Who is monetising your traffic on the way past. |
Intelligence
Publisher networks |
Domains | domain | Current state |
|
Partner Portfolio
intel_partner_portfolio
Every partner site we hold for you, with the partner behind it, the market, the site category, traffic band and when we last scanned it. Sites switched to inactive on your programme are left out. The list everything else on this board is built from. |
Intelligence
Partner strategies |
Domains | domain | Current state |
|
Partner Traffic by Market
intel_aud_traffic
Each partner site's estimated visits over the last month, in the selected market and across all markets, with the countries that make up most of it. |
Intelligence
Audience and value |
Domains | domain | Current state |
|
Partners by Portfolio Size
intel_partner_groups
Partners running more than one site for you, biggest portfolio first, so the ones where a single conversation covers several sites come first. Subnetworks are excluded - they are a route in, not a relationship. Shows the markets they cover and where the partner ID came from. |
Intelligence
Partner strategies |
Domains | domain | Current state |
|
Publisher Ownership and Contacts
intel_partner_owners
Who is behind each partner site - taken from the site's own entity and legal pages where we can read them, and from the domain record where we cannot. The company number is the field that matches exactly across sites, so it is what finds the ones quietly sharing an owner. |
Intelligence
Partner strategies |
Domains | domain | Current state |
|
Publisher Social Channels
intel_pub_socialplatforms
Each partner site with the social platforms linked to it, so you can see who is active on the channels you care about. |
Intelligence
Publisher networks |
Domains | domain | Current state |
|
Reseller Sales Pages
intel_pub_resellers
Partner pages that route the buyer through a reseller or marketplace rather than to you, with which resellers each page links to, whether your brand is named on the page, and whether the link is commercialised. |
Intelligence
Publisher networks |
Pages | page | Current state |
|
Scan Coverage and Freshness
intel_cov_freshness
Every site and market with the date we last scanned it, how stale that now is, and whether it has ever been scanned at all. |
Intelligence
What we hold |
Domains | domain | Current state |
|
Share of Voice
intel_comp_sov
Where a competitor is winning pages on sites you already pay for, biggest gap first. For each site: how many pages we looked at, how many mention you, who leads and by how much. Sites with fewer than five pages in the set are left out - a share of three pages describes the sample rather than your position. |
Intelligence
Competitor strategies |
Domains | domain | Current state |
|
Social Partner Assessments
intel_aud_recommendation
The work-with-them call on each social profile, with confidence, audience fit, professionalism and the verticals it covers. |
Intelligence
Audience and value |
Social Profiles | social | Current state |
|
Social Reach and Activity
intel_aud_social
Every social profile with its following, posts per week, engagement rate and last post - who is actually active behind the follower count. |
Intelligence
Audience and value |
Social Posts | social | Current state |
|
Social Scan Coverage
intel_cov_social
Every social profile with the date we last assessed it, its scan status, and whether it is queued, excluded or could not be retrieved. |
Intelligence
What we hold |
Social Profiles | social | Current state |
|
Sub-Affiliate Sources
intel_partner_subnetwork
Sites whose traffic arrives through a sub-affiliate or network rather than direct, with the partner ID and the markets. Where a programme's quality control is usually thinnest. |
Intelligence
Partner strategies |
Domains | domain | Current state |
|
Unattributed Partner Sites
intel_partner_unidentified
Sites in your programme we could not resolve to a partner ID or name from any source. Sites you are paying for and cannot put a name to. |
Intelligence
Partner strategies |
Domains | domain | Current state |
|
Your Affiliate Link Placements
intel_exp_linking
Every page on your partner sites carrying a link to you, with the anchor text, the affiliate ID, the link as written and where it finally lands. |
Intelligence
Brand exposure |
Pages | page | Current state |
|
Your Share of Voice in AI Answers
intel_ai_sov
How often assistants name you against each tracked competitor, out of every answer we sampled for your searches. The same question as share of voice on partner pages, asked of the answers customers now see instead of a results page. |
Intelligence
AI influence |
Pages | page | Current state |
|
Adult Content on Partner Sites
risk_adult_content_present
Your brand appearing alongside adult or pornographic content, with the page or post it was found on. A single screenshot is all it takes for this to become a brand problem. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
|
All Critical Risks
risk_all_critical
Every finding your configuration rates as critical, across all 7 checks, in one file - the site or profile, the market, which check it failed and what the scan found. |
Risk
Missing ad guidelines |
Your Partners | domain, social | Current state |
|
Brand Impersonation
risk_impersonates_brand_present
Partner sites and profiles presenting themselves as you or one of your brands, with the page or post and what they claim. The clearest case for immediate action on this board. |
Risk
Brand impersonation |
Your Partners | domain, social | Current state |
|
Browser Security Warnings
risk_browser_warnings_present
Partner sites where a browser raised a security or safety warning. Traffic sent here is being told to turn back, whatever the click data says. |
Risk
Site integrity |
Domains | domain | Current state |
|
Domain Registration Warnings
risk_domain_registration
Partner domains whose registration is worth a look - registered very recently, or expiring within the week. Both are how a partner site quietly becomes somebody else's. |
Risk
Technical health |
Domains | domain | Current state |
|
Explicit Sexual Language
risk_explicit_sexual_present
Partner sites and profiles using explicit sexual language on pages carrying your brand, with the wording found and where. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
|
Gambling brands mentioned
risk_gambling_brand_mentions_present
Partner sites and profiles naming gambling brands, with which brands and where. |
Risk
Regulated products |
Your Partners | domain, social | Current state |
|
Hate Speech and Extremism
risk_hate_speech_present
Hate speech or extremist material on partner sites and profiles you are associated with. The page or post, and what was found. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
|
Illegal Activity References
risk_illegal_activity_present
Partner sites and profiles referencing illegal activity, with the page or post and what was found. Worth checking before a renewal, not after a complaint. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
|
Low Quality Content Signals
risk_low_quality
Partner pages carrying one or more signals of low-quality publishing - links that do not resolve, thin or reworded content, pages that look machine-produced, unfinished copy - with which signal fired on each page. Signals, not verdicts. |
Risk
Quality issues |
Domains | domain | Current state |
|
Misleading Popups
risk_suspicious_popups_present
Popups and interstitials on partner pages that could mislead a visitor mid-journey, with the page they appeared on. |
Risk
Site integrity |
Domains | domain | Current state |
|
Missing Cookie Consent
risk_gdpr_consent_absent
Partner sites showing no cookie or consent notice in a market that requires one. Consent failures are enforced against the whole chain, not only the site that dropped the cookie. |
Risk
Disclosure and policy |
Domains | domain | Current state |
|
Missing Disclaimer
risk_has_disclaimer_absent
Partner sites promoting you with no disclaimer on any page we scanned. The market and the date last checked, so you can see how long it has been that way. |
Risk
Disclosure and policy |
Domains | domain | Current state |
|
Missing Privacy Policy
risk_has_privacy_policy_absent
A partner collecting visitor data without a published privacy policy is a data protection exposure attached to your brand. These sites have none we could find. |
Risk
Disclosure and policy |
Domains | domain | Current state |
|
Missing Responsible Gambling Message
risk_has_responsible_gambling_absent
Partner sites promoting gambling with no responsible gambling message on the pages we scanned, by market. |
Risk
Regulated products |
Domains | domain | Current state |
|
No age verification
risk_age_gate_absent
Partner sites and profiles carrying age-restricted content with no age gate in front of it, with the market. |
Risk
Regulated products |
Your Partners | domain, social | Current state |
|
No deposit limit information
risk_has_deposit_limits_absent
Partner sites promoting gambling with no deposit limit information. |
Risk
Regulated products |
Domains | domain | Current state |
|
No Licence or Regulator Named
risk_regulated_by_absent
Partner sites promoting regulated products without naming a licence, regulator or bonding scheme - the first thing a complaint or an audit will ask them for. |
Risk
Regulated products |
Your Partners | domain, social | Current state |
|
No safe gambling tools
risk_has_safe_gambling_tools_absent
Partner sites promoting gambling without pointing to any safer gambling tools. |
Risk
Regulated products |
Domains | domain | Current state |
|
No self-exclusion information
risk_has_self_exclusion_absent
Partner sites promoting gambling with no self-exclusion information. |
Risk
Regulated products |
Domains | domain | Current state |
|
Partner Sites Not Responding
risk_final_http_status_present
Sites that returned no page on the last scan, with the response we got and when we last reached them. You may still be paying for placement on them. |
Risk
Technical health |
Domains | domain | Current state |
|
Previously Reported Publishers
risk_previous_abuse_present
Partners with a history of abuse reports against them, with what was reported and when. Useful context before you widen a relationship. |
Risk
Brand safety |
Domains | domain | Current state |
|
Risk Decisions
risk_decisions
Every finding somebody on your team has flagged or marked as not an issue - the site or profile, which check, what they decided, any note they left, and when. A finding with a decision on it stops counting towards your risk numbers, so this is where it goes. |
Risk
Missing ad guidelines |
Pages | page | Current state |
|
Strong Language
risk_excessive_swearing_present
Partner content whose language may not suit your brand, with the page or post. Not a breach - a judgement you may want to make yourself. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
|
Threatening and Abusive Language
risk_harassment_present
Threatening or harassing language on partner sites and profiles carrying your brand, with the page or post it appeared on. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
|
Traffic Redirected Off-Site
risk_redirect_domains_present
Partner sites sending visitors to a domain other than the one they are on, with where they end up. Redirect chains are where attribution and consent both go missing. |
Risk
Site integrity |
Domains | domain | Current state |
|
Unlicensed Operators Promoted
risk_unlicensed_gambling_present
Partners promoting operators with no licence for the market they are being promoted in. This is the one that costs a licence rather than a warning: the operator named, the market, and the page it was on. |
Risk
Regulated products |
Your Partners | domain, social | Current state |
|
Unusual Scripts Detected
risk_malware_phishing_present
Scripts we could not account for on partner pages carrying your links, with the page and the script involved. Not a malware verdict - it is what to look at first. |
Risk
Site integrity |
Your Partners | domain, social | Current state |
|
Violence and Weapons References
risk_violence_weapons_present
References to violence or weapons on partner content carrying your brand, with the page or post it was found on. |
Risk
Brand safety |
Your Partners | domain, social | Current state |
One entry per asset. Domains and social profiles come back in the same list, each carrying its type, the identifier the detail endpoints take, where it came from, when we last looked at it and whether you can ask us to look again.
Start here. Walk it with the cursor to synchronise your own systems, or filter it to find the identifier you need. Domains are returned first, alphabetically, then social profiles by platform and handle.
| Name | In | Default | Description |
|---|---|---|---|
| type string | query | all | Restrict to one kind of asset. One of: all, domain, social |
| detail string | query | simple | simple returns identity and status. full adds partner, vertical, traffic band, and the social accounts found on each domain, each with its own assessed_for block. One of: simple, full |
| iso string | query | - | Two-letter market code. Applies to domains only - social profiles are not market scoped. |
| platform string | query | - | Restrict the social side to one platform. One of: instagram, tiktok, youtube, twitter, pinterest |
| search string | query | - | Substring match on the domain or the handle. |
| limit integer | query | 100 | Rows per page, up to 500. |
| cursor string | query | - | Pass back the next_cursor from the previous response. Null next_cursor means you have seen everything. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
Counts for THIS PAGE, not for the whole account - walk the cursor to the end to total everything.
| Field | Type | Description |
|---|---|---|
| summary.total | integer | Assets returned in this response. |
| summary.domains | integer | How many of those are domains. |
| summary.social_profiles | integer | How many are social profiles. |
Fields present on both kinds of asset.
| Field | Type | Description |
|---|---|---|
| assets[].type | string | domain or social. Everything else on the row depends on this. |
| assets[].id | string | The identifier the detail endpoints take: the domain, or platform:handle. Null on a social row whose handle we cannot resolve - see note. |
| assets[].status | string | Domains: scanned, in_progress or unscanned. Social: assessed or requested. |
| assets[].last_scanned | date | When we last completed a scan or assessment. Empty means never. |
| assets[].next_scheduled | date | ESTIMATE, domains only: the last scan plus your account cycle. It is not a booked slot and it can move. |
| assets[].refreshable | boolean | Whether you can ask us to look again. Always false for domains - they run to a schedule you cannot change. False on a social profile inside its seven-day cooldown, or on a platform we record but do not assess. |
| assets[].note | string | Only present when something about the row needs explaining, e.g. an assessment we hold but cannot tie to a usable handle. |
One row per domain, not per domain and market. The markets it has been scanned in are on the row.
| Field | Type | Description |
|---|---|---|
| assets[].iso | string | The market of the scan this row describes. |
| assets[].markets[] | array | Every market we hold activity for on this domain. |
One row per profile, across every platform we record.
| Field | Type | Description |
|---|---|---|
| assets[].platform | string | instagram, tiktok, youtube, twitter or pinterest. x is normalised to twitter. |
| assets[].handle | string | Account handle, lower-cased and with the @ stripped. |
| assets[].request_status | string | Only when an assessment is queued. Where that request has got to. |
Only attached when detail=full. Each one costs an extra lookup, so the simple list stays fast for callers who only want identifiers.
| Field | Type | Description |
|---|---|---|
| assets[].site_id | string | Our internal site id. Domain rows. |
| assets[].vertical | string | Sector the domain was classified into. |
| assets[].partner_company | string | Partner or publisher name, where we have resolved one. |
| assets[].partner_affid | string | Affiliate id we hold against the domain. |
| assets[].est_monthly_traffic | string | A BAND, e.g. "100k - 500k". Never a raw visit count - that data is third-party licensed. |
| assets[].social_profiles[] | array | Domain rows: the platform:handle ids this domain's own scan links to. Each is a separate asset in the social segment, where its state and scores live. |
| assets[].profile_id | string | Social rows: our internal id for the profile. |
| assets[].followers | integer | Social rows: audience size. Null when we hold no figure. |
Paging is by POSITION, not offset, so rows added or removed between calls cannot make you skip or repeat one.
| Field | Type | Description |
|---|---|---|
| next_cursor | string | Pass back as ?cursor= for the next page. NULL means you have seen everything. "s:" with no key means the domains are finished and the social segment starts next. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Reflects the most recent completed scan or assessment for each asset. last_scanned dates every row. |
| Coverage | Domains are those your account has compliance activity for. The social SEGMENT is your own assets: profiles assessed for your account plus any currently queued, minus any you have excluded. The social accounts listed on a DOMAIN row are a different set - they are whatever that site links to, so many of them are assessed for somebody else or not at all, which is what their assessed_for block tells you. Health findings are not on this list - use Domains only or By Domain for those. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The per-domain summary the Domain Intelligence table is built from: scan status, vertical, sub-network detection, partner, traffic band, health priority counts, social profiles and top countries.
Use this when you want the domain view specifically. For domains and social profiles together, use /v1/assets.
| Name | In | Default | Description |
|---|---|---|---|
| iso string | query | - | Two-letter market code. Omit or send XX for all markets. |
| search string | query | - | Substring match on the domain. |
| include string | query | - | raw adds the heavier exposure, offers and growth blocks per domain. One of: raw |
| health string | query | - | Restrict to domains with health findings. One of: 1 |
| auditfilter string | query | - | Audit field id to require a match for. Adds audit_evidence to each row. |
| limit integer | query | 5000 | Maximum rows, capped at 5000. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
Totals across every domain returned.
| Field | Type | Description |
|---|---|---|
| summary.total_domains | integer | Domains in the response. |
| summary.scanned_count | integer | Domains whose last run completed. |
| summary.in_progress_count | integer | Domains with a run that has not completed. |
| summary.subnetwork_count | integer | Domains identified as sub-network or sub-affiliate. |
| summary.exposure_count | integer | Domains with brand exposure. include=raw only. |
| summary.offers_count | integer | Domains with monitored offers. include=raw only. |
| summary.growth_count | integer | Domains with a growth opportunity. include=raw only. |
| summary.review_pass_count | integer | Domains a reviewer marked pass. |
| summary.review_fail_count | integer | Domains a reviewer marked fail. |
| summary.review_ticked_count | integer | Domains ticked off by a reviewer. |
| summary.priority_critical_total | integer | Critical health findings across all domains. |
| summary.priority_important_total | integer | Important findings across all domains. |
| summary.priority_interesting_total | integer | Interesting findings across all domains. |
One row per domain, mirroring the Domain Intelligence table.
| Field | Type | Description |
|---|---|---|
| domains[].domain | string | The domain. |
| domains[].iso | string | Market this row describes. |
| domains[].site_id | string | Our internal site id. |
| domains[].scan_status | string | Raw status of the latest run, e.g. completed. |
| domains[].scanned_at | datetime | When the latest scan ran. |
| domains[].updated_at | datetime | When the scan record last changed. |
| domains[].pagehash | string | Content hash of the scanned page, for change detection. |
| domains[].vertical | string | Sector the domain was classified into. |
| domains[].is_subnetwork | boolean | Whether the domain looks like a sub-network or sub-affiliate. |
| domains[].subnetwork_label | string | Readable reason, e.g. Subnetwork via <entity>. |
| domains[].subnetwork_signals[] | array | What triggered it: signal, affid, entity, networkcode, ctype, description. |
| domains[].partner_company | string | Partner or publisher company name. |
| domains[].partner_affid | string | Affiliate id. |
| domains[].est_monthly_traffic | integer | Banded monthly visits. Rounded, never the raw figure. |
| domains[].top_countries[] | array | Largest traffic markets, with share. |
| domains[].social_profiles | object | One URL per platform found on the site: facebook, instagram, twitter, youtube, linkedin, pinterest, tiktok, linktree. |
Health findings and the reviewer verdict for the domain.
| Field | Type | Description |
|---|---|---|
| health.priority_counts.critical | integer | Critical findings outstanding. |
| health.priority_counts.important | integer | Important findings outstanding. |
| health.priority_counts.interesting | integer | Interesting findings outstanding. |
| health.priority_labels | object | The finding names behind each count. |
| health.has_priorities_configured | boolean | False means nobody has set priorities, so zero counts mean untested rather than clean. |
| health.verdict | string | pass, fail or empty. |
| health.tick_state | integer | Reviewer tick state. |
| health.note | string | Reviewer note. |
| health.reviewed_at | datetime | When it was reviewed. |
| health.reviewed_by | string | Who reviewed it. |
Only attached when include=raw. Left off by default because each one costs a further batched query.
| Field | Type | Description |
|---|---|---|
| domains[].exposure_pages | integer | Unique pages carrying a brand link, mention or topic match. |
| domains[].offers.monitored | boolean | Whether offer monitoring is on for this domain. |
| domains[].offers.page_count | integer | Pages with monitored offers. |
| domains[].offers.is_fresh | boolean | Whether the offer data is newer than the last domain scan. |
| domains[].has_growth | boolean | Whether any actionable growth opportunity exists. |
| domains[].audit_evidence | string | Only when auditfilter is supplied. The evidence that matched. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Scan status and dates come from the latest run per domain and market. |
| Coverage | One entry per domain your account has compliance activity for. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Every report on your Reports board, with the id to run it, the views it offers, the periods it can be narrowed to and the exact columns it will return.
Start here. Your report set is not the same as anybody else's - it is built from your vertical, your audit priorities and your subscription - so the ids have to be discovered rather than hardcoded.
| Name | In | Default | Description |
|---|---|---|---|
| iso string | query | - | Two-letter market code. Affects which risk reports exist, because priorities can be set per market. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
The whole list comes back in one response - there is no paging on the report list itself.
| Field | Type | Description |
|---|---|---|
| summary.total | integer | How many reports your account can run. |
One entry per runnable report. A report the index cannot yet answer is left out rather than listed and then refused.
| Field | Type | Description |
|---|---|---|
| reports[].report | string | The id to pass back as ?report=. Stable; safe to store against your own records. |
| reports[].name | string | What the report is called on your board, including any rename an administrator made. |
| reports[].description | string | What the report answers, in one sentence. |
| reports[].category | string | risk, insights or growth - the board column it sits in. |
| reports[].family | string | The finer grouping used to order cards within a column. |
| reports[].priority | string | Your own severity for the underlying check, on risk reports. Empty elsewhere - intelligence reports have no severity matrix behind them, and an empty value there is the absence of the concept rather than a level. |
| reports[].grains[] | array | The views this report offers: domain, social, page. Only ones that can actually be run are listed. |
| reports[].default_grain | string | What you get if you do not send grain. |
| reports[].windows[] | array | Periods in days this report can be narrowed to with ?days=. Empty means the report is about current state and has no period. |
| reports[].tags[] | array | The hashtags shown on the card, including any your account has added. |
| reports[].columns[].key | string | The key each row is keyed by in report_get. Never changes. |
| reports[].columns[].label | string | The heading, as your account has it. Editable, so do not key off it. |
| reports[].columns[].essential | boolean | True where the column is set for the whole account and cannot be switched off. False means it is optional and somebody on your account chose to include it. |
| reports[].href | string | A ready-made URL that runs this report with its defaults. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | The list itself is built per request from your current configuration, so a report appears the moment a gate opens and disappears when one closes. |
| Coverage | Only reports that can actually be served are listed. A report the index cannot yet answer is left out rather than listed and then refused, and a report an administrator has archived is off the API for the same reason it is off the board. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The rows of one report, in the same columns and the same order as the spreadsheet that report downloads - because it is the same report definition, the same column set and the same sort, resolved once.
When you want a report as data rather than as a file: to feed a dashboard, to drive an outreach queue, or to diff against yesterday.
| Name | In | Default | Description |
|---|---|---|---|
| report required string | path | - | A report id from /v1/reports. Omit it entirely and you get the list instead. |
| grain string | query | - | Which view of the report. Defaults to the first one it offers; a report with only one view ignores this. One of: domain, social, page |
| iso string | query | - | Restrict to one market. Omit for every market. |
| days integer | query | - | Period, for the reports that have one - see windows on the list. Anything else falls back to the widest the report offers. |
| limit integer | query | 100 | Rows per page, up to 1000. |
| cursor integer | query | 0 | Pass back next_cursor from the previous response. Null next_cursor means you have seen everything. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
What was run, resolved rather than echoed - so you can see which market and period you actually got.
| Field | Type | Description |
|---|---|---|
| report.id | string | The report id. |
| report.name | string | Its name on your board. |
| report.description | string | What it answers. |
| report.category | string | risk, insights or growth. |
| report.grain | string | The view actually served. A report offering one view serves that view whatever you asked for. |
| report.grains[] | array | Every view it offers. |
| report.iso | string | The market applied, or empty for all markets. |
| report.days | integer | The period applied, or null where the report has no period. Not always what you sent - a value the report does not offer falls back to the widest it does. |
| report.windows[] | array | The periods available, for building your own control. |
| report.built_at | date | When the index these rows came from was built. Empty on the page reports, which read live tables. |
The contract for the rows below, in the order the spreadsheet would print them.
| Field | Type | Description |
|---|---|---|
| columns[].key | string | The key this column appears under on every row. |
| columns[].label | string | The heading your account uses for it. |
| columns[].type | string | string, number, date or url - enough to format a cell without inspecting the values. |
The total is for the whole report, not the page, so you know how far the walk goes before you start it.
| Field | Type | Description |
|---|---|---|
| paging.total | integer | Rows the report returns in total for this market and period. |
| paging.returned | integer | Rows in this response. |
| paging.limit | integer | The page size applied. |
| paging.cursor | integer | Where this page started. |
| paging.next_cursor | integer | Pass back as ?cursor=. Null means you have seen everything. |
| paging.stable | boolean | True where the rows come from the overnight index, which does not move during the day, so a walk sees one consistent set. False on the page reports, which read live tables - a row inserted mid-walk can shift the rest by one. |
KEYED BY COLUMN KEY, NOT BY LABEL. Which keys appear is decided by your configuration - read columns rather than assuming. The list below is what the keys mean when they are present.
| Field | Type | Description |
|---|---|---|
| rows[].DOMAIN | string | The partner site. |
| rows[].PARTNER | string | The partner, by name where we hold one and by affiliate id otherwise. Always populated where we know anything at all about who runs the site. |
| rows[].PARTNER_ID | string | The affiliate id on its own. |
| rows[].ISO | string | The market this row was found in. |
| rows[].SCAN_AT | date | When the row was last scanned or assessed. |
| rows[].RISK_CRITICAL | number | Critical findings on the site or profile - all of them, not only the one this report is about. |
| rows[].RISK_ITEMS | array | The OTHER findings on the row, as names rather than field ids, with this report's own check removed. An array, not a comma string - a label can contain a comma. |
| rows[].EVIDENCE | string | What we found, for the check this report is about. Empty is a real answer: some checks match on a signal there is nothing to quote for. |
| rows[].PROFILE_URL | string | The way back into Rightlander for this row. |
| rows[].OUTREACH_URL | string | Straight into the outreach page with this partner in focus. |
| rows[].PLATFORM | string | Social rows: the platform. |
| rows[].HANDLE | string | Social rows: the account handle. |
| rows[].LINKED_DOMAIN | string | Social rows: the site the profile belongs to, where we can tie it to one. |
| rows[].SOV_SHARE | number | Share of voice as a number, not a formatted percentage. Null where we found no pages to divide by, which is not the same as a nil share. |
| rows[].PAGE_URL | string | Page reports: the URL the row is about. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Facet-served reports read the overnight index and built_at dates it. The page reports read live tables and have no build date. |
| Coverage | The same rows the download would produce for the same report, market and period. If the board shows a count on the card, this returns that many rows. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The Partner Activity Feed as data: critical risks, brand bidding, offer changes, link anomalies, growth pages, AI influence, partner post mentions and team activity, one row per item, ordered by when it happened.
Poll it once a day to drive your own alerting or a changelog, and de-duplicate on id. For what is outstanding rather than what changed, use Reports.
| Name | In | Default | Description |
|---|---|---|---|
| days integer | query | 1 | How far back to look, 1 to 90. 1 is the last 24 hours. Compared by day, like the daily alert email, so the window starts at midnight on the first day it covers. Sets the price. |
| category string | query | - | Restrict to these kinds of item. Comma separated for more than one. Omit for all. An unknown value is a 400 that lists the valid ones. One of: risk_domain, risk_social, ppc, offers, anomalies, growth, llm, social_brand, social_comp, social_topic, team |
| iso string | query | - | Two-letter market code. Omit or send XX for every market. |
| max integer | query | 100 | Most items to return, 1 to 500. The newest are kept; summary.capped says whether any were left out. |
| accounts string | query | - | Comma separated account codes. Omit for the account your key belongs to. Each account read is charged separately, and a code your key is not authorised for is refused with 403. |
| client_ref string | query | - | Networks: your ID for one client. Returns that client's feed - items from its own account (scope client) once it has signed up, and from your scans (scope network) - limited to the domains you sent for it. Cannot be combined with accounts; team items are left out. Charged as one account. |
| uid string | query | - | Networks that personalise per user: one user of client_ref. Returns that user's feed - limited to the partner domains you sent for the user (the client's list until you send one), and the user's own items once it has personalised. client.personalise_url is signed for that user. Ignored, with a note, if your feeds are personalised per client. |
| render string | query | - | html adds ready-made HTML in your feed style: each item's html, plus render.html for the whole page. The stylesheet is downloaded once from your guided setup, not sent here. Set the style in your guided setup or with feed_style on POST /v1/network. Omit for data only. One of: html |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
What was run, as resolved rather than echoed, so you can see the window and filters you actually got.
| Field | Type | Description |
|---|---|---|
| request.endpoint | string | Always activity. |
| request.accounts[] | array | The account codes read. Your own unless you named others your key is authorised for. |
| request.days | integer | The window in days, after any adjustment. |
| request.max | integer | The item limit applied. |
| request.categories[] | array | The categories read, or all. |
| request.iso | string | The market applied, or XX for every market. |
| request.client_ref | string | The client_ref sent, or null. |
| request.adjusted[] | array | Anything we changed about your request and why - a days value above 90 is reduced, for example. Empty when nothing was. |
Networks: whose feed this is, under client_ref. Null on an ordinary call.
| Field | Type | Description |
|---|---|---|
| client.client_ref | string | Your ID for the client. |
| client.status | string | pending (not signed up), active or cancelled. |
| client.personalised | boolean | True when items from the client's own account are included. False means network items only. |
| client.account | string | The client's Rightlander account code when personalised. Null otherwise. |
| client.partner_domains | integer | Active domains on the list you sent for this client - the list every item was limited to. |
| client.personalise_url | string | The "Personalise my feed" link for this client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise, so networkModal.js opens it in a modal. Optional prefills may be added to the end, URL-encoded and unsigned: email (shown read-only; free email services other than gmail.com refused unless signed), name, company, brand, domain. Null once the client has a personalised feed. |
| client.settings_url | string | The "Edit my feed settings" link for a personalised client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise: it opens the client's settings in the modal, where it can change its products, what its feed shows and its plan, or ask to cancel. Null until the client is personalised. |
The period the items were read from.
| Field | Type | Description |
|---|---|---|
| window.hours | integer | days x 24. |
| window.from | date | The first day included. The window is compared by day, so it starts at midnight on this date. |
| window.to | datetime | When the request was answered. |
| window.grain | string | Always day - stated rather than left to be discovered. |
| window.index_built_at | datetime | When the overnight index behind the overnight categories was last built. Null if it has never been built. |
| window.index_ok | boolean | False when that index could not be read, so the overnight categories may be missing rather than empty. |
What this request cost and why.
| Field | Type | Description |
|---|---|---|
| credits.charged | integer | Credits taken. 0 when the window was empty, and always 0 on a trial. |
| credits.price | integer | What the request costs when it returns something: days x accounts x the unit price. |
| credits.basis | string | The unit price in words. |
| credits.trial | boolean | True on a trial account, which is metered by its request allowance instead of by credits. |
| credits.free_when_empty | boolean | Always true: an empty window is never charged. |
Counts for the response.
| Field | Type | Description |
|---|---|---|
| summary.returned | integer | Items in events. |
| summary.total_in_window | integer | Items found in the window before max was applied. |
| summary.capped | boolean | True when max left items out. The newest are the ones kept. |
| summary.folded_repeats | integer | Repeat sightings folded into existing items rather than listed again. |
| summary.by_family.risk | integer | Returned items in the risk family. |
| summary.by_family.opportunity | integer | Returned items in the opportunity family. |
| summary.by_family.team | integer | Returned items describing what your team did. |
| summary.by_scope.network | integer | Returned items from your own account's scans. |
| summary.by_scope.client | integer | Returned items from the client's own account, under client_ref. |
| summary.by_category | object | Returned items per category key. Every category is present, at 0 when it had nothing. |
| summary.not_on_client_list | integer | Under client_ref, items left out because their domain is not on the client's list. Null on an ordinary call. |
One entry per day of the window, newest first, including days with nothing - a gap in a list of dates would read as missing data.
| Field | Type | Description |
|---|---|---|
| by_day[].day | date | The day. |
| by_day[].total | integer | Returned items dated that day. |
| by_day[].categories | object | Those items per category key. Empty on a quiet day. |
The items, newest first.
| Field | Type | Description |
|---|---|---|
| events[].id | string | Stable identity for the item: the same thing seen again tomorrow has the same id. De-duplicate on this. |
| events[].revision | string | Changes when the findings behind a risk item change, so the same site with a different problem can be told apart from the same problem still there. Null on items that carry no findings. |
| events[].account | string | The account the item belongs to. |
| events[].scope | string | network - from your own account's scans. client - from the client's own account, under client_ref. example - networks only: Relevant content, found by the generic product profiles for your verticals, not for any one client. |
| events[].scope_label | string | Relevant content on example items. Null otherwise. |
| events[].example_note | string | On example items only: the note to show beside the item. Null otherwise. |
| events[].brands_hidden | boolean | Networks only: true on a Brand bidding indicator in the network's own items - seen bidding on brand searches, with the brands, the ad text and its links left out for privacy. Absent otherwise. |
| events[].category | string | The category key - see categories. |
| events[].category_label | string | Its name as the Activity Feed page shows it. |
| events[].category_colour | string | The category's colour as a hex value, such as #d93025 for a critical risk on a site - the colour the Activity Feed page and our emails use, so you can match them. |
| events[].family | string | risk, opportunity or team. |
| events[].happened_at | datetime | When it happened - the FIRST sighting in the window. A scan finding carries its scan date at midnight; a post carries its publish time. |
| events[].day | date | The date part of happened_at. |
| events[].last_seen_at | datetime | The latest sighting, when there was more than one. Null otherwise. |
| events[].repeats | integer | How many times the item was logged in the window. |
| events[].iso | string | The market it was found in. Null where the source has no market. |
| events[].markets[] | array | Every market it was found in, when there were several. |
| events[].title | string | What happened, in words. |
| events[].detail | string | The evidence in one line - the fields found, the phrase matched, the page. |
| events[].evidence[].text | string | One line of evidence. Social items carry a line per post. |
| events[].evidence[].url | string | Where to see that evidence. Null when there is nowhere to send you. |
| events[].evidence[].external | boolean | True when the link leaves Rightlander - the partner's own page or post. |
| events[].items | integer | How many things the item stands for, where that is more than one - cited pages on an AI influence item, ID combinations on an anomaly. Null otherwise. |
| events[].asset.kind | string | domain, social or account. |
| events[].asset.name | string | What it happened to - a domain, or platform / @handle. |
| events[].asset.handle | string | The social handle, without the at sign. Null on other items. |
| events[].asset.domain | string | The partner's domain the item resolves to. On a social item, the site the account belongs to. Null when there is none. |
| events[].asset.url | string | The asset's own home - the site, or the profile. Null when it cannot be trusted. |
| events[].partner.name | string | The partner, where we hold one. |
| events[].partner.affid | string | Their affiliate id, where we hold one. |
| events[].affiliate_id | string | The affiliate ID you sent with the domain on POST /v1/partner-domains, else partner.affid. The field to join an item to your own affiliate records on. Null when neither is held. |
| events[].audience.count | integer | How many people the asset reaches. The whole audience object is null when unknown. |
| events[].audience.unit | string | What count measures: visits for a site, followers for an account. Never read the number without it. |
| events[].links.rightlander | string | The Rightlander screen to act on the item. Null in a feed for a client or user (client_ref): use open there. |
| events[].links.share | string | A link to hand to a colleague - the partner's Domain Profile where the item has a domain. Null in a feed for a client or user (client_ref): use open there. |
| events[].links.external | string | The item itself off-platform - the post or the cited page. Null when there is none. |
| events[].by | string | On team items, the name of the colleague who did it. Null on everything else. |
| events[].freshness | string | overnight, scheduled or live - how current this category's data is. |
| events[].link | string | Networks only: a read-only page for this one item that your client can open without a login, in your branding. Works for 30 days; the same item keeps the same link. Null for other accounts. Open it in a new window. |
| events[].open | string | Networks, in a feed for a client or user that has personalised: on the client's own items (scope client), a link that opens the Rightlander page for the item, signed in as the client, with no Rightlander menus, read only. Works for 7 days; the same item keeps the same link. Open it in a new window (a top-level window, not a frame). Null on other items: use link. Brand mention, competitor mention and product relevance items open the page or post itself instead: links.external. |
| events[].personalise_url | string | Networks, in a feed for a client or user that has not personalised: a "Personalise my feed" link signed for them, on brand, competitor, growth and product relevance items, when Rightlander has switched this on for you (every item, or every nth). Absent otherwise. |
How each category's read went, so a quiet day and a failed read never look the same.
| Field | Type | Description |
|---|---|---|
| sources[].category | string | The category key. |
| sources[].label | string | Its name. |
| sources[].status | string | ok, partial (some accounts read, some did not), skipped or unavailable. |
| sources[].items | integer | Items the source found, before repeats were folded and max applied. |
| sources[].freshness | string | overnight, scheduled or live. |
| sources[].note | string | Why a source is partial or unavailable. Null when it read normally. |
Every category the feed knows, for building your own filter or legend.
| Field | Type | Description |
|---|---|---|
| categories[].category | string | The key to pass in ?category=. |
| categories[].label | string | Its name. |
| categories[].colour | string | Its colour as a hex value, as the Activity Feed page shows it. |
| categories[].family | string | risk, opportunity or team. |
| categories[].description | string | What an item in it means, in one sentence. |
| categories[].freshness | string | overnight, scheduled or live. |
render=html only; null otherwise.
| Field | Type | Description |
|---|---|---|
| events[].html | string | The item as a ready-made block of HTML in your feed style. |
| render.wrapper | string | The classes for the div you put the saved items in, such as rlf-feed rlf-cards rlf-light rlf-comfortable. The stylesheet itself is downloaded once from your guided setup. |
| render.html | string | Every item returned, in a wrapper, ready to drop into your page. |
| render.style | object | The feed style used - the same object as feed_style on GET /v1/network. |
Plain-English reminders about reading the response.
| Field | Type | Description |
|---|---|---|
| notes[] | array | Short sentences. Includes a note when nothing was charged because the window was empty. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Mixed, and every row says which. Critical risks, growth pages and link anomalies come from an index rebuilt overnight, so a finding from today's scan appears tomorrow and window.index_built_at dates it. AI influence follows its own scheduled build. Offer changes, partner posts and team activity are live. |
| Coverage | Every partner site and social account on your account, less anything you marked as a trusted source and any item you dismissed. Your own sites, accounts and paid ads are left out - you are not your own partner. Brand bidding lists an advert once, on the day it was first seen; an advert already running before the window is not news and is not repeated. A source that could not be read is reported in sources rather than returned as a silent zero. |
| Permission | A key needs the read permission. |
| Cost | 1 credit per day, per account. Charged only when the response contains at least one item - an empty window is free. A refused or failed request is never charged, and trial accounts are not charged credits. |
This endpoint can return any of the shared errors described under Errors. Because it costs credits it can also return 402 insufficient_credits.
The markets you have compliance reports in, the month tables we hold for each and which source they come from. It also lists your reports with their ids and priorities.
Start here. It tells you which iso, month and report_id values the other two endpoints will answer for.
None.
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
What was run and where you stand against the compliance limit.
| Field | Type | Description |
|---|---|---|
| request.endpoint | string | Always compliance_markets. |
| request.compliance_limit.calls_per_day | integer | Compliance calls your account is allowed a day, shared by the three compliance endpoints. |
| request.compliance_limit.used_today | integer | Compliance calls made today, including this one. |
| request.compliance_limit.remaining | integer | What is left today. |
| request.compliance_limit.resets_at | datetime | When it resets. 00:00 UTC. |
The account your key belongs to.
| Field | Type | Description |
|---|---|---|
| account | string | Your account code. |
The current scan cycle, so you know which months the cycle endpoint reads.
| Field | Type | Description |
|---|---|---|
| scan_cycle.months[] | array | The two months of the current scan cycle, newest first, as YYYY-MM. |
| scan_cycle.from | date | The first day of the cycle. |
| scan_cycle.rolls_over_at | datetime | When the cycle moves on and the older month leaves it. |
Whether each source could be read on this request.
| Field | Type | Description |
|---|---|---|
| sources[].source | string | discovery or requested. |
| sources[].status | string | ok, or unavailable when that source could not be read just now. |
One entry per market you have compliance reports in.
| Field | Type | Description |
|---|---|---|
| markets[].iso | string | Two-letter market, or XX for worldwide. |
| markets[].name | string | The market name. |
| markets[].sources[].source | string | discovery or requested. |
| markets[].sources[].status | string | Always ok here: a source that could not be read is reported in sources instead. |
| markets[].sources[].months[] | array | Month tables that exist, newest first, as YYYY-MM, up to 24 months back. |
| markets[].sources[].reports | integer | How many of your reports this source holds for the market. |
Your compliance reports. report_id is what the item endpoints take.
| Field | Type | Description |
|---|---|---|
| reports[].report_id | integer | The report id. |
| reports[].source | string | discovery or requested. Ids are only unique within a source. |
| reports[].iso | string | The market the report runs in. |
| reports[].title | string | The report title. |
| reports[].priority | integer | 1 high, 2 medium, 3 low. |
| reports[].priority_label | string | High, Medium or Low. |
| reports[].active | boolean | False for a report that has been switched off. Its items still appear in a month read. |
Plain-English notes on what was returned.
| Field | Type | Description |
|---|---|---|
| notes[] | array | Notes about this response. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. |
| Coverage | Reports your account owns, active or switched off. months are the tables that exist for a market, up to 24 months back; a month can exist and hold nothing for you. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The items the Compliance Workbench shows for one market, from this month and last month together, with the action taken on each, who took it and when.
To keep your own systems in step with the workbench. Read it with since to pick up only what changed. Page it with limit and cursor.
| Name | In | Default | Description |
|---|---|---|---|
| iso required string | path | - | Two-letter market, or XX for worldwide. |
| source string | query | - | discovery is our scanning across the market as a whole and requested is the scanning set up for your account alone. Omit for both. One of: discovery, requested |
| status string | query | all | Which items. resolved is any action. Omit for all of them. One of: all, unresolved, resolved, flagged, non_issue, ignored |
| report_id integer | query | - | One of your reports, from GET /v1/compliance/markets. |
| report_priority integer | query | - | Reports of one priority: 1 high, 2 medium, 3 low. One of: 1, 2, 3 |
| domain string | query | - | One partner domain. |
| affid string | query | - | One affiliate ID. The prefixed forms the scanner records (btag=, affid= and so on) are matched too. |
| brand string | query | - | One or more of your brand names, comma separated. |
| state string | query | - | With iso=XX only: a two-letter state or country code the item was scanned in. |
| since string | query | - | YYYY-MM-DD. Items reported, scanned or actioned on or after this date. |
| detail string | query | full | simple leaves out findings and returns finding_count and the short issue text in result. One of: full, simple |
| limit integer | query | 100 | Items per page, up to 500. |
| cursor string | query | - | Pass back next_cursor from the previous response. Null next_cursor means you have seen everything. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
What was run as resolved rather than echoed, with where you stand against the compliance limit.
| Field | Type | Description |
|---|---|---|
| request.endpoint | string | Always compliance_items. |
| request.iso | string | The market read. |
| request.period | string | cycle, or the month read as YYYY-MM. |
| request.source | string | discovery, requested or all. |
| request.status | string | The status filter applied. |
| request.detail | string | full or simple. |
| request.limit | integer | Items per page. |
| request.filters | object | The other filters applied, by name. |
| request.adjusted[] | array | Anything we changed about the request, such as a limit brought down to the maximum. |
| request.compliance_limit.calls_per_day | integer | Compliance calls your account is allowed a day, shared by the three compliance endpoints. |
| request.compliance_limit.used_today | integer | Compliance calls made today, including this one. |
| request.compliance_limit.remaining | integer | What is left today. |
| request.compliance_limit.resets_at | datetime | When it resets. 00:00 UTC. |
The tables read.
| Field | Type | Description |
|---|---|---|
| period.type | string | cycle or month. |
| period.tables[] | array | Cycle only. The two month tables, newest first, such as GB202611. |
| period.from | date | Cycle only. The first day of the cycle. |
| period.to | date | Cycle only. The last day of the current month. |
| period.rolls_over_at | datetime | Cycle only. When the cycle moves on. |
| period.table | string | Month only. The table read, such as GB202610. |
| period.month | string | Month only. YYYY-MM. |
| period.in_current_cycle | boolean | Month only. True while the month is in the scan cycle and its actions can still change. |
Each source read, so a source we could not reach is never mistaken for one with nothing in it.
| Field | Type | Description |
|---|---|---|
| sources[].source | string | discovery or requested. |
| sources[].status | string | ok, partial or unavailable. |
| sources[].items | integer | Items from this source on this page. |
| sources[].reports | integer | Your reports this source holds for the market and period. |
| sources[].note | string | Present when status is not ok. |
Totals for the whole read, on the first page only. Null on later pages.
| Field | Type | Description |
|---|---|---|
| summary.items | integer | Items across all pages. |
| summary.unresolved | integer | Items with no action yet. |
| summary.flagged | integer | Items flagged for action. |
| summary.non_issue | integer | Items marked as a non-issue. |
| summary.ignored | integer | Items ignored. |
| summary.by_report_priority | object | The same four counts for high, medium and low priority reports. |
| summary.domains | integer | Distinct partner domains among the items. |
One entry per workbench item: an issue found on one page by one report.
| Field | Type | Description |
|---|---|---|
| items[].id | string | The item id, such as discovery:GB202611-4821. Also what the screenshot link takes. |
| items[].issue_key | string | The same for the same issue on the same page in any month, so you can follow it when id changes. |
| items[].source | string | discovery (our scanning across the market) or requested (scanning set up for your account). |
| items[].table | string | The month table the item is from, such as GB202611. |
| items[].row_id | integer | The row within that table. |
| items[].also_reported_in[] | array | Cycle only. The same issue in the older month of the cycle, by item id. |
| items[].iso | string | The market. |
| items[].state_iso | string | Where it differs from iso, the state or country the item was scanned in, such as NJ. Null otherwise. |
| items[].status | string | unresolved, flagged, non_issue or ignored. |
| items[].report.id | integer | The report that found it. |
| items[].report.title | string | Its title. |
| items[].report.priority | integer | 1 high, 2 medium, 3 low. |
| items[].report.priority_label | string | High, Medium or Low. |
| items[].page.url | string | The page. For a social post, the post itself. |
| items[].page.domain | string | The partner domain. |
| items[].page.title | string | The page title, where we recorded one. |
| items[].page.type | string | web, social, telegram or email. |
| items[].page.page_scan | boolean | True when the page came from a set of pages rather than a scan of the whole site. |
| items[].page.site_id | integer | Our id for the scanned site. |
| items[].page.brand_link_page | string | For reports that look for your brand anywhere on the site, the page where your link was found. Null otherwise. |
| items[].partner.affiliate_id | string | The affiliate ID found with the item, without the parameter name. Null when none was found. |
| items[].partner.company | string | The partner company for that affiliate ID, where you have recorded one. Null otherwise. |
| items[].brand_affected | string | Your brand the issue concerns. |
| items[].brands_on_page[] | array | Brands found on the page. |
| items[].scanned_at | date | When the page was scanned. |
| items[].reported_at | date | When the issue was first reported. |
| items[].first_scan | date | When we first scanned the site. |
| items[].action | object | Null when the item is unresolved. |
| items[].action.type | string | flagged, non_issue or ignored. |
| items[].action.scope | string | site (the whole site) or page (this page only). Null when the action does not say. |
| items[].action.temporary | boolean | True for a temporary ignore. |
| items[].action.label | string | The action in plain English, as the workbench describes it. |
| items[].action.origin | string | this_cycle, or carried_forward when the action was made in an earlier month and still applies. |
| items[].action.carried_from | object | For carried_forward: table, month (YYYY-MM) and row_id of the item it was made on. Null otherwise. |
| items[].action.actioned_at | datetime | When the action was taken. |
| items[].action.actioned_at_estimated | boolean | True when we could not find the exact time and actioned_at is the report date or the start of the month instead. |
| items[].action.actioned_by | string | The name of the person who took it. Null when we cannot tell. |
| items[].case_id | string | The open case management case holding the item. Null when there is none. |
| items[].findings[] | array | detail=full. The sentences on the page the workbench shows for this item. |
| items[].findings[].text | string | The sentence as found on the page. |
| items[].findings[].translated_text | string | An English translation, where the page is in another language. |
| items[].findings[].full_sentence | string | The longer passage around it, where we recorded one. |
| items[].findings[].matched_phrase | string | The phrase the report looks for. |
| items[].findings[].exact_phrase | string | The wording actually found. |
| items[].findings[].relevance | string | How close your brand is to the sentence: Very High, High, Medium or Low. |
| items[].findings[].relevance_reason | string | Why, in plain English. |
| items[].findings[].brand_affected | string | Your brand this sentence concerns. |
| items[].findings[].brand_before | string | The nearest brand before the sentence. |
| items[].findings[].brand_after | string | The nearest brand after the sentence. |
| items[].findings[].item_hash | string | Identifies the same sentence and brand wherever it appears. |
| items[].findings[].verify_url | string | The page with the sentence highlighted, in browsers that support it. |
| items[].findings[].ai_analysis | mixed | Our AI reading of the sentence, where the report has it switched on and we hold one. Null otherwise. |
| items[].finding_count | integer | detail=simple. How many sentences the item has. |
| items[].result | string | detail=simple. The short issue text stored with the item. |
| items[].screenshot_url | string | Opens our screenshot of the page after you sign in to Rightlander. |
Paging is by position, so items added or actioned between calls cannot make you skip or repeat one.
| Field | Type | Description |
|---|---|---|
| paging.limit | integer | Items per page. |
| paging.returned | integer | Items on this page. |
| paging.next_cursor | string | Pass it back as cursor for the next page. Null when you have everything. |
| paging.complete | boolean | True on the last page. |
Plain-English notes on what was returned.
| Field | Type | Description |
|---|---|---|
| notes[] | array | Notes about this response. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. An action taken in the workbench appears on the next call. |
| Coverage | Items from your active compliance reports that the Compliance Workbench shows. Items from culled affiliates are left out, as in the workbench. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The compliance items reported in one market in one month, with the latest action on each. Reports you have since switched off are included.
For history and reporting or to capture the final state of a month as it leaves the scan cycle.
| Name | In | Default | Description |
|---|---|---|---|
| iso required string | path | - | Two-letter market, or XX for worldwide. |
| month required string | path | - | YYYYMM or YYYY-MM. GET /v1/compliance/markets lists the months that exist. |
| source string | query | - | discovery is our scanning across the market as a whole and requested is the scanning set up for your account alone. Omit for both. One of: discovery, requested |
| status string | query | all | Which items. resolved is any action. Omit for all of them. One of: all, unresolved, resolved, flagged, non_issue, ignored |
| report_id integer | query | - | One of your reports, from GET /v1/compliance/markets. |
| report_priority integer | query | - | Reports of one priority: 1 high, 2 medium, 3 low. One of: 1, 2, 3 |
| domain string | query | - | One partner domain. |
| affid string | query | - | One affiliate ID. The prefixed forms the scanner records (btag=, affid= and so on) are matched too. |
| brand string | query | - | One or more of your brand names, comma separated. |
| state string | query | - | With iso=XX only: a two-letter state or country code the item was scanned in. |
| since string | query | - | YYYY-MM-DD. Items reported, scanned or actioned on or after this date. |
| detail string | query | full | simple leaves out findings and returns finding_count and the short issue text in result. One of: full, simple |
| limit integer | query | 100 | Items per page, up to 500. |
| cursor string | query | - | Pass back next_cursor from the previous response. Null next_cursor means you have seen everything. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
What was run as resolved rather than echoed, with where you stand against the compliance limit.
| Field | Type | Description |
|---|---|---|
| request.endpoint | string | Always compliance_items. |
| request.iso | string | The market read. |
| request.period | string | cycle, or the month read as YYYY-MM. |
| request.source | string | discovery, requested or all. |
| request.status | string | The status filter applied. |
| request.detail | string | full or simple. |
| request.limit | integer | Items per page. |
| request.filters | object | The other filters applied, by name. |
| request.adjusted[] | array | Anything we changed about the request, such as a limit brought down to the maximum. |
| request.compliance_limit.calls_per_day | integer | Compliance calls your account is allowed a day, shared by the three compliance endpoints. |
| request.compliance_limit.used_today | integer | Compliance calls made today, including this one. |
| request.compliance_limit.remaining | integer | What is left today. |
| request.compliance_limit.resets_at | datetime | When it resets. 00:00 UTC. |
The tables read.
| Field | Type | Description |
|---|---|---|
| period.type | string | cycle or month. |
| period.tables[] | array | Cycle only. The two month tables, newest first, such as GB202611. |
| period.from | date | Cycle only. The first day of the cycle. |
| period.to | date | Cycle only. The last day of the current month. |
| period.rolls_over_at | datetime | Cycle only. When the cycle moves on. |
| period.table | string | Month only. The table read, such as GB202610. |
| period.month | string | Month only. YYYY-MM. |
| period.in_current_cycle | boolean | Month only. True while the month is in the scan cycle and its actions can still change. |
Each source read, so a source we could not reach is never mistaken for one with nothing in it.
| Field | Type | Description |
|---|---|---|
| sources[].source | string | discovery or requested. |
| sources[].status | string | ok, partial or unavailable. |
| sources[].items | integer | Items from this source on this page. |
| sources[].reports | integer | Your reports this source holds for the market and period. |
| sources[].note | string | Present when status is not ok. |
Totals for the whole read, on the first page only. Null on later pages.
| Field | Type | Description |
|---|---|---|
| summary.items | integer | Items across all pages. |
| summary.unresolved | integer | Items with no action yet. |
| summary.flagged | integer | Items flagged for action. |
| summary.non_issue | integer | Items marked as a non-issue. |
| summary.ignored | integer | Items ignored. |
| summary.by_report_priority | object | The same four counts for high, medium and low priority reports. |
| summary.domains | integer | Distinct partner domains among the items. |
One entry per workbench item: an issue found on one page by one report.
| Field | Type | Description |
|---|---|---|
| items[].id | string | The item id, such as discovery:GB202611-4821. Also what the screenshot link takes. |
| items[].issue_key | string | The same for the same issue on the same page in any month, so you can follow it when id changes. |
| items[].source | string | discovery (our scanning across the market) or requested (scanning set up for your account). |
| items[].table | string | The month table the item is from, such as GB202611. |
| items[].row_id | integer | The row within that table. |
| items[].also_reported_in[] | array | Cycle only. The same issue in the older month of the cycle, by item id. |
| items[].iso | string | The market. |
| items[].state_iso | string | Where it differs from iso, the state or country the item was scanned in, such as NJ. Null otherwise. |
| items[].status | string | unresolved, flagged, non_issue or ignored. |
| items[].report.id | integer | The report that found it. |
| items[].report.title | string | Its title. |
| items[].report.priority | integer | 1 high, 2 medium, 3 low. |
| items[].report.priority_label | string | High, Medium or Low. |
| items[].page.url | string | The page. For a social post, the post itself. |
| items[].page.domain | string | The partner domain. |
| items[].page.title | string | The page title, where we recorded one. |
| items[].page.type | string | web, social, telegram or email. |
| items[].page.page_scan | boolean | True when the page came from a set of pages rather than a scan of the whole site. |
| items[].page.site_id | integer | Our id for the scanned site. |
| items[].page.brand_link_page | string | For reports that look for your brand anywhere on the site, the page where your link was found. Null otherwise. |
| items[].partner.affiliate_id | string | The affiliate ID found with the item, without the parameter name. Null when none was found. |
| items[].partner.company | string | The partner company for that affiliate ID, where you have recorded one. Null otherwise. |
| items[].brand_affected | string | Your brand the issue concerns. |
| items[].brands_on_page[] | array | Brands found on the page. |
| items[].scanned_at | date | When the page was scanned. |
| items[].reported_at | date | When the issue was first reported. |
| items[].first_scan | date | When we first scanned the site. |
| items[].action | object | Null when the item is unresolved. |
| items[].action.type | string | flagged, non_issue or ignored. |
| items[].action.scope | string | site (the whole site) or page (this page only). Null when the action does not say. |
| items[].action.temporary | boolean | True for a temporary ignore. |
| items[].action.label | string | The action in plain English, as the workbench describes it. |
| items[].action.origin | string | this_cycle, or carried_forward when the action was made in an earlier month and still applies. |
| items[].action.carried_from | object | For carried_forward: table, month (YYYY-MM) and row_id of the item it was made on. Null otherwise. |
| items[].action.actioned_at | datetime | When the action was taken. |
| items[].action.actioned_at_estimated | boolean | True when we could not find the exact time and actioned_at is the report date or the start of the month instead. |
| items[].action.actioned_by | string | The name of the person who took it. Null when we cannot tell. |
| items[].case_id | string | The open case management case holding the item. Null when there is none. |
| items[].findings[] | array | detail=full. The sentences on the page the workbench shows for this item. |
| items[].findings[].text | string | The sentence as found on the page. |
| items[].findings[].translated_text | string | An English translation, where the page is in another language. |
| items[].findings[].full_sentence | string | The longer passage around it, where we recorded one. |
| items[].findings[].matched_phrase | string | The phrase the report looks for. |
| items[].findings[].exact_phrase | string | The wording actually found. |
| items[].findings[].relevance | string | How close your brand is to the sentence: Very High, High, Medium or Low. |
| items[].findings[].relevance_reason | string | Why, in plain English. |
| items[].findings[].brand_affected | string | Your brand this sentence concerns. |
| items[].findings[].brand_before | string | The nearest brand before the sentence. |
| items[].findings[].brand_after | string | The nearest brand after the sentence. |
| items[].findings[].item_hash | string | Identifies the same sentence and brand wherever it appears. |
| items[].findings[].verify_url | string | The page with the sentence highlighted, in browsers that support it. |
| items[].findings[].ai_analysis | mixed | Our AI reading of the sentence, where the report has it switched on and we hold one. Null otherwise. |
| items[].finding_count | integer | detail=simple. How many sentences the item has. |
| items[].result | string | detail=simple. The short issue text stored with the item. |
| items[].screenshot_url | string | Opens our screenshot of the page after you sign in to Rightlander. |
Paging is by position, so items added or actioned between calls cannot make you skip or repeat one.
| Field | Type | Description |
|---|---|---|
| paging.limit | integer | Items per page. |
| paging.returned | integer | Items on this page. |
| paging.next_cursor | string | Pass it back as cursor for the next page. Null when you have everything. |
| paging.complete | boolean | True on the last page. |
Plain-English notes on what was returned.
| Field | Type | Description |
|---|---|---|
| notes[] | array | Notes about this response. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. A month in the current scan cycle can still change. |
| Coverage | Items from your compliance reports, active or switched off, that the Compliance Workbench would show. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Records the domains you send against your account, or with client_ref against one of your clients, and queues each new one for scanning: under your own account, or under the client's once it has signed up for a personalised feed. Every domain comes back with what was done with it.
Once a day, with each list in full and mode=replace, so ours always matches yours. Use mode=add for a few new domains in between, and mode=remove to take some off.
| Name | In | Default | Description |
|---|---|---|---|
| domains required string | body | - | Up to 1000 per request. In a JSON body, an array of strings or of objects { "domain", "affiliate_id", "iso" }. As a form field, domains separated by commas, spaces or new lines, each optionally as domain|affiliate_id or domain|affiliate_id|iso. A full URL is fine; it is reduced to its domain. |
| iso string | body | - | Two-letter market for any domain that does not carry its own. Needed unless every entry has one. |
| client_ref string | body | - | Your ID for the client these domains belong to. Omit to send your own network list. A client_ref you have not used before is created. |
| uid string | body | - | Networks that personalise per user: the user of client_ref these domains belong to. The list is that user's, and its size sets the user's suggested scan credits. Refused if your feeds are personalised per client. |
| mode string | body | add | add keeps everything already on the list. replace removes anything not in this request. remove takes the domains named off the list. One of: add, replace, remove |
| client_name string | body | - | Optional. The client's name, kept on its record. |
| client_domain string | body | - | Optional. The client's own brand site, which its partner list is filed under. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
What the send cost.
| Field | Type | Description |
|---|---|---|
| credits.charged | integer | Credits this send used: 1, however many domains it held. 0 on a trial key. |
| credits.price | integer | The price of a send. |
What was run.
| Field | Type | Description |
|---|---|---|
| request.client_ref | string | The client_ref sent, or null for your own list. |
| request.mode | string | add, replace or remove. |
| request.iso | string | The default market sent, or null. |
The client record, under client_ref. Null for your own list.
| Field | Type | Description |
|---|---|---|
| client.client_ref | string | Your ID for the client. |
| client.status | string | pending, active or cancelled. |
| client.personalised | boolean | True when the client has signed up and its domains are scanned under its own account. |
| client.account | string | The client's account code when personalised. Null otherwise. |
| client.name | string | As you sent it. Null when never sent. |
| client.brand_domain | string | As you sent it. Null when never sent. |
| client.linked_at | datetime | When the client's account was linked. Null until then. |
The account the domains are scanned under: yours, the client's, or null while the client has not signed up.
| Field | Type | Description |
|---|---|---|
| scanned_under | string | An account code, or null. |
Counts for this post.
| Field | Type | Description |
|---|---|---|
| summary.received | integer | Entries in the request. |
| summary.accepted | integer | Distinct domains that could be used. |
| summary.rejected | integer | Entries that could not - see rejected. |
| summary.duplicates | integer | Repeats of a domain already in the request. The last one wins. |
| summary.added | integer | New to the list. |
| summary.updated | integer | Already on it, with a new affiliate ID or market. |
| summary.unchanged | integer | Already on it, as sent. |
| summary.restored | integer | Previously removed, now back. |
| summary.removed | integer | Taken off the list by this post. |
| summary.not_held | integer | mode=remove only: named, but not on the list. |
| summary.queued | integer | Put into the scanning intake. |
| summary.held | integer | Already on the account; nothing to queue. |
| summary.over_allowance | integer | Past the account's partner-site allowance. Recorded; queued by a later post once it is raised. |
| summary.no_profile | integer | In a market where the client has no product profile yet. Recorded; scanned as soon as the client adds a product profile for that market. |
| summary.waiting | integer | Recorded, waiting for the client to sign up. |
| summary.failed | integer | Could not be queued just now. Post again to retry. |
The scanning account's partner-site allowance after this post. Null while there is no account to scan under.
| Field | Type | Description |
|---|---|---|
| allowance.limit | integer | Partner sites the account may hold. |
| allowance.used | integer | Held now. |
| allowance.pending | integer | Queued and not yet added. |
| allowance.remaining | integer | Room left. |
One row per accepted domain, in the order of the request.
| Field | Type | Description |
|---|---|---|
| domains[].domain | string | The domain as we hold it - the registrable domain, lower case. |
| domains[].input | string | What you sent. |
| domains[].affiliate_id | string | The affiliate ID held for it, or null. |
| domains[].iso | string | Its market. |
| domains[].result | string | added, updated, unchanged, restored, removed or not_held. |
| domains[].scan | string | queued, held, over_allowance, waiting, failed, no_profile (the client has no product profile in that market yet; scanned once it adds one) or not_scanned. |
Domains this post took off the list.
| Field | Type | Description |
|---|---|---|
| removed[] | array | Every domain removed, by mode=remove or by a replace. |
| removed_by_replace[] | array | Those removed because a replace left them out. |
Entries that could not be used, and why.
| Field | Type | Description |
|---|---|---|
| rejected[].input | string | What you sent. |
| rejected[].reason | string | Why it was not used. |
Plain-English notes - why nothing was scanned for a client, what over_allowance means.
| Field | Type | Description |
|---|---|---|
| notes[] | array | Short sentences. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Queued domains follow the account's normal scan schedule; first results usually arrive within days. Domains already held keep the schedule they have. |
| Coverage | Domains past the account's partner-site allowance are recorded and reported as over_allowance, and are queued by the next post once the allowance is raised. A client that has not signed up yet has its domains recorded as waiting and queued the moment it does. |
| Permission | A key needs the domains permission. |
| Cost | 1 credits per accepted request. Refunded in full if we cannot start the work. |
This endpoint can return any of the shared errors described under Errors. Because it costs credits it can also return 402 insufficient_credits.
Your network list, or with client_ref one client's, as we hold it: affiliate ID, market, whether it is active or removed, and its scan state.
To reconcile your records with ours, or to see which domains are still waiting for a client to sign up.
| Name | In | Default | Description |
|---|---|---|---|
| client_ref string | query | - | Your ID for the client. Omit for your own network list. |
| uid string | query | - | One user of client_ref (networks that personalise per user). |
| status string | query | active | Which domains to list. One of: active, removed, all |
| limit integer | query | 500 | Rows per page, up to 5000. |
| cursor string | query | - | Pass back next_cursor from the previous response. Null next_cursor means you have seen everything. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
As on POST. Null for your own list.
| Field | Type | Description |
|---|---|---|
| client.status | string | pending, active or cancelled. |
| client.personalised | boolean | True when the client's domains are scanned under its own account. |
Counts for the whole list, whatever page this is.
| Field | Type | Description |
|---|---|---|
| summary.active | integer | Active domains. |
| summary.removed | integer | Removed domains. |
| summary.by_scan | object | Active domains per scan state. |
| summary.returned | integer | Rows on this page. |
Alphabetical by domain.
| Field | Type | Description |
|---|---|---|
| domains[].domain | string | The domain. |
| domains[].affiliate_id | string | Your affiliate ID for it, or null. |
| domains[].iso | string | Its market. |
| domains[].status | string | active or removed. |
| domains[].scan | string | queued, held, over_allowance, waiting, failed, no_profile (the client has no product profile in that market yet; scanned once it adds one) or not_scanned. |
| domains[].added_at | datetime | First sent. |
| domains[].last_posted_at | datetime | Last sent. |
| domains[].removed_at | datetime | When removed. Null while active. |
Paging.
| Field | Type | Description |
|---|---|---|
| next_cursor | string | Pass back as cursor. Null when there is nothing more. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. |
| Coverage | Only what your account has sent. Domains the client added to its own account by other means are not on this list. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Every client_ref your account has used, with its status - pending, requested, approved, declined, active or cancelled - its usage estimate and allocation, and its partner domain counts.
In your daily job: send your client list with client_refs (up to 100 per call), save each client's status and personalise_url for the day, then call the activity feed with client_ref for each client with personalised true. Your feed page then needs no call.
| Name | In | Default | Description |
|---|---|---|---|
| status string | query | active | Which clients to list. The default is the ones with a personalised feed; requested is the ones waiting for your decision. One of: active, requested, approved, declined, pending, cancelled, all |
| client_ref string | query | - | One client only, whatever its status, with its users. A client_ref we have not seen is recorded as pending. Use it to get the client's personalise_url for its button. |
| client_refs string | query | - | Up to 100 clients in one call, comma separated, returned in the order sent whatever their status. New ones are recorded as pending. Each comes back with its status and, if not personalised, its personalise_url, so your daily job can save every client's button link for the day. Networks that personalise per user can send ref|uid entries. |
| uid string | query | - | With client_ref: one user only, recorded as pending if new, with that user's own personalise_url (networks that personalise per user). |
| limit integer | query | 500 | Rows per page, up to 1000. |
| cursor string | query | - | Pass back next_cursor from the previous response. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
Your network's route.
| Field | Type | Description |
|---|---|---|
| network.code | string | Your own Rightlander account code (your MASTERUSERCODE). |
| network.billing | string | subscription (clients sign up and pay through the Rightlander Subscription System) or network (you bill and approve them). |
Counts for this page.
| Field | Type | Description |
|---|---|---|
| summary.returned | integer | Clients on this page. |
| summary.by_status | object | Clients on this page per status. |
One row per client_ref, in client_ref order.
| Field | Type | Description |
|---|---|---|
| clients[].client_ref | string | Your ID for the client. |
| clients[].status | string | pending (domains sent, no request yet), requested, approved, declined, active or cancelled. |
| clients[].personalised | boolean | True when a client_ref call returns the client's own items. |
| clients[].billing | string | subscription or network - the route the request took. Null before a request. |
| clients[].uid | string | Your ID for the user, for networks that personalise per user. Null for a client as a whole. |
| clients[].account | string | The client's Rightlander account code (its MASTERUSERCODE) when personalised. Null otherwise. Every user of a client shares it. |
| clients[].user_account | string | Per-user networks: the user's own Rightlander login under the client account (its USERCODE) when personalised. Null otherwise. With network.code, client_ref, uid and account, it lets you map your client and user to ours. No code carries any access on its own. |
| clients[].name | string | As you sent it, or null. |
| clients[].brand_domain | string | As you sent it, or null. |
| clients[].contact | object | name, email and company the client gave on its request. Null when none. |
| clients[].estimate | object | partner_domains, markets, social_profiles and health_checks_per_month (scans a month) worked out when the client clicked, and package: the scan credits a month the client chose. Null before a request. |
| clients[].allocation | integer | The scan credits a month you approved (for example 5000). Null until approved. |
| clients[].extra_product_profiles | integer | Extra product profiles on top of those included: what the client chose, then what you approved. 0 for none. |
| clients[].markets | array | The markets (two-letter codes) the client chose when it asked to personalise; it confirms them at setup. Null before a request. |
| clients[].feed_categories | array | The kinds of item the client chose for its personalised feed, within what your feed carries; critical risks are always in. Null means everything your feed carries. Once personalised, GET /v1/activity for this client returns only these. |
| clients[].personalise_url | string | The "Personalise my feed" link for this client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise, so networkModal.js opens it in a modal. Optional prefills may be added to the end, URL-encoded and unsigned: email (shown read-only; free email services other than gmail.com refused unless signed), name, company, brand, domain. Null once the client has a personalised feed. |
| clients[].settings_url | string | The "Edit my feed settings" link for a personalised client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise: it opens the client's settings in the modal, where it can change its products, what its feed shows and its plan, or ask to cancel. Null until the client is personalised. |
| clients[].allocation_pending | object | Fewer credits or extra profiles waiting to take effect: allocation, extra_product_profiles and from (a date, the 1st of a month). Null when there is none. |
| clients[].first_seen_at | datetime | The first time you used this client_ref. |
| clients[].requested_at | datetime | When the client clicked "Personalise my feed". Null before that. |
| clients[].decided_at | datetime | When you approved or declined it. Null otherwise. |
| clients[].decision_note | string | The note you gave with the decision, or null. |
| clients[].linked_at | datetime | When the client's account was linked. Null until then. |
| clients[].cancelled_at | datetime | When the personalised feed was cancelled. Null otherwise. |
| clients[].partner_domains.active | integer | Active domains on the client's list. |
| clients[].partner_domains.removed | integer | Removed domains. |
| clients[].partner_domains.by_scan | object | Active domains per scan state. |
| clients[].partner_domains.last_posted_at | datetime | The last time you sent this client's domains. |
Paging.
| Field | Type | Description |
|---|---|---|
| next_cursor | string | Pass back as cursor. Null when there is nothing more. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. A client appears as active as soon as its sign-up is linked. |
| Coverage | Only client_refs your own account has used. Two networks can use the same ID for different companies; each sees only its own. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Your decision on a client's request for a personalised feed, if you bill your own clients, a change to its monthly scan credits or extra product profiles, or the end of a client's feed. Approving returns the setup link the client finishes setup at.
When a client.requested webhook arrives, or a client appears in GET /v1/clients?status=requested, and you have agreed terms with that client. Cancel when a client stops paying you.
| Name | In | Default | Description |
|---|---|---|---|
| action required string | body | - | approve and decline need a requested client and a network that bills its own clients. change needs an approved or active client and a network that bills its own clients: more credits or profiles apply now, fewer from the 1st of next month. cancel works on a requested, approved or active client. One of: approve, decline, cancel, change |
| client_ref required string | body | - | Your ID for the client. |
| uid string | body | - | One user of the client: the action is on that user's subscription (networks that personalise per user). |
| allocation integer | body | - | Scan credits a month: a multiple of 1000, from 1000 to 500000. approve: omit to use what the client chose, or its estimate rounded up to the next 1,000. change: the new amount; omit to change only extra_product_profiles. |
| extra_product_profiles integer | body | - | Extra product profiles on top of those included, 0 to 50. approve: omit to use what the client chose. change: the new number; omit to keep it. |
| note string | body | - | Optional. Kept with the decision and sent in the webhook. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
The client after the action, in the same shape as one row of GET /v1/clients without the domain counts.
| Field | Type | Description |
|---|---|---|
| client.status | string | approved, declined, active or cancelled. |
| client.allocation | integer | Scan credits a month, after an approval or a change that applies now. |
| client.extra_product_profiles | integer | Extra product profiles, after an approval or a change that applies now. |
| client.allocation_pending | object | change only: fewer credits or profiles and the date they take effect. Null otherwise. |
change only.
| Field | Type | Description |
|---|---|---|
| effective_from | date | When the change applies: today for more credits or profiles, the 1st of next month for fewer. Null for other actions. |
approve only.
| Field | Type | Description |
|---|---|---|
| setup_url | string | Where the client finishes setup. Send it to the client. Null for decline and cancel. |
What to do next.
| Field | Type | Description |
|---|---|---|
| notes[] | array | Short sentences. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Immediate. The webhook for the decision is sent before the response. |
| Coverage | Only client_refs your own account has used. |
| Permission | A key needs the clients permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Your billing route (subscription or network), the package your clients get, your prices per scan credit and per extra product profile, your webhook URL and branding, and what you need to build the "Personalise my feed" button: the request link and your signing secret.
Once, when you build the button, and again after rotating your secret.
None.
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
How your network is set up.
| Field | Type | Description |
|---|---|---|
| network.account | string | Your account code. |
| network.display_name | string | Your name as your clients see it, or null. Set by Rightlander. |
| network.billing | string | subscription or network. Set by Rightlander. |
| network.package | object | markets, partner_domains, health_checks (your own scan credits a month), product_profiles (included per client, per market) and calls_day (the API calls you can make a day: 1,000 unless agreed otherwise) - your package with us. Null until agreed. |
| network.client_packages | array | Suggested amounts of scan credits a month. Any multiple of 1,000 up to 500,000 is allowed. |
| network.pricing | object | What Rightlander bills you, if you bill your own clients: currency, credit_unit (1000), credit_price (per scan credit, a decimal string), per_1000, extra_profile_price (a month), profiles_included and max_extra_profiles. You set your own price to your clients. |
| network.webhook_url | string | Where we post client events, or null. |
| network.branding.logo_url | string | Shown to your clients on our pages, or null. |
| network.branding.brand_colour | string | Header and button colour on our pages, or null. |
| network.branding.item_branding | string | network or neutral - how the page behind each item link looks. |
| network.item_links.valid_for_days | integer | How long an item link works after the feed last returned the item. |
| network.feed_style | object | The look of GET /v1/activity?render=html - see feed_style on POST /v1/network. |
| network.feed_categories | array | The categories your feed carries - see feed_categories on POST /v1/network. |
| network.personalise.level | string | client or user: whether your feeds are personalised per client or per user (send uid). Set by Rightlander. |
| network.show_username | boolean | Whether your clients choose and see a Rightlander username at setup. |
| network.examples.verticals[] | array | The verticals our generic product profiles on your account cover. |
| network.examples.categories[] | array | The categories that are examples in your feed. |
| network.examples.per_category_per_day | integer | The most example items per category per day. |
| network.examples.note | string | The label example items carry. |
What you need to build the "Personalise my feed" button.
| Field | Type | Description |
|---|---|---|
| request_link.base | string | The page the button opens. |
| request_link.signing_secret | string | Signs the button link and our webhooks. Keep it on your server. |
| request_link.valid_for_hours | integer | How long a signed link works after its ts. |
| request_link.signed_params[] | array | The parameters the signature covers. |
| request_link.how_to_sign | string | The signing rule in words. |
| request_link.example | string | A link with your account code filled in. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. |
| Coverage | Your own network only. |
| Permission | A key needs the clients permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Set the URL we post client events to, the logo and colour your clients see on the pages they reach from your site, or replace your signing secret. Your display name is set by Rightlander.
When you first set up, and whenever your webhook endpoint or branding changes.
| Name | In | Default | Description |
|---|---|---|---|
| webhook_url string | body | - | https only. Send an empty value to stop webhooks. |
| logo_url string | body | - | An https image URL, shown at the top of our pages for your clients. |
| brand_colour string | body | - | A hex colour like #1A4B8C for the header and buttons. |
| feed_style object | body | - | The look of GET /v1/activity?render=html. Any of: layout (cards, list), theme (light, dark), density (comfortable, compact), category_colours (ours, accent), accent (hex), radius (0 to 16), font (inherit, system), show_partner, show_markets, show_date, show_audience, show_evidence (true or false), button_text. Items always open in a new window. Only the settings you send change. |
| feed_categories array | body | - | What GET /v1/activity carries: any of risk_domain, risk_social, ppc, offers, anomalies, growth, llm, social_brand, social_comp, social_topic, as an array or a comma list. risk_domain and risk_social are always kept. Also set in the Network feed step of the guided setup. |
| show_username string | body | 0 | 1 lets your clients choose and see a Rightlander username at setup. 0 (the default): they only choose a password and are never shown one. One of: 0, 1 |
| item_branding string | body | network | How the page behind each item's link looks: network shows your name, logo and colour; neutral shows no name or logo. One of: network, neutral |
| rotate_secret string | body | - | 1 replaces your signing secret at once. Links signed with the old one stop working. One of: 1 |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
How your network is set up.
| Field | Type | Description |
|---|---|---|
| network.account | string | Your account code. |
| network.display_name | string | Your name as your clients see it, or null. Set by Rightlander. |
| network.billing | string | subscription or network. Set by Rightlander. |
| network.package | object | markets, partner_domains, health_checks (your own scan credits a month), product_profiles (included per client, per market) and calls_day (the API calls you can make a day: 1,000 unless agreed otherwise) - your package with us. Null until agreed. |
| network.client_packages | array | Suggested amounts of scan credits a month. Any multiple of 1,000 up to 500,000 is allowed. |
| network.pricing | object | What Rightlander bills you, if you bill your own clients: currency, credit_unit (1000), credit_price (per scan credit, a decimal string), per_1000, extra_profile_price (a month), profiles_included and max_extra_profiles. You set your own price to your clients. |
| network.webhook_url | string | Where we post client events, or null. |
| network.branding.logo_url | string | Shown to your clients on our pages, or null. |
| network.branding.brand_colour | string | Header and button colour on our pages, or null. |
| network.branding.item_branding | string | network or neutral - how the page behind each item link looks. |
| network.item_links.valid_for_days | integer | How long an item link works after the feed last returned the item. |
| network.feed_style | object | The look of GET /v1/activity?render=html - see feed_style on POST /v1/network. |
| network.feed_categories | array | The categories your feed carries - see feed_categories on POST /v1/network. |
| network.personalise.level | string | client or user: whether your feeds are personalised per client or per user (send uid). Set by Rightlander. |
| network.show_username | boolean | Whether your clients choose and see a Rightlander username at setup. |
| network.examples.verticals[] | array | The verticals our generic product profiles on your account cover. |
| network.examples.categories[] | array | The categories that are examples in your feed. |
| network.examples.per_category_per_day | integer | The most example items per category per day. |
| network.examples.note | string | The label example items carry. |
What you need to build the "Personalise my feed" button.
| Field | Type | Description |
|---|---|---|
| request_link.base | string | The page the button opens. |
| request_link.signing_secret | string | Signs the button link and our webhooks. Keep it on your server. |
| request_link.valid_for_hours | integer | How long a signed link works after its ts. |
| request_link.signed_params[] | array | The parameters the signature covers. |
| request_link.how_to_sign | string | The signing rule in words. |
| request_link.example | string | A link with your account code filled in. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Immediate. |
| Coverage | Your own network only. |
| Permission | A key needs the clients permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The full picture behind the Domain Profile screen, as data. Traffic and audience, the partner and how to reach them, connected domains and social profiles, the risk score and the evidence for it, compliance findings, PPC brand bidding, growth target pages, offers and AI influence.
Use this for a single domain you already know about. Use ?sets= to keep the response to what you actually need - the full payload is large.
| Name | In | Default | Description |
|---|---|---|---|
| domain required string | path | - | The domain, without scheme or path. |
| iso string | query | GB | Market to report against. Affects which scan and which compliance findings are used. |
| sets string | query | - | Comma separated. Omit for everything. See Data sets. One of: core, intel, risk, growth, intel,risk |
| pagelimit string | query | 10 | Cap on URL lists inside the response. 0 or all lifts it. Counts alongside the lists are never capped. |
| exclude string | query | - | Turns off blocks that are on by default. One of: posts, bios, posts,bios |
| include string | query | - | raw attaches the underlying scan payloads. Large. One of: raw |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
Who and what the domain is on your account.
| Field | Type | Description |
|---|---|---|
| identity.domain | string | The domain, normalised. |
| identity.iso | string | Market the response is scoped to. |
| identity.site_id | string | Our internal site id. |
| identity.domain_id | string | Our internal domain id. |
| identity.is_disclosed | boolean | Whether the domain has been disclosed to you by the partner. |
| identity.company | string | Company we hold against the domain. |
| identity.affids[] | array | Every affiliate id seen on the domain. |
| identity.subnetworks[] | array | Sub-networks the domain is associated with. |
| identity.is_subnetwork | boolean | Whether the domain itself is a sub-network property. |
| identity.subnetwork_label | string | Readable reason for the sub-network call. |
The scan this response is built from. Date everything else by it.
| Field | Type | Description |
|---|---|---|
| scan.scanned_at | datetime | When the scan ran. |
| scan.updated_at | datetime | When the record last changed. |
| scan.content_status | string | Outcome of the content fetch. |
| scan.pagehash | string | Content hash, for change detection between calls. |
| scan.final_url | string | Where the scan ended up after redirects. |
| scan.final_http_status | integer | HTTP status of that final URL. |
| scan.is_cloaked | boolean | Whether the site served us different content than a normal visitor. |
| scan.primary_role | string | What the site principally is. |
| scan.scan_status_pill | string | The short status the workbench displays. |
| scan.pages_scanned.pages | integer | Pages covered by the current run. Zero is a fact about the domain, not a missing value. |
| scan.pages_scanned.last_scanned | date | Date of that coverage. |
| scan.pages_scanned.isos_counted[] | array | Markets the page count sums across. |
| scan.pages_scanned.iso_scoped | boolean | Whether the count was limited to the requested market. |
The three headline 0-100 scores.
| Field | Type | Description |
|---|---|---|
| scores.risk_score_0_100 | integer | Risk. Higher is worse. See risk_score_evidence for why. |
| scores.quality_score_0_100 | integer | Content quality. Higher is better. |
| scores.ai_content_likelihood_0_100 | integer | How likely the content is machine generated. |
| scores.ai_content_band | string | That likelihood as a band. |
| scores.ai_content_evidence[] | array | What drove the AI content call. |
What the site is about.
| Field | Type | Description |
|---|---|---|
| content_categories.domain_type | string | Kind of site, e.g. review, coupon, news. |
| content_categories.domain_type_subtype | string | Finer classification. |
| content_categories.site_category_label | string | Readable category. |
| content_categories.verticals[] | array | Every sector detected on the site. |
| content_categories.primary_vertical | string | The dominant one. |
| content_categories.client_vertical | string | Your own sector, for comparison. |
| content_categories.profile_categories[] | array | Categories from the site profile. |
| content_categories.page_topic_categories[] | array | Topics across every scored page. Not filtered by the growth rules. |
Audience size and where it comes from. Banded and rounded throughout - raw visit counts are never returned, under our data licensing.
| Field | Type | Description |
|---|---|---|
| traffic.data_month | string | Month the traffic estimate covers. |
| traffic.iso_traffic_tier | string | Traffic band within the requested market. |
| traffic.global_traffic_tier | string | Traffic band worldwide. |
| traffic.global_traffic_approx | number | One significant figure approximation of global visits. |
| traffic.global_traffic_display | string | That approximation as text, e.g. ~10m visits. |
| traffic.top_countries[].iso | string | Market code. |
| traffic.top_countries[].country | string | Market name. |
| traffic.top_countries[].share_pct | mixed | Whole-number share, or the string "<1". Never 0 - a market is listed because it has traffic. |
| traffic.history.first_month | string | Earliest month we hold. |
| traffic.history.last_month | string | Most recent month. |
| traffic.history.pct_variance | string | Change between the two, e.g. -22%. |
Registration facts.
| Field | Type | Description |
|---|---|---|
| domain_reputation.domain_created | date | Registration date. |
| domain_reputation.domain_expires | date | Expiry date. |
| domain_reputation.domain_age_days | integer | Age in days. A very young domain is worth a second look. |
| domain_reputation.expires_in_days | integer | Days until expiry. |
| domain_reputation.registrant | string | Registrant, where the record is public. |
| domain_reputation.registrant_org | string | Registrant organisation. |
Who runs the domain and whether they are already one of yours.
| Field | Type | Description |
|---|---|---|
| partner.name | string | Partner name. |
| partner.name_shared_estate | boolean | True when the name came from the shared table rather than your own data. |
| partner.partner_id | string | Affiliate or partner id. |
| partner.is_client_partner | boolean | Whether this partner is on your programme. |
| partner.partner_status_known | boolean | False means we could not establish the relationship either way. |
| partner.signals[] | array | What established the partner, e.g. curated list, tracking link, affiliate id. |
| partner.priority | string | Any priority you have set against them. |
| partner.is_subnetwork_entity | boolean | Whether the partner is a network rather than a publisher. |
| partner.generic_assessment | boolean | True when nothing tied the domain to your programme, so the read is generic. |
How to reach whoever runs the site.
| Field | Type | Description |
|---|---|---|
| owner_contact.from_site | string | Contact address found on the site itself. |
| owner_contact.best_social_route.platform | string | Platform of the best social route to the owner. |
| owner_contact.best_social_route.handle | string | Handle on that platform. |
| owner_contact.best_social_route.url | string | Profile URL. |
| owner_contact.best_social_route.followers | integer | Audience, so you can judge whether it is worth using. |
| owner_contact.sources[] | array | Where each contact route came from. |
Other domains that appear to belong to the same owner.
| Field | Type | Description |
|---|---|---|
| connected_domains.count | integer | How many were found. |
| connected_domains.resolved_aff_id | string | The affiliate id the group resolved to. |
| connected_domains.resolved_company | string | The company the group resolved to. |
| connected_domains.name_tie_is_foreign | boolean | True when the tie is only a name match, which is weaker evidence. |
| connected_domains.domains[] | array | Each connected domain and why it is connected. |
Social links found on the site. One URL per platform. Twitter and X are merged.
| Field | Type | Description |
|---|---|---|
| social.<platform> | string | Profile URL. Keys include facebook, instagram, twitter, youtube, linkedin, pinterest, tiktok and linktree. |
The connected social accounts, assessed. This is the block most callers come for.
| Field | Type | Description |
|---|---|---|
| social_profiles.available | boolean | False when social assessment is not available on your account. |
| social_profiles.note | string | Why, when available is false. |
| social_profiles.summary.total_assets | integer | Profiles connected to the domain. |
| social_profiles.summary.assessed | integer | Profiles we have scored. |
| social_profiles.summary.requested | integer | Profiles queued but not yet assessed. |
| social_profiles.summary.not_retrievable_or_gated | integer | Profiles we ran and could not read - private, gated or gone. Deliberately separate from requested. |
| social_profiles.summary.unassessed | integer | Profiles never queued. |
| social_profiles.summary.link_only | integer | Links found on the site with no profile behind them yet. |
| social_profiles.summary.assessed_followers | integer | Total audience across assessed profiles. |
| social_profiles.summary.client_context | string | Whether you have a product profile configured. Without one the brand filter cannot run. |
| social_profiles.summary.brand_filter | string | applied, or not applied with the reason. |
| social_profiles.summary.client_sectors.same[] | array | Your sectors. A brand in one of these counts as relevant. |
| social_profiles.summary.client_sectors.adjacent[] | array | Adjacent sectors, also counted. |
| social_profiles.summary.platforms_scannable[] | array | Platforms we can assess in full. |
One entry per connected profile.
| Field | Type | Description |
|---|---|---|
| platform | string | Platform key. |
| platform_label | string | Readable platform name. |
| handle | string | Account handle. |
| url | string | Profile URL. |
| scannable | boolean | Whether we can assess this platform. |
| state | string | assessed, requested, not_retrievable_or_gated, unassessed or link_only. |
| profile_id | string | Our id for the profile. Use it with the refresh endpoint. |
| display_name | string | Account display name. |
| followers | integer | Audience size. |
| posts_total | integer | Posts on the account. |
| language | string | Detected language. |
| location | string | Stated location. |
| scanned_at | datetime | When the profile was last assessed. |
| scan_id | string | Assessment run id. |
| scan_status | string | Outcome of that run. A bad status explains a posting chart that looks out of date. |
| limited_information | boolean | True when every score came back zero or null - a private or gated account, not a clean one. |
| risk_score_0_100 | integer | Risk score for the profile. |
| risk_band | string | That score as a band. |
| quality_score_0_100 | integer | Content quality. |
| audience_fit_score_0_100 | integer | How well the audience fits your market. |
| professionalism_score_0_100 | integer | Presentation and professionalism. |
| posts_assessed | integer | Posts the assessment looked at. |
| engagement | object | Totals and per-post averages. Averages matter: a profile with two posts cannot be ranked against one with fifty on totals. |
| partner_signals | object | Evidence tying the profile to the partner. |
| sector_fit | object | in_sector, adjacent, unrelated, share_pct, matched_verticals and unknown_reason. |
| profile_verticals[] | array | Sectors detected on the profile. |
| brands.detected[] | array | Brands found in recent posts that are relevant to you. |
| brands.relevant_count | integer | How many were kept. |
| brands.filtered_out | integer | How many were seen and dropped as irrelevant. |
| brands.basis | string | What the relevance filter matched on. none means it could not run. |
| brands.own_brand_excluded | integer | Mentions of the publisher's own brand, removed so they do not crowd out the ones that matter. |
| bio.label | string | Bio field name on this platform. Empty means the platform has no readable bio, not that the account has none. |
| bio.text | string | Bio text. |
| bio.links[] | array | Links in the bio. Often the most actionable single field on the row. |
| bio.link_count | integer | How many. |
| assessment.recommendation | string | Our read on the profile. |
| assessment.confidence | string | How confident that read is. |
| assessment.summary | string | One paragraph. |
| assessment.rationale | string | The reasoning behind that recommendation. |
| risk_and_compliance | object | Compliance findings against the profile. |
| profile_overview | object | Header facts about the account. |
| quality_metrics | object | The measures behind the quality score. |
| posts_referenced[] | array | Lookup table of every post cited anywhere on this row: post_id, url, posted_at, engagement, available. Post ids are STRINGS - they exceed what JavaScript can hold as a number. |
Brands a reviewer has logged on the domain. Reviewed evidence, kept apart from what a scan detected.
| Field | Type | Description |
|---|---|---|
| brands_found.count | integer | How many distinct brands. |
| brands_found.brands[] | array | Brand names. Names only, no page counts. |
Where your brand appears across the domain. Pages are keyed on the canonical URL, so campaign variants of one page merge into one entry carrying every signal.
| Field | Type | Description |
|---|---|---|
| exposure.summary.total_pages | integer | Distinct pages with any exposure signal. |
| exposure.summary.linked_pages_count | integer | Pages carrying a link to you. |
| exposure.summary.mention_pages_count | integer | Pages mentioning you without linking. |
| exposure.summary.topic_pages_count | integer | Pages matching your topics. |
| exposure.summary.outbound_link_count | integer | Outbound links counted. |
| exposure.summary.priority_pages_active | integer | Pages you have marked priority. |
| exposure.summary.has_client_mention | boolean | Whether you are mentioned anywhere. |
| exposure.summary.all_visible_brands[] | array | Every brand visible across those pages, yours and others. |
| exposure.pages[].url | string | Canonical page URL. |
| exposure.pages[].display_url | string | The same URL for display. |
| exposure.pages[].page_title | string | Page title. |
| exposure.pages[].has_link | boolean | Carries a link to you. |
| exposure.pages[].has_mention | boolean | Mentions you. |
| exposure.pages[].has_topic_signal | boolean | Matches one of your topics. |
| exposure.pages[].aff_id | string | Affiliate id on the link. |
| exposure.pages[].anchor_text | string | Anchor text used. |
| exposure.pages[].external_link | string | Where the link points. |
| exposure.pages[].brands[] | array | Brands linked from the page. |
| exposure.pages[].visible_brands[] | array | Brands visible on the page. |
| exposure.pages[].added_date | date | When we first saw it. |
| exposure.pages[].is_priority | boolean | Whether it is one of your priority pages. |
How the site makes money.
| Field | Type | Description |
|---|---|---|
| commercial_signals.has_app | boolean | The site advertises an app. |
| commercial_signals.has_browser_extension | boolean | The site advertises a browser extension. |
| commercial_signals.has_coupon_focus | boolean | The site is coupon led. |
| commercial_signals.has_ads | boolean | The site carries display advertising. |
Whether the site is a real commercial proposition. Returns null rather than a number when no foundation signal exists - a score invented from third-party traffic alone would be worse than no score.
| Field | Type | Description |
|---|---|---|
| commercial_viability.score_0_100 | integer | The score, or null. |
| commercial_viability.base_score_0_100 | integer | Before penalties. |
| commercial_viability.band | string | The score as a band. |
| commercial_viability.confidence | string | How much evidence sits behind it. |
| commercial_viability.foundation_signals[] | array | The signals that let a score be produced at all. |
| commercial_viability.foundation_possible | boolean | Whether a score could be produced. |
| commercial_viability.traffic_source_penalty | number | Deduction for low quality traffic sources. |
| commercial_viability.signals[] | array | Everything that moved the score. |
Apps and browser extensions the domain scan found. The flags and the captured store URLs can disagree in both directions, and both readings are reported rather than reconciled.
| Field | Type | Description |
|---|---|---|
| apps_and_extensions.included | boolean | False means we could not look. |
| apps_and_extensions.app_advertised | boolean | The scan flagged an app. |
| apps_and_extensions.extension_advertised | boolean | The scan flagged an extension. |
| apps_and_extensions.item_count | integer | Store URLs captured. |
| apps_and_extensions.items[].kind | string | app or extension. |
| apps_and_extensions.items[].store | string | Which store. |
| apps_and_extensions.items[].url | string | Store listing URL. |
| apps_and_extensions.items[].found_in | string | Where on the site it was found. |
Which markets we have actually scanned this domain in. Read it before assuming a market is clean.
| Field | Type | Description |
|---|---|---|
| scanned_jurisdictions[].iso | string | Market code. |
| scanned_jurisdictions[].country | string | Market name. |
| scanned_jurisdictions[].last_scan | date | Most recent scan in that market. |
| scanned_jurisdictions[].scans | integer | How many runs we have done there. |
Click data, when you have Trackback.
| Field | Type | Description |
|---|---|---|
| trackback.is_trackback_user | boolean | Whether Trackback is on your account. False means the clicks figure is absent, not zero. |
| trackback.clicks | integer | Clicks attributed to the domain, summed across every mapped account. |
The compliance run behind the data.
| Field | Type | Description |
|---|---|---|
| job_log.rundate | date | When the run happened. |
| job_log.status | string | Run status. |
| job_log.googlepages | integer | Pages indexed for the domain. |
| job_log.rows | integer | Rows the run produced. |
Integrity signals from the page itself. Each flag may be accompanied by an _evidence field carrying what was found.
| Field | Type | Description |
|---|---|---|
| compliance.has_affiliate_disclosure | boolean | An affiliate disclosure is present. |
| compliance.has_disclaimer | boolean | A disclaimer is present. |
| compliance.has_privacy_policy | boolean | A privacy policy is present. |
| compliance.has_cookie_banner | boolean | A cookie banner is present. |
| compliance.age_restriction_present | boolean | Age gating is present. |
| compliance.age_restriction_min_age | integer | Minimum age stated. |
| compliance.claims_regulated | boolean | The site claims to be regulated. |
| compliance.regulator_names[] | array | Regulators named. |
| compliance.claims_regulated_evidence | string | The phrase and any licence numbers found. |
| compliance.endorsement_allusions | boolean | The site implies an endorsement. |
| compliance.trustpilot_mentioned | boolean | Trustpilot is referenced. |
| compliance.has_responsible_gambling_message | boolean | A responsible gambling message is present. |
| compliance.has_self_exclusion | boolean | Self-exclusion information is present. |
What the scan found wrong with the site. Every one is a boolean; two carry evidence alongside.
| Field | Type | Description |
|---|---|---|
| risk_flags.unidentified_scripts | boolean | Scripts we could not identify. Not a malware finding on its own. |
| risk_flags.auto_generated_pages | boolean | Pages appear machine generated. |
| risk_flags.thin_or_spun_content | boolean | Content is thin or spun. |
| risk_flags.dead_links_detected | boolean | Dead links found. |
| risk_flags.placeholder_or_demo_content | boolean | Placeholder or template content left in place. |
| risk_flags.low_effort_templating | boolean | Low effort templating. |
| risk_flags.low_effort_templating_evidence | string | What was found. |
| risk_flags.previous_abuse_reports | boolean | Prior abuse reports against the domain. |
| risk_flags.browser_warnings | boolean | Browsers warn on the site. |
| risk_flags.suspicious_popups | boolean | Suspicious popups. |
| risk_flags.adult_content | boolean | Adult content. |
| risk_flags.explicit_sexual_language | boolean | Explicit sexual language. |
| risk_flags.hate_speech | boolean | Hate speech. |
| risk_flags.harassment | boolean | Harassment. |
| risk_flags.illegal_activity_references | boolean | References to illegal activity. |
| risk_flags.violence_or_weapons_references | boolean | Violence or weapons references. |
| risk_flags.excessive_swearing | boolean | Excessive swearing. |
| risk_flags.impersonates_known_brand | boolean | The site impersonates a known brand. |
| risk_flags.impersonated_brand_candidates[] | array | Which brands. |
| risk_flags.unlicensed_gambling_signals | boolean | Signals of unlicensed gambling. |
Why the risk score is what it is, including any override from findings the scan never saw.
| Field | Type | Description |
|---|---|---|
| risk_score_evidence.included | boolean | False when there is no score to explain. |
| risk_score_evidence.risk_score_0_100 | integer | The score being explained. |
| risk_score_evidence.band | string | The band. |
| risk_score_evidence.what_fired[] | array | Every rule that contributed. |
| risk_score_evidence.verdicts[] | array | The judgements behind them. |
| risk_score_evidence.checks_clear[] | array | Checks that passed. Useful for proving what was tested. |
| risk_score_evidence.checks_clear_count | integer | How many passed. |
| risk_score_evidence.flagged | boolean | Whether compliance or brand bidding findings forced an override. |
| risk_score_evidence.flagged_by[] | array | Which of the two. |
| risk_score_evidence.score_held_at_minimum | boolean | True when the score was floored by the override rather than earned by the scan. |
| risk_score_evidence.flag_reasons[] | array | One sentence per trigger. |
| risk_score_evidence.note | string | Anything else worth saying. |
Findings your compliance team has raised against the domain.
| Field | Type | Description |
|---|---|---|
| compliance_reviews.flagged_count | integer | Items currently flagged. |
| compliance_reviews.priority_count | integer | Of those, how many are priority. |
| compliance_reviews.total_count | integer | Items of any state. |
| compliance_reviews.isos_checked[] | array | Markets searched for findings. |
| compliance_reviews.items[] | array | Each finding, with its state, market and evidence. |
Paid search ads bidding on your brand terms.
| Field | Type | Description |
|---|---|---|
| ppc_brand_bidding.included | boolean | False means brand bidding checks are not available on this deployment - not that the domain is clean. |
| ppc_brand_bidding.monitoring_active | boolean | READ THIS BEFORE ad_count. False means we never looked, so zero ads is not an all clear. |
| ppc_brand_bidding.ad_count | integer | Ads found. |
| ppc_brand_bidding.isos_checked[] | array | Markets checked. |
| ppc_brand_bidding.cycle | string | The window the check covers. |
| ppc_brand_bidding.ads[].iso | string | Market the ad ran in. |
| ppc_brand_bidding.ads[].search_terms[] | array | Terms that surfaced it. |
| ppc_brand_bidding.ads[].ad_title | string | Ad headline. |
| ppc_brand_bidding.ads[].ad_text | string | Ad body. |
| ppc_brand_bidding.ads[].display_url | string | URL as shown. |
| ppc_brand_bidding.ads[].landing_url | string | Where it actually goes. |
| ppc_brand_bidding.ads[].advertiser_host | string | Host running the ad. |
| ppc_brand_bidding.ads[].position | integer | Position on the results page. |
| ppc_brand_bidding.ads[].first_seen | date | First seen. |
| ppc_brand_bidding.ads[].last_seen | date | Last seen. |
| ppc_brand_bidding.other_advertisers.seen | boolean | Whether anyone else was bidding. Only populated when our own count is zero. |
| ppc_brand_bidding.other_advertisers.ad_count | integer | How many ads. Count and markets only - never who they were. |
| ppc_brand_bidding.other_advertisers.isos[] | array | Markets they ran in. |
On-demand health scans requested for the domain.
| Field | Type | Description |
|---|---|---|
| healthcheck_requests.this_month_count | integer | Requests this calendar month, against your allowance. |
| healthcheck_requests.latest_request_at | datetime | When the last one was made. |
Pages worth pursuing. Filtered to exactly what the Growth Feed would show, so the API and the screen never disagree.
| Field | Type | Description |
|---|---|---|
| growth_target_pages.summary.page_count | integer | Pages after the growth filters. |
| growth_target_pages.summary.scored_pages_total | integer | Pages scored before filtering. The gap between the two is explained by filtered_out. |
| growth_target_pages.summary.highest_topic_score | number | Best topic score in the filtered set. |
| growth_target_pages.summary.average_topic_score | number | Average across it. |
| growth_target_pages.summary.total_adjusted_aar | number | Adjusted addressable audience reach. |
| growth_target_pages.summary.total_original_aar | number | Before adjustment. |
| growth_target_pages.summary.competitor_count | integer | Competitors present on those pages. |
| growth_target_pages.summary.client_brand_mentions | integer | Times you are mentioned. |
| growth_target_pages.summary.client_brand_links | integer | Times you are linked. |
| growth_target_pages.summary.priority_band_counts | object | Pages in each priority band, priority_1 to priority_4. |
| growth_target_pages.summary.filtered_out | object | How many pages each rule removed, so the drop is reconcilable. |
| growth_target_pages.summary.filter | object | The rules themselves: admin_accepted_only, opportunity_types, scan_window_days, suppression_months, workflow_hidden. |
| growth_target_pages.pages[].url | string | Canonical page URL. |
| growth_target_pages.pages[].opportunity_type | string | new or improve. Pages where you already outrank the competitor are excluded. |
Offer monitoring status for the domain.
| Field | Type | Description |
|---|---|---|
| offers.monitored | boolean | Whether offers are monitored here. |
| offers.page_count | integer | Pages with monitored offers. |
| offers.oldest_scan_at | datetime | Oldest offer scan in the set. |
| offers.is_fresh | boolean | Whether offer data postdates the last domain scan. |
How the domain shows up in AI answers. Ownership is fail-closed: a profile with no verified owner is not returned.
| Field | Type | Description |
|---|---|---|
| ai_influence.available | boolean | False when AI influence is not on your account. |
| ai_influence.cited | boolean | Whether the domain is cited at all. |
| ai_influence.citations | integer | Citations for your product profiles. |
| ai_influence.citations_all_clients | integer | Citations across every profile we track. Context for the number above. |
| ai_influence.cited_urls | integer | Distinct URLs cited for you. |
| ai_influence.cited_urls_all | integer | Distinct URLs cited for anyone. |
| ai_influence.profiles_citing | integer | How many profiles cite the domain. |
| ai_influence.verticals[] | array | Sectors the citations sit in. |
| ai_influence.example_phrases[] | array | Searches that produced a citation. |
| ai_influence.stability | string | Whether the citation pattern is holding. |
| ai_influence.as_of | date | Date the evidence carries. |
| ai_influence.cited_pages[].url | string | A cited page. |
| ai_influence.cited_pages[].citations | integer | Citations for that page, summed across searches. |
| ai_influence.cited_pages[].last_seen | date | Most recent citation. |
| ai_influence.cited_pages[].cited_for[] | array | Up to ten searches it was cited for. |
| ai_influence.cited_pages_total | integer | Cited pages before any page limit. |
| ai_influence.your_profiles[] | array | Your product profiles the citations belong to. |
| ai_influence.ownership_verified | boolean | False means we could not confirm the profiles are yours, so they are withheld. |
How the response was built. Useful when a block is empty and you need to know whether that means clean or unavailable.
| Field | Type | Description |
|---|---|---|
| diagnostics.tables_used[] | array | Data sources that answered. |
| diagnostics.failures[] | array | Blocks that could not be built, and why. |
| diagnostics.cwb_estate | string | Which compliance estate answered. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Domain scans run to your subscription cycle, typically monthly. scan.scanned_at dates the evidence. |
| Coverage | Markets you have scanning configured for. Ask for a market we have not scanned and the response says so rather than returning nothing. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
| Name | In | Default | Description |
|---|---|---|---|
| platform required string | path | - | Platform the profile is on. x is treated as twitter. One of: instagram, tiktok, youtube, pinterest, twitter |
| handle required string | path | - | Account handle. The @ and a full profile URL are both accepted. |
| sets string | query | - | Comma separated. Omit for everything. core is always returned. One of: core, intel, risk, growth, intel,risk |
| iso string | query | - | Market. Decides which product profile the brand relevance filter reads from. |
| exclude string | query | - | Turns off blocks that are on by default. Each costs an extra lookup. One of: posts, bios, posts,bios |
| include string | query | - | raw attaches the underlying assessment payload. Large. One of: raw |
| usercode string | query | - | Only needed where product profiles are keyed per user. Defaults to the account. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
The account itself.
| Field | Type | Description |
|---|---|---|
| profile.platform | string | Platform key. x is normalised to twitter, so one account never looks like two. |
| profile.platform_label | string | Readable platform name. |
| profile.handle | string | Account handle, normalised - you may send it bare, with an @, or as a full profile URL. |
| profile.profile_id | string | Our id for the profile. Null when we hold no assessment. |
| profile.url | string | Profile URL. |
| profile.display_name | string | Display name. |
| profile.followers | integer | Audience size. |
| profile.posts_total | integer | Posts on the account. |
| profile.language | string | Detected language. |
| profile.location | string | Stated location. |
| profile.linked_domain | string | Domain the profile is connected to, where we have established one. |
Whether the data is any good, and when it was gathered. Read this before anything else.
| Field | Type | Description |
|---|---|---|
| status.state | string | assessed or requested. A handle we hold nothing for returns 404 rather than an empty row. |
| status.last_scanned | datetime | When we last assessed it. |
| status.scan_id | integer | Assessment run id. |
| status.scan_status | string | Outcome of that run. A bad status is what explains a posting chart that looks out of date. |
| status.limited_information | boolean | True when every score came back zero or null - a private or gated account, not a clean one. |
| status.refreshable | boolean | Whether a refresh can be requested right now. |
| status.cooldown_until | datetime | When the seven-day cooldown lifts, if one is in force. |
| status.request_status | string | Only when state is requested. Where the queued assessment has got to. |
The next action you are likely to want, with the reason when it is not open to you.
| Field | Type | Description |
|---|---|---|
| refresh.available | boolean | Whether a refresh would be accepted. |
| refresh.endpoint | string | Where to request one. Null on a platform we do not assess. |
| refresh.credits | integer | What it would cost. |
| refresh.reason | string | Why it is unavailable, when it is. |
Whether the account sits in your part of the market.
| Field | Type | Description |
|---|---|---|
| sector_fit.verdict | string | core, adjacent, off or unknown. |
| sector_fit.basis | string | brands or verticals - what the verdict was reached on. |
| sector_fit.in_sector | integer | Brands in your sectors. |
| sector_fit.adjacent | integer | Brands in adjacent sectors. |
| sector_fit.unrelated | integer | Brands in neither. |
| sector_fit.share_pct | number | Share of detected brands that are in or adjacent to your sectors. |
| sector_fit.matched_verticals[] | array | Which of your sectors matched. |
| sector_fit.unknown_reason | string | Why the verdict is unknown. UNKNOWN IS NOT "not relevant" - it means we had nothing to judge on. |
Brands in recent posts, filtered to the ones relevant to you.
| Field | Type | Description |
|---|---|---|
| brands.relevant[].brand | string | Brand name. |
| brands.relevant[].vertical | string | The brand's own sector. This is what relevance is judged on, not the scan's relevance tag. |
| brands.relevant[].entity_type | string | What kind of entity it is. |
| brands.relevant[].client_relevance | string | own_brand, competitor, same_sector, adjacent_sector or unrelated. |
| brands.relevant[].client_relevance_label | string | That tag in plain English. |
| brands.relevant[].mention_count | integer | Posts mentioning it. Most-mentioned first. |
| brands.relevant[].commercial_post_count | integer | Of those, how many were commercial. |
| brands.relevant[].post_ids[] | array | Post ids, as STRINGS. Resolve them against posts_referenced. |
| brands.relevant_count | integer | How many brands were kept. |
| brands.filtered_out | integer | How many were seen and dropped as irrelevant. This is what tells an empty list apart from a profile that mentioned no brands at all. |
| brands.basis | string | verticals, tokens, both, or none. none means the filter could not run, so nothing is claimed relevant. |
| brands.own_brand_excluded | integer | Mentions of the publisher's own brand, removed before filtering so they do not crowd out the ones that matter. |
| brands.client_sectors.same[] | array | Your sectors. Returned because "why is my brand list empty" is otherwise unanswerable from the response. |
| brands.client_sectors.adjacent[] | array | Adjacent sectors, also counted. |
The bio and the links inside it. Often the most actionable field on the whole response - it is where an account states where it sends its audience. Turn it off with exclude=bios.
| Field | Type | Description |
|---|---|---|
| bio.label | string | What the platform calls the field. EMPTY MEANS THE PLATFORM HAS NO READABLE BIO, not that the account has none. |
| bio.links_label | string | links everywhere except TikTok, where they are the other accounts the creator connected - a different claim. |
| bio.text | string | Bio text. |
| bio.links[].url | string | Where it goes. On Twitter this is the expanded URL, not the t.co shortlink. |
| bio.links[].title | string | Link title. |
| bio.links[].type | string | Link type. |
| bio.link_count | integer | How many, after de-duplication on the URL. |
How often the account posts, and how much engagement it gets. Turn it off with exclude=posts.
| Field | Type | Description |
|---|---|---|
| posting_activity.window_days | integer | Days covered. Thirty, unless a brand mention older than that pulled the window back. |
| posting_activity.window_widened_for_brands | boolean | Whether it was widened. |
| posting_activity.window_end | datetime | The end of the window. Dated when it has slid back to the last post we hold. |
| posting_activity.window_is_stale | boolean | True when the window is not recent. |
| posting_activity.posts | integer | Posts in the window. |
| posting_activity.posts_per_week | number | Cadence. |
| posting_activity.engagement_metric | string | What the platform measures - plays, likes and views are not interchangeable. |
| posting_activity.engagement_total | integer | Total across the window. |
| posting_activity.note | string | An empty window is NOT "dormant" - it means we hold nothing recent. window_end is what tells you which. |
| engagement.metric | string | The metric, repeated on the headline block. |
| engagement.total | integer | Total engagement. |
| engagement.average_per_post | integer | Per post. Use this to compare accounts - a profile that posted twice cannot be ranked against one that posted fifty times on totals. |
| engagement.posts_counted | integer | Posts behind the average. |
| engagement | object | NULL rather than zero when we hold no posts: no data and no engagement are different answers. |
What the assessment inferred about the account and its audience.
| Field | Type | Description |
|---|---|---|
| profile_overview.primary_geography | string | Where the audience mostly is. |
| profile_overview.primary_geography_evidence[] | array | What that was inferred from. |
| profile_overview.audience_age_band | string | Inferred audience age. |
| profile_overview.audience_age_confidence | integer | How confident that is. |
| profile_overview.content_tone[] | array | Tone of the content. |
| profile_overview.cta_intensity_0_100 | integer | How hard the account sells. |
| profile_overview.monetisation_intent | string | How the account makes money. |
| profile_overview.monetisation_intent_confidence | integer | How confident that is. |
| profile_overview.primary_language | string | Language of the content. |
| profile_overview.language_quality_0_100 | integer | How well written it is. |
| profile_verticals[] | array | Sectors detected on the profile. |
The four dials, plus the flag that stops a zero being misread.
| Field | Type | Description |
|---|---|---|
| scores.risk_score_0_100 | integer | Risk. Higher is worse. |
| scores.risk_band | string | That score as a band. |
| scores.quality_score_0_100 | integer | Content quality. |
| scores.audience_fit_score_0_100 | integer | Fit with your market. |
| scores.professionalism_score_0_100 | integer | Presentation. |
| scores.posts_assessed | integer | Posts the assessment looked at. |
| scores.limited_information | boolean | READ THIS BEFORE THE SCORES. True means every one came back zero or null, so they describe what we could see rather than the account. |
| partner_signals.score | integer | Partner quality out of 4. Client-INDEPENDENT: it says the account is well run, not that it suits you. sector_fit answers that. |
| partner_signals.matched[] | array | Which signals it scored on. |
What is wrong with the account, with the posts that evidence it.
| Field | Type | Description |
|---|---|---|
| risk_and_compliance.overall_risk_score_0_100 | integer | The assessment's own risk figure. |
| risk_and_compliance.regulated_verticals[] | array | Regulated sectors the account posts in. |
| risk_and_compliance.age_restricted_risk.risk_level | string | Age-restricted content risk. |
| risk_and_compliance.age_restricted_risk.audience_under_25_likely | boolean | Whether the audience skews young. |
| risk_and_compliance.age_restricted_risk.evidence[] | array | What that was based on. |
| risk_and_compliance.age_restricted_risk.post_ids[] | array | Posts involved, as strings. |
| risk_and_compliance.compliance_issues[].risk_type | string | What kind of issue. |
| risk_and_compliance.compliance_issues[].severity_score | integer | How serious. |
| risk_and_compliance.compliance_issues[].why_it_matters | string | Why it matters. |
| risk_and_compliance.compliance_issues[].evidence[] | array | The evidence. |
| risk_and_compliance.compliance_issues[].post_ids[] | array | Posts involved, as strings. |
| risk_and_compliance.compliance_issue_count | integer | How many issues. |
The measures behind the quality score.
| Field | Type | Description |
|---|---|---|
| quality_metrics.overall_quality_0_100 | integer | Overall. |
| quality_metrics.content_consistency_0_100 | integer | How consistent the output is. |
| quality_metrics.brand_coherence_0_100 | integer | How coherent the account is as a brand. |
| quality_metrics.audience_fit_0_100 | integer | Fit between content and audience. |
| quality_metrics.authenticity_0_100 | integer | Authenticity signals. |
| quality_metrics.professionalism_0_100 | integer | Presentation. |
| quality_metrics.conversion_style_0_100 | integer | How the account drives action. |
| quality_metrics.strengths[] | array | What it does well. |
| quality_metrics.weaknesses[] | array | What it does badly. |
| quality_metrics.best_fit_brand_types[] | array | Brands it would suit. |
| quality_metrics.avoid_if_sensitive[] | array | Reasons to steer clear if you are sensitive to them. |
| assessment.recommendation | string | Our read on the account. |
| assessment.confidence | integer | How confident that read is. |
| assessment.summary | string | One paragraph. |
| assessment.rationale[] | array | The reasoning, up to eight points. |
Whether there is a gap here worth approaching them about. Derived from the brand list above rather than by a second classifier, so the two cannot disagree.
| Field | Type | Description |
|---|---|---|
| growth.competitor_brands[].brand | string | A competitor the account already promotes. |
| growth.competitor_brands[].mention_count | integer | How often. |
| growth.your_brand_mentions | integer | Times you appear. |
| growth.opportunity | string | A plain reading of the two counts, e.g. "competitors are present and you are not". Says "not assessed" when the relevance filter could not run. |
| growth.window_days | integer | The window those counts cover. |
A lookup table for every post id cited anywhere above. One entry per post, not repeated per citation.
| Field | Type | Description |
|---|---|---|
| posts_referenced[].post_id | string | The id, ALWAYS A STRING - a TikTok post id is past the point where JavaScript can hold it as a number without rounding. |
| posts_referenced[].url | string | The post. Null when it has aged out of our posts table. |
| posts_referenced[].posted_at | datetime | When it was posted. |
| posts_referenced[].engagement | object | Every engagement column the platform holds, keyed by what it measures. |
| posts_referenced[].available | boolean | False for an id we can no longer resolve. It is still listed - omitting it would make a cited id look like an error. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Social profiles are assessed on a monthly cycle, or whenever a refresh is requested. status.last_scanned dates the evidence, and assessed_for.last_assessed_for_you dates the last one made against your own brands. |
| Coverage | Instagram, TikTok, YouTube and Pinterest are assessed in full. Twitter profiles carry a bio but are not scored. Other platforms are recorded as links only. If we hold no assessment made for you but somebody else has assessed the account, you get that one back marked generic rather than nothing - see the Assessments guide. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
| Name | In | Default | Description |
|---|---|---|---|
| platform required string | path | - | Platform the profile is on. One of: instagram, tiktok, youtube, pinterest |
| handle required string | path | - | Account handle, without the @. |
| callback_url string | body | - | Where to post the result. Defaults to the callback URL on your key. https only. |
| reference string | body | - | Your own reference, echoed back on the job and the callback. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
The queued refresh. Poll it, or wait for the callback.
| Field | Type | Description |
|---|---|---|
| job.job_id | string | Identifier for this refresh. Keep it. |
| job.status | string | queued on acceptance. |
| job.type | string | social_refresh. |
| job.target | string | platform:handle being refreshed. |
| job.reference | string | Your own reference, echoed back. |
| job.requested_at | datetime | When we accepted it. |
| job.estimated_completion | datetime | Our estimate. Usually hours, always within 24. |
| job.poll | string | URL to check status. |
| job.callback_url | string | Where we will post the result, if you registered one. |
What it cost. Charged on acceptance, refunded in full if we cannot start.
| Field | Type | Description |
|---|---|---|
| credits.charged | integer | Credits taken. |
| credits.balance | integer | Balance after the charge. |
The limits a refresh has to pass. These are the same limits as a refresh requested inside the workbench - the API is not a way around them.
| Field | Type | Description |
|---|---|---|
| allowance.used_this_month | integer | Social scans used this month. |
| allowance.allowed_per_month | integer | Your monthly allowance. |
| allowance.cooldown_days | integer | Days that must pass between refreshes of the same profile. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Results are usually available within a few hours and always within 24 hours. |
| Coverage | Refreshes count against the same monthly social health allowance as refreshes requested in the workbench, and against the same seven-day cooldown per profile. |
| Permission | A key needs the refresh permission. |
| Cost | 10 credits per accepted request. Refunded in full if we cannot start the work. |
This endpoint can return any of the shared errors described under Errors. Because it costs credits it can also return 402 insufficient_credits.
Re-runs the search set behind AI influence and rebuilds which domains are cited in AI answers for your product profile. One request runs twelve searches, which is why it costs what it does.
Use it after a material change to your product profile or your competitor set. It is capped at three runs per profile per calendar month.
| Name | In | Default | Description |
|---|---|---|---|
| profile_id required string | body | - | The product profile to rebuild. This is a profile-level operation, not a domain-level one. |
| callback_url string | body | - | Where to post the result. Defaults to the callback URL on your key. |
| reference string | body | - | Your own reference, echoed back. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
The queued rebuild.
| Field | Type | Description |
|---|---|---|
| job.job_id | string | Identifier for this rebuild. |
| job.status | string | queued on acceptance. |
| job.type | string | llm_refresh. |
| job.target | string | profile:<id> being rebuilt. |
| job.reference | string | Your own reference, echoed back. |
| job.requested_at | datetime | When we accepted it. |
| job.searches | integer | Searches the rebuild will run. Twelve, and never fewer - a rebuild replaces the previous snapshot, so a shorter run would lose data. |
| job.poll | string | URL to check status. |
What it cost.
| Field | Type | Description |
|---|---|---|
| credits.charged | integer | Credits taken. |
| credits.balance | integer | Balance after the charge. |
Shared with rebuilds requested inside the workbench.
| Field | Type | Description |
|---|---|---|
| allowance.runs_this_month | integer | Rebuilds already run for this profile this calendar month. |
| allowance.runs_allowed | integer | How many are permitted. Three. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | A rebuild replaces the previous snapshot rather than adding to it. |
| Coverage | Product profiles with AI influence enabled. |
| Permission | A key needs the llm permission. |
| Cost | 1,500 credits per accepted request. Refunded in full if we cannot start the work. |
This endpoint can return any of the shared errors described under Errors. Because it costs credits it can also return 402 insufficient_credits.
Returns the job, its status and, once complete, a link to the refreshed asset. Polling is always available even if you also registered a callback - the callback is a convenience, not the contract.
Poll no more than once a minute. Refreshes take hours, not seconds.
| Name | In | Default | Description |
|---|---|---|---|
| job_id required string | path | - | The job_id returned when you requested the refresh. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
Current state of one refresh.
| Field | Type | Description |
|---|---|---|
| job.job_id | string | The job. |
| job.type | string | social_refresh or llm_refresh. |
| job.status | string | queued, running, complete, failed or rejected. |
| job.target | string | What is being refreshed. |
| job.reference | string | Your reference. |
| job.credits | integer | Credits charged. Zero if refunded. |
| job.requested_at | datetime | When it was accepted. |
| job.started_at | datetime | When work began. |
| job.completed_at | datetime | When it finished. |
| job.message | string | Why it failed, when it did. |
| job.result | string | Path to the refreshed asset, once complete. |
Delivery record, when you registered a callback URL.
| Field | Type | Description |
|---|---|---|
| callback.url | string | Where we posted. |
| callback.status | string | delivered, pending or failed. |
| callback.attempts | integer | Delivery attempts made. |
| callback.last_at | datetime | Most recent attempt. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. |
| Coverage | Jobs are retained for 90 days. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Every refresh you have requested, newest first, with its status and what it cost.
Use it to reconcile credit spend, or to find a job_id you did not keep.
| Name | In | Default | Description |
|---|---|---|---|
| status string | query | - | Restrict to one status. One of: queued, running, complete, failed |
| type string | query | - | Restrict to one kind of job. One of: social_refresh, llm_refresh |
| limit integer | query | 50 | Rows to return, up to 200. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
Your refreshes, newest first. Same fields as a single job.
| Field | Type | Description |
|---|---|---|
| jobs[].job_id | string | The job. |
| jobs[].type | string | social_refresh or llm_refresh. |
| jobs[].status | string | Current state. |
| jobs[].target | string | What was refreshed. |
| jobs[].credits | integer | Credits charged. |
| jobs[].requested_at | datetime | When it was accepted. |
| jobs[].completed_at | datetime | When it finished. |
Totals for the window returned.
| Field | Type | Description |
|---|---|---|
| summary.total | integer | Jobs matching the request. |
| summary.credits_spent | integer | Credits across them, so this reconciles against your statement. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Live. |
| Coverage | Jobs are retained for 90 days. |
| Permission | A key needs the read permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
The counts behind the action cards on your Actions and Objectives board: how many items are waiting against each objective and market, and how many of those are new.
Poll this on a schedule to drive your own alerting, rather than polling the asset endpoints looking for changes.
| Name | In | Default | Description |
|---|---|---|---|
| iso string | query | - | Two-letter market code. Omit for all markets. |
| goal string | query | - | Restrict to one objective. One of: risk, growth, offers, social |
| since string | query | - | ISO date or timestamp. Only count items that arrived after it. |
Every field this endpoint can return, block by block. A block tagged with a data set is only returned when you ask for that set, or when you leave sets off entirely. core blocks come back either way. A name ending in [] describes one member of an array.
One entry per objective and market.
| Field | Type | Description |
|---|---|---|
| alerts[].goal | string | The objective, e.g. risk, growth, offers, social. |
| alerts[].iso | string | Market, or empty for all markets. |
| alerts[].label | string | Readable name of the action. |
| alerts[].total | integer | Items waiting right now. |
| alerts[].since | integer | How many arrived since your ?since= point. Null when there is no baseline yet. |
| alerts[].url | string | Where to act on it in the workbench. |
| alerts[].as_of | datetime | When the count was computed. |
| alerts[].stale | boolean | True when the count was served from cache rather than recomputed. Read as_of alongside it. |
The envelope every endpoint carries, whatever you asked for.
| Field | Type | Description |
|---|---|---|
| ok | boolean | True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing. |
| error | string | Human-readable message. Present only on failure. |
| error_code | string | Stable code to branch on. Match on this, not on the message text. |
| status | integer | HTTP status, repeated in the body for clients that cannot see it. |
| request.queried_at | datetime | When we answered. |
| request.took_ms | integer | How long it took us. |
| request.key_source | string | header or query - where your key was read from. |
| request.rate_limit.requests_per_day | integer | Your daily allowance. |
| request.rate_limit.used_today | integer | Requests used today. |
| request.rate_limit.remaining | integer | What is left. |
| request.rate_limit.resets_at | datetime | When it resets. 00:00 UTC. |
| request.credits_charged | integer | Credits taken by this request. Present only when it cost something. |
| Freshness | Counts are cached briefly and carry an as_of timestamp. |
| Coverage | Objectives configured on your account. |
| Permission | A key needs the alerts permission. |
| Cost | No credits. Counts against your daily request allowance. |
This endpoint can return any of the shared errors described under Errors.
Pick an endpoint on the left to build and send a request.
Select an endpoint to see a code sample.
Not sent yet.
Build a request here to see the exact URL and a ready-to-run code sample. Log in to send it against your own account and see the real response.