Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.
Get a campaign's effective scope
const url = 'https://api.eu1.luigisbox.ai/platform/v1/campaigns/example/effective-scope';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.eu1.luigisbox.ai/platform/v1/campaigns/example/effective-scope \ --header 'Authorization: Bearer <token>'Every catalog, channel, surface and intent the campaign’s targeting resolves to, computed on demand from the tags as they stand now.
Serving resolves the same way, so this is also what the campaign is covering: a tag edit reaches serving within seconds, and only inside that window can the two differ. A dimension left unnarrowed is dispatched as “any” rather than as a list, and so covers whatever is created later with no re-save.
It also carries serving_problems and serving_checked_at, which answer a second question: not where the campaign is meant to apply, but whether it actually reached those catalogs. The two are served together on purpose — “will this campaign work?” needs both, and splitting them would make the common case two requests.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Responses
Section titled “ Responses ”Successful Response
What a campaign’s targeting resolves to right now, fully enumerated.
Explicit picks are unioned with the picked tags’ current members and resolved against the catalogs, channels and surfaces that exist at read time. Serving resolves the same way, so this is also what the campaign is covering: a tag edit reaches serving within seconds, and only inside that window can the two differ.
One case lags longer. A campaign that names no catalogs covers every catalog in its organization, so a newly added one is listed here at once — but the campaign does not serve there until it is next saved.
A dimension with no reference at all widens to its universe — all catalogs of the
organization, all channels and surfaces of those catalogs. An empty list therefore means
the campaign targets nothing in that dimension, with one exception spelled out for
channel_ids below.
intents is derived from surfaces rather than echoing the stored array: a
campaign whose targeted surface was deleted reports no surfaces and no Intents.
A channel referenced explicitly, or through a channel tag, is always listed in
channel_ids. A campaign that narrows by no channel is unrestricted by channel at
request time, whatever channel_ids reports.
object
The catalogs the campaign resolves to. Empty means it resolves to none, so nothing serves it — not that it reaches all of them.
The channels the campaign narrows to, excluding each catalog’s implicit default channel. Empty means it narrows to no channel you created — not that it reaches none, since a campaign unnarrowed by channel is dispatched to every channel of its catalogs.
The distinct Intents of surfaces, sorted — derived at read time, never the stored targeting echoed back. A campaign whose targeted surface has since been deleted reports no surfaces and no Intents.
Targeted catalogs the campaign is not currently serving in, one entry each. A non-empty list means the campaign reads as active while reaching fewer catalogs than its scope shows. Empty means no catalog is known to have failed, which is not the same as confirmed healthy — read it with serving_checked_at: empty with a timestamp is a clean check, empty with null is one that has not run yet. A campaign that is not active reaches nothing and reports none, and a dry run of unsaved targeting has no campaign to check, so both are always empty.
One targeted catalog an active campaign is not currently serving in.
object
The targeted catalog the campaign is not serving in.
Stable machine code for why the campaign does not reach this catalog.
Human-readable explanation of the failure.
The surfaces the campaign resolves to, each with the catalog that owns it. Empty means it narrows to no surface — not that it reaches none, since a campaign unnarrowed by surface is served on every surface of its catalogs whose Intent it targets.
A concrete surface reference: a surface id paired with its catalog.
object
Example
{ "intents": [ "search" ], "serving_problems": [ { "code": "field_type_conflict" } ]}Missing or invalid credentials
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Authenticated but not permitted
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Resource not found
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Request validation failed
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Was this page helpful?
Thanks.