Limits

Limit how much money can move. Account limits gate everything you and your agents do. Agent limits hold one agent to a tighter budget than the rest of your account. Both apply to a single payment (perTransaction), a UTC calendar day (perDay), or a calendar month (perMonth).

A limit never automatically fails a payment. A payment that breaches a limit returns a normal 2xx, no money moves, and it holds as an approval until someone approves or denies it. See Approvals.

Account limits

Your account limits are the backstop over everything you and every agent do.

Read your limits

GET /parties/me/limits returns the current limits.

limits = client.parties.get_limits()

const limits = await client.parties.getLimits();

natural parties getLimits

What are my account spending limits?

curl https://api.natural.com/parties/me/limits \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Set your limits

PUT /parties/me/limits replaces all three windows at once.

limits = client.parties.set_limits(
    per_transaction=250_000,  # $2,500 per payment
    per_day=1_000_000,        # $10,000 per day
    per_month=None,           # no monthly limit
)

const limits = await client.parties.setLimits({
  perTransaction: 250_000, // $2,500 per payment
  perDay: 1_000_000, // $10,000 per day
  perMonth: null, // no monthly limit
});

natural parties setLimits --per-transaction 250000 --per-day 1000000

curl -X PUT https://api.natural.com/parties/me/limits \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "perTransaction": 250000,
        "perDay": 1000000,
        "perMonth": null
      }
    }
  }'

Remove all limits

DELETE /parties/me/limits clears every window in one call. To clear just one window, PUT that window as null and keep the others. Removing your account limits does not touch an agent’s own limits or a limit a customer set on your agent; clear those where you set them.

client.parties.disable_limits()

await client.parties.disableLimits();

natural parties disableLimits

curl -X DELETE https://api.natural.com/parties/me/limits \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Agent limits

Give one agent a tighter budget than the rest of your account. Set limits when you create the agent with limits on POST /agents. To change them afterward, PATCH /agents/{agentId}. limits is a full replacement: sending it resets every window to what you pass.

import uuid

agent = client.agents.update(
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
    limits={"per_transaction": 100_000},  # $1,000; clears perDay and perMonth
)

const agent = await client.agents.update({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
  limits: { perTransaction: 100_000 }, // $1,000; clears perDay and perMonth
});

natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
  --idempotency-key "$(uuidgen)" \
  --json '{"limits": {"perTransaction": 100000}}'

curl -X PATCH https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "limits": { "perTransaction": 100000 }
      }
    }
  }'

{
  "data": {
    "type": "agent",
    "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
    "attributes": {
      "name": "Carrier Payment Agent v3.0",
      "description": "Autonomous agent that pays delivery carriers with enhanced fraud detection",
      "handle": "@natural-carrier_payments",
      "status": "ACTIVE",
      "limits": {
        "perTransaction": 100000
      },
      "createdAt": "2026-01-04T15:30:00Z",
      "createdBy": "usr_550e8400e29b41d4a716446655440000",
      "lastActiveAt": "2026-01-05T09:12:00Z"
    },
    "relationships": {
      "party": {
        "data": {
          "type": "party",
          "id": "pty_7c9e6679e29b41d4a716446655440001"
        }
      }
    }
  }
}

See Invite a customer for the full invitation and its request shape.

How limits compose

A payment can pass through several limits: your account limit, the agent limit, and limits set by your customer. They are independent gates with no precedence: every applicable one must clear, so in effect the tightest limit wins.

Level	Limits	Set by
Account	`perTransaction`, `perDay`, `perMonth`	You, for your whole account
Agent	`perTransaction`, `perDay`, `perMonth`	You, per agent
On a customer’s behalf	`perTransaction` only	A customer, when they authorize your agent

A payment that breaches any limit holds for approval. All limits must clear or be approved for a payment to complete.

Overview

Common use cases

Products

Guides

Account limits

Read your limits

Set your limits

Remove all limits

Agent limits

How limits compose

​Account limits

​Read your limits

​Set your limits

​Remove all limits

​Agent limits

​How limits compose

Account limits

Read your limits

Set your limits

Remove all limits

Agent limits

How limits compose