---
updatedAt: 2026-08-19T02:10:18.000Z
agentTools:
  projectIndex: https://docs.delivr.ai/llms.txt
---

# Batch audience usage rollup

Returns export and campaign usage for a batch of audiences, so a list view can show which ones are in use without a request per row.

Every requested id comes back, in the order requested. An audience with no live export is returned with zero counts and `in_use` false, which also covers ids that no longer exist, so a missing entry never means "not found".

The project is taken from the authenticated context rather than a parameter, so usage is only ever reported within the caller's own project.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Intent Audiences",
    "description": "Build and export person-level intent audiences end to end. Browse the topic **taxonomy** to find what your buyers research, discover the **fields** you can filter on, then create, manage, sample, and download **audiences**.\n\n**Authentication:** organization API key (`X-Api-Key` + `X-Api-Secret`). Audiences are project-scoped: name the project with the `X-Project-Id` header or a `?project_id=` query parameter (equivalent). (Legacy JWT bearer auth still works but is deprecated.)\n\n**Base URL:** `https://api.delivr.ai`\n",
    "version": "1.0",
    "contact": {
      "name": "Delivr.ai Support",
      "url": "https://delivr.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.delivr.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "ApiSecretAuth": []
    }
  ],
  "tags": [
    {
      "name": "Audiences",
      "description": "Create, manage, sample, and download person-level intent audiences."
    }
  ],
  "paths": {
    "/api/v1/audiences/linkage-usage": {
      "get": {
        "tags": [
          "Audiences"
        ],
        "summary": "Batch audience usage rollup",
        "operationId": "getAudienceLinkageUsage",
        "description": "Returns export and campaign usage for a batch of audiences, so a list view can show which ones are in use without a request per row.\n\nEvery requested id comes back, in the order requested. An audience with no live export is returned with zero counts and `in_use` false, which also covers ids that no longer exist, so a missing entry never means \"not found\".\n\nThe project is taken from the authenticated context rather than a parameter, so usage is only ever reported within the caller's own project.\n",
        "parameters": [
          {
            "name": "audience_ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated audience ids. Duplicates are collapsed. Maximum 500 ids per request.",
            "schema": {
              "type": "string"
            },
            "example": "101,102,103"
          }
        ],
        "responses": {
          "200": {
            "description": "Usage for each requested audience.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AudienceLinkageUsage"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`audience_ids` missing, not a comma-separated list of integers, or more than 500 ids."
          },
          "401": {
            "description": "Missing or invalid authentication."
          },
          "500": {
            "description": "Failed to load audience usage."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Organization API key (`dlvr_` prefixed), created in the dashboard at `https://app.delivr.ai/{org_id}/settings/api-keys`. Must be paired with the `X-Api-Secret` header."
      },
      "ApiSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Secret",
        "description": "Secret half of the organization API key, paired with `X-Api-Key`. Both headers are required on every request."
      }
    },
    "schemas": {
      "AudienceLinkageUsage": {
        "type": "object",
        "required": [
          "audience_id",
          "export_count",
          "active_export_count",
          "active_campaign_count",
          "in_use"
        ],
        "properties": {
          "audience_id": {
            "type": "integer",
            "format": "int64",
            "example": 101
          },
          "export_count": {
            "type": "integer",
            "format": "int64",
            "description": "Exports referencing this audience, including inactive ones.",
            "example": 3
          },
          "active_export_count": {
            "type": "integer",
            "format": "int64",
            "description": "Exports referencing this audience that are currently active.",
            "example": 1
          },
          "active_campaign_count": {
            "type": "integer",
            "format": "int64",
            "description": "Active campaigns referencing this audience.",
            "example": 2
          },
          "in_use": {
            "type": "boolean",
            "description": "True when `active_export_count` is above zero. Derived from the counts rather than stored, so it cannot disagree with them.",
            "example": true
          }
        }
      }
    }
  }
}
```