marketing.sources.cancel

Stop a scan

POST/marketing/sources/{id}/cancel

Operation: marketing.sources.cancel
MCP tool: marketing_sources_cancel

Stop whatever scan of this source is queued or running. The source itself stays: if it had already published a manifest it goes back to succeeded with that manifest current, and if it had not it is failed. Answers how many scan attempts were stopped — zero is not an error, it means nothing was running.

curl -X POST "https://api.gogoscreen.com/api/v1/marketing/sources/<id>/cancel" \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

A request to this operation.

At a glance

Fact	Detail
Scopes	`marketing:write`
Credentials	a signed in dashboard session or an API key.
Rate limit	120 requests a minute per credential, in the `write` class.
Idempotency	Required. Send an `Idempotency-Key` header; a retry with the same key and the same body returns the stored answer with `Idempotent-Replayed: true`. How idempotency works.
MCP tool	`marketing_sources_cancel`
Always sets	`Cache-Control: private, no-store`
Verified email	Required. An account whose email address is not verified meets `403 email_unverified` before the operation runs.
Marketing videos	Required. An account without marketing videos enabled meets `403 feature_disabled` before the operation runs.

Path parameters

Name	Type	Required	Description
id	string	Required	The resource `id`, from a create answer or the matching list.format: uuid

Response

Answers 200. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

Stop a scan

200 OK body
Name	Type	Description
cancelled	number
resource	object	any keys

200 OK headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.
`Idempotent-Replayed`	Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
idempotency_key_required	400	A mutating operation arrived over HTTP with no `Idempotency-Key` header. It is refused before the body is parsed, so a caller missing both learns about both at once.	Add an `Idempotency-Key` header of up to 128 characters, unique to this request. Over MCP the same value goes in the `idempotencyKey` tool argument.
site_not_allowed	400	The website is a major public platform (a social network, search engine, marketplace or big portal) or a site about a sensitive topic (adult content, gambling, drugs, weapons, hate or violence). `details.reason` says which: `public_platform` or `sensitive_topic`. A sign-in address on a sensitive-topic site is refused too, and so is a sign-in that lands on a refused site.	Use your own product's website. No time was used. If you think your site was refused by mistake, write to support@gogoscreen.com or open a ticket with "Talk to a person": support can allow a site by name.
source_refresh_url_mismatch	400	A refresh named a different address from the one the source was created with. Allowing it would silently replace a customer's site with another.	Refresh with the original address, or create a new source for the new one.
url_invalid	400	The address is not one this API will fetch, for a reason the more specific codes do not cover.	Send an absolute public http or https URL.
url_malformed	400	The address could not be parsed as a URL.	Send an absolute URL including the scheme.
url_private	400	The address resolves to a private, loopback, link local, carrier grade NAT or IPv4 mapped IPv6 address. This API will not fetch inside a network.	Point at a publicly reachable address. There is no way to opt out of this guard.
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
website_demo_invalid	400	The demo login sent with a scan is not a valid shape.	Send a username, a password and the login page address together, or none of them.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
source_not_found	404	No website source of that id belongs to this account.	Check the id. A source belonging to another account answers the same way.
source_owner_not_found	404	The account a scan is being run for does not exist.	Nothing a caller can change. Quote `requestId` to support.
conflict	409	The request conflicts with the state the resource is in, and no more specific code applies.	Re-read the resource and decide from its current state. Retrying the same request unchanged will not help.
idempotency_conflict	409	That idempotency key has already been used on this operation with a different request body.	Use a fresh key for a different request. A key stands for one intent, not for one attempt.
idempotency_in_progress	409	The first request under that key is still being worked. Two concurrent identical requests both reach the store and one of them is told this.	Wait the `Retry-After` seconds, which is 2, and send exactly the same request again with the same key. Do not change the body and do not mint a new key.
source_export_in_flight	409	A source delete was asked for while an export is still being cut from one of its versions.	Cancel the export, then delete the source.
source_idempotency_conflict	409	That idempotency key was already used on this account with a different scan.	Use a fresh key for a different scan.
source_inspection_busy	409	A scan is already running on this account. One at a time.	Poll the running scan until its state is terminal, or cancel it, then start the new one.
source_inspection_stopping	409	A scan is still shutting down after a cancel.	Wait a moment and try again.
source_owner_unavailable	409	The account cannot start new work, because it is blocked or scheduled for deletion.	Resolve the account's state, then retry.
source_deleted	410	The website source has been deleted. It still reads `state: "cancelled"`.	Scan the site again with `marketing.sources.create`.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.