> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Campaigns

**Tool name** `list_campaigns`

<Info>Read-only · Idempotent</Info>

Lists a workspace's individual GAM campaigns (orders), one per row, with each campaign's lifetime delivery — impressions, CTR, and active status — filtered by a name/id search, active/inactive status, and Permutive-targeting, and ordered by name, dates, impressions, or CTR. Returns one page of named campaigns at a time.

## Example prompt

> Show me the active Permutive-targeted campaigns across my workspaces, sorted by impressions.

## Parameters

<ParamField body="cohort_id" type="string">
  Restrict to campaigns whose targeting included this cohort (by short id). When set, `impressions` and `ctr` become the cohort's own targeted figures within each campaign rather than the campaign's lifetime totals.
</ParamField>

<ParamField body="name_contains" type="string">
  Case-insensitive substring matched against each campaign's name and campaign id. Omit to match all campaigns.
</ParamField>

<ParamField body="page_token" type="string">
  Opaque token from a previous response's `next_page_token`, to fetch the next page.
</ParamField>

<ParamField body="permutive_targeted_only" type="boolean">
  When true (the default), only campaigns that use Permutive targeting; when false, all campaigns in the workspace.
</ParamField>

<ParamField body="sort_by" type="enum">
  Field to order the listing by. Omit for the default order — active campaigns first, then soonest end date. one of: `name`, `start_date`, `end_date`, `impressions`, `ctr`.
</ParamField>

<ParamField body="sort_order" type="enum">
  Order direction. Defaults to ascending. Ignored when sort\_by is omitted (the default order is fixed). one of: `asc`, `desc`.
</ParamField>

<ParamField body="status" type="enum">
  Restrict to active or inactive campaigns. A campaign is active when its end date is in the future. Omit for both. one of: `active`, `inactive`.
</ParamField>

<ParamField body="workspace_ids" type="string[]" required>
  Workspaces whose GAM campaigns (orders) are aggregated into a single flat list. min 1 item.
</ParamField>

## Returns

<ResponseField name="campaigns" type="CampaignListItem[]">
  A page of campaigns matching the query, in the requested order.

  <Expandable title="CampaignListItem">
    <ResponseField name="active" type="boolean" required>
      Whether the campaign is currently active — its end date is in the future.
    </ResponseField>

    <ResponseField name="agency" type="string">
      Agency associated with the order, when GAM records one. Often absent.
    </ResponseField>

    <ResponseField name="campaign_id" type="string" required>
      The campaign id. Pass to get\_campaign to read one campaign in detail.
    </ResponseField>

    <ResponseField name="ctr" type="number (double)" required>
      Lifetime click-through rate. When the cohort filter is set, this is instead the cohort's own targeted CTR within the campaign.
    </ResponseField>

    <ResponseField name="end_date" type="string" required>
      Order end date (ISO 8601).
    </ResponseField>

    <ResponseField name="impressions" type="integer (int64)" required>
      Lifetime impressions delivered against the order. When the cohort filter is set, this is instead the cohort's own targeted impressions within the campaign.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Campaign (order) name.
    </ResponseField>

    <ResponseField name="permutive_targeted" type="boolean" required>
      Whether the campaign uses Permutive targeting.
    </ResponseField>

    <ResponseField name="start_date" type="string" required>
      Order start date (ISO 8601).
    </ResponseField>

    <ResponseField name="workspace_ids" type="string[]" required>
      Which of the requested workspaces this campaign appears under. min 1 item.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_page_token" type="string">
  Pass as `page_token` to fetch the next page. Absent on the last page. Expires shortly after the first page.
</ResponseField>

<ResponseField name="total_matching" type="integer (int32)" required>
  Total campaigns matching the filters across all pages, before pagination.
</ResponseField>