sift_client.resources.campaigns

CLASS	DESCRIPTION
CampaignsAPIAsync	High-level API for interacting with campaigns.

CampaignsAPIAsync

CampaignsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with campaigns.

A campaign is a named list of reports. Runs join a campaign through the reports they generate, so a run must be created with create_default_report=True to be added.

Initialize the CampaignsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
get	Get a Campaign by ID or client key.
list_	List campaigns.
find	Find one campaign. Takes the same arguments as list_.
create	Create a new campaign, optionally seeded with reports.
get_or_create	Get the campaign with this client key, or create it.
update	Update a Campaign.
add_reports	Add reports to a campaign, keeping the ones already there.
add_runs	Add runs to a campaign through the reports they generated.
archive	Archive a campaign.
unarchive	Unarchive a campaign.
report_summaries	Get per-report rule counts for several campaigns at once.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

get async

get(
    campaign_id: str | None = None,
    *,
    client_key: str | None = None,
    organization_id: str | None = None,
    skip_report_summaries: bool = False,
) -> Campaign

Get a Campaign by ID or client key.

PARAMETER	DESCRIPTION
campaign_id	The ID of the campaign. TYPE: str | None DEFAULT: None
client_key	The client key, as an alternative to the ID. TYPE: str | None DEFAULT: None
organization_id	Required with client_key if you belong to several orgs. TYPE: str | None DEFAULT: None
skip_report_summaries	Omit the per-report counts. Much faster for large campaigns. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Campaign	The Campaign.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    campaign_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_by: Any | str | None = None,
    tags: list[str] | list[Tag] | None = None,
    metadata: dict[str, Any] | None = None,
    reports: list[Report] | list[str] | None = None,
    runs: list[Run] | list[str] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Campaign]

List campaigns.

PARAMETER	DESCRIPTION
name	Exact name of the campaign. TYPE: str | None DEFAULT: None
names	List of campaign names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the campaign. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter campaigns by name. TYPE: str | Pattern | None DEFAULT: None
campaign_ids	Filter to campaigns with any of these IDs. TYPE: list[str] | None DEFAULT: None
client_keys	Filter to campaigns with any of these client keys. TYPE: list[str] | None DEFAULT: None
created_by	Filter campaigns created by this user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter campaigns with any of these Tags or tag names. TYPE: list[str] | list[Tag] | None DEFAULT: None
metadata	Filter campaigns by metadata criteria. TYPE: dict[str, Any] | None DEFAULT: None
reports	Filter campaigns containing any of these Reports or report IDs. TYPE: list[Report] | list[str] | None DEFAULT: None
runs	Filter campaigns containing any of these Runs or run IDs. TYPE: list[Run] | list[str] | None DEFAULT: None
description_contains	Partial description of the campaign. TYPE: str | None DEFAULT: None
include_archived	If True, include archived campaigns in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter campaigns. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of campaigns to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Campaign]	A list of Campaign objects that match the filter criteria.

find async

find(**kwargs) -> Campaign | None

Find one campaign. Takes the same arguments as list_.

Raises if more than one matches.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Campaign | None	The Campaign found or None.

create async

create(
    create: CampaignCreate | dict,
    *,
    reports: list[Report] | list[str] | None = None,
    runs: list[Run] | list[str] | None = None,
    from_campaign: str | Campaign | None = None,
) -> Campaign

Create a new campaign, optionally seeded with reports.

At most one seed may be given. runs lets the server collect the reports those runs generated, so the runs need a default report.

PARAMETER	DESCRIPTION
create	The campaign definition. TYPE: CampaignCreate | dict
reports	Seed with these Reports or report IDs. TYPE: list[Report] | list[str] | None DEFAULT: None
runs	Seed with the reports these Runs generated. TYPE: list[Run] | list[str] | None DEFAULT: None
from_campaign	Duplicate this Campaign or campaign ID. TYPE: str | Campaign | None DEFAULT: None

RETURNS	DESCRIPTION
Campaign	The created Campaign.

get_or_create async

get_or_create(create: CampaignCreate | dict) -> Campaign

Get the campaign with this client key, or create it.

PARAMETER	DESCRIPTION
create	The campaign definition. Its client_key is required. TYPE: CampaignCreate | dict

RETURNS	DESCRIPTION
Campaign	The existing or newly created Campaign.

RAISES	DESCRIPTION
ValueError	If client_key is not set.

update async

update(
    campaign: str | Campaign, update: CampaignUpdate | dict
) -> Campaign

Update a Campaign.

reports, tags, and metadata are replaced, not merged. Prefer add_reports or add_runs to grow the report list.

PARAMETER	DESCRIPTION
campaign	The Campaign or campaign ID to update. TYPE: str | Campaign
update	Updates to apply to the Campaign. TYPE: CampaignUpdate | dict

RETURNS	DESCRIPTION
Campaign	The updated Campaign.

add_reports async

add_reports(
    campaign: str | Campaign,
    reports: list[Report] | list[str],
) -> Campaign

Add reports to a campaign, keeping the ones already there.

PARAMETER	DESCRIPTION
campaign	The Campaign or campaign ID to add to. TYPE: str | Campaign
reports	The Reports or report IDs to add. TYPE: list[Report] | list[str]

RETURNS	DESCRIPTION
Campaign	The updated Campaign.

add_runs async

add_runs(
    campaign: str | Campaign, runs: list[Run] | list[str]
) -> Campaign

Add runs to a campaign through the reports they generated.

A campaign holds reports, not runs, so each run must have a default report. Pass create_default_report=True to RunCreate to get one.

PARAMETER	DESCRIPTION
campaign	The Campaign or campaign ID to add to. TYPE: str | Campaign
runs	The Runs or run IDs to add. TYPE: list[Run] | list[str]

RETURNS	DESCRIPTION
Campaign	The updated Campaign.

RAISES	DESCRIPTION
ValueError	If any run has no default report.

archive async

archive(campaign: str | Campaign) -> Campaign

Archive a campaign.

PARAMETER	DESCRIPTION
campaign	The Campaign or campaign ID to archive. TYPE: str | Campaign

RETURNS	DESCRIPTION
Campaign	The archived Campaign.

unarchive async

unarchive(campaign: str | Campaign) -> Campaign

Unarchive a campaign.

PARAMETER	DESCRIPTION
campaign	The Campaign or campaign ID to unarchive. TYPE: str | Campaign

RETURNS	DESCRIPTION
Campaign	The unarchived Campaign.

report_summaries async

report_summaries(
    campaigns: list[str | Campaign],
    *,
    organization_id: str | None = None,
) -> dict[str, list[CampaignReport]]

Get per-report rule counts for several campaigns at once.

PARAMETER	DESCRIPTION
campaigns	The Campaigns or campaign IDs to summarize. TYPE: list[str | Campaign]
organization_id	Required if you belong to several organizations. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
dict[str, list[CampaignReport]]	A mapping of campaign ID to its reports, with counts populated. The service
dict[str, list[CampaignReport]]	returns each campaign's reports in no fixed order; Campaign.report_summaries
dict[str, list[CampaignReport]]	orders them to match the campaign.