The creditLimit Field on an Audience Signal with the Clay CLI

An audiences-scoped signal accepts a creditLimit object at creation, and the CLI stores and echoes it back exactly as submitted regardless of the workspace's plan. Whether that stored number actually caps spend depends on a separate, workspace-level setting that is not visible through this field or through the CLI at all.

What you will build

A JobChange signal created against a saved audience with a creditLimit, to show that the value is accepted and stored unconditionally.

clay signals create --input '{...,"creditLimit":{"limit":5}}'
    ↓
clay signals get <triggerDefinitionId>   (creditLimit is echoed back)

AI Prompt

Using the Clay CLI, create a signal against a saved audience segment with a creditLimit,
and confirm what that field does and does not guarantee.

Requirements:
- creditLimit is only valid on an audiences-scoped signal (segmentIds/entityType), not a
  table-scoped one.
- `clay signals create --type JobChange --input '{"entityType":"CONTACT","segmentIds":[...],"creditLimit":{"limit":5}}'`.
- The created object stores and returns creditLimit exactly as submitted. This alone does
  not confirm it is enforced: enforcement depends on whether the workspace has audience
  credit limits enabled, which is not exposed by any `clay` command.
- Do not treat a stored creditLimit as a guaranteed spend cap without separately confirming
  with the workspace's plan or an admin that the feature is enabled.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
• An existing Audiences segment for the people entity type

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Create a signal with a creditLimit

clay signals create --type JobChange \
  --name "Champions moving, capped" \
  --input '{"entityType":"CONTACT","segmentIds":["audseg_example"],"creditLimit":{"limit":5}}'

Real output:

{
  "id": "td_example",
  "runStatus": "Paused",
  "signal": {
    "type": "JobChange",
    "inputs": {
      "entityType": "CONTACT",
      "segmentIds": ["audseg_example"],
      "creditLimit": { "limit": 5 },
      "lookBackTimeWindowInMonths": 3
    }
  }
}

Verify the result

clay signals get td_example

Expected: signal.inputs.creditLimit reports {"limit": 5} exactly as submitted, on any workspace, regardless of whether the feature is enabled there.

How it works

creditLimit is part of the signal's stored configuration and round-trips through create, get, and update the same way any other input field does. Whether it changes billing behavior is decided elsewhere, by a workspace-level toggle for audience credit limits that no clay signals or clay workspaces command surfaces. A stored value and an enforced cap are two different things, and the CLI alone cannot distinguish them.

Common issues

A stored creditLimit is not proof of an enforced cap

Because the field is stored unconditionally, seeing it echoed back in clay signals get output confirms only that the value was saved, not that a run will actually stop at that limit. Confirm enforcement through the workspace's plan settings rather than inferring it from the CLI response.

creditLimit on a table-based signal

creditLimit is documented for audiences-scoped signals only (entityType/segmentIds). A table-scoped signal (tableId/viewId) has no equivalent field in its input shape.

Next steps

• How Topic-Intent Signals Are Billed
• Measuring Real Signal Cost with credits balance

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay signals get <triggerDefinitionId>"
  expected_result: "creditLimit is stored and echoed back exactly as submitted, independent of whether the workspace enforces it."

Related Articles

• Signal Targeting Edge Cases with the Clay CLI
• Watching an Audience for Job Changes with the Clay CLI
• Watching for Promotions with the Clay CLI