Count an audience

Counts UK contacts and companies matching an audience, inline or a saved aud_ id, and returns Total, New to you and Emailable, up to three breakdowns, quality, the compliance summary, a price estimate and a count id. Use it whenever a filter changes, and before preview_records or quote_order, which both take the count id. Free and needs no account; anonymous and trial callers see counts under 100 and breakdown cells rounded to the nearest 5 (disclosure says which), and exact small counts need a paid plan. It returns no contact details, and over MCP a cross-tab holds at most 200 cells (truncated true; GET /v1/counts/{id} has the rest). Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

Input

The schema sets additionalProperties to false, so a member that is not listed is refused.

Example call

The params of a tools/call request:

{
  "name": "count_audience",
  "arguments": {
    "audience": {
      "schema": "mydatahub.audience/1",
      "dataset": "uk_contacts",
      "where": {
        "all": [
          {
            "field": "contact.title",
            "op": "matches",
            "terms": ["marketing manager"],
            "mode": "contains"
          },
          {
            "field": "contact.job_level_rank",
            "op": "in",
            "values": [1, 2, 3, 4, 5, 6, 8, 9]
          },
          {
            "field": "company.sic_2007",
            "op": "in",
            "values": ["C"]
          },
          {
            "field": "company.employee_band",
            "op": "gte",
            "value": "50-99"
          },
          {
            "field": "site.location",
            "op": "within_radius",
            "centre": {
              "place": "Leeds"
            },
            "radius_miles": 20
          },
          {
            "not": {
              "field": "email.address_sha256",
              "op": "in_list",
              "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
            }
          }
        ]
      }
    },
    "level": "contact",
    "breakdown_by": ["contact.job_level_rank"]
  }
}

Output

The result carries structuredContent that matches this schema, and one line of text that leads with the number.

Showing the first 80 of 83 members. The OpenAPI document and the MCP tool list hold the full schema.

Errors

A failed call returns isError true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with code, detail, next_step and did_you_mean. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See Errors.