Plans and quotas

API limits come from your workspace's plan. They apply the same way in the dashboard and in the API: an address added through the API counts toward the same limit as one added from the dashboard.

Plans that include the API#

	Free	Starter	Pro	Business
API and key-based real-time access	no	no	yes	yes
Calls per day (UTC)	—	—	10,000	unlimited
Requests per second per key	—	—	25	50
Watched addresses	3	25	100	unlimited
Rules	3	unlimited	unlimited	unlimited
Channels	1	5	10	unlimited
Channel kinds	Telegram, Discord, helloMe	all	all	all
Chains	2	all	all	all
Immediate alert (before confirmation)	no	no	yes	yes
History retention	30 days	90 days	365 days	730 days

Values in force at the date of the changelog. They can change: the source of truth for your workspace is GET /v1/workspace (limits field), and public pricing is on the home page (data from GET /api/public/plans). The Business plan is quoted on request: write to support@aicscan.io.

On plans without the API, every authenticated route answers:

JSON

{
  "error": {
    "code": "plan_required",
    "message": "API access is not included in the `starter` plan. Upgrade to a plan that includes the API (Pro or Business).",
    "details": { "plan": "starter", "feature": "api" }
  }
}

Reading your limits and usage#

Shell

curl https://aicscan.io/v1/workspace -H "Authorization: Bearer $AICSCAN_API_KEY"

limits: plan limits (null = unlimited). limits.channel_kinds is null when all channel kinds are allowed. limits.requests_per_second is the rate applied to the calling key.
usage: addresses, rules and channels in use, and requests_today, the number of calls served today (UTC day).

Resource limits#

When a creation would exceed a limit, the API answers 403 plan_limit_reached:

JSON

{
  "error": {
    "code": "plan_limit_reached",
    "message": "Your plan allows 100 addresses; upgrade to add more.",
    "details": { "resource": "addresses", "limit": 100, "current": 100, "plan": "pro" }
  }
}

details.resource is addresses, rules, channels or chains. A rule's addresses are added to the watched addresses and count toward the limit; a rule or address on a chain that is new for the workspace counts toward the chain limit.

Other plan-related refusals:

Code	Cause
`channel_kind_not_in_plan`	Channel kind not included in the plan (`details.allowed_kinds`).
`plan_feature_unavailable`	`immediate_alert: true` requested on a plan without immediate alerts (`details.feature`).

Daily quota#

On a limited plan (Pro: 10,000 calls per day), calls are counted per workspace and per UTC day, across all keys. Only calls that are served count: a call refused before processing (invalid key, rate limit, missing scope) consumes nothing. Opening a real-time connection counts as one call.

Every response carries:

HTTP

Aicscan-Daily-Quota-Limit: 10000
Aicscan-Daily-Quota-Remaining: 9682

Past the quota, the API answers 429 daily_quota_exceeded; Retry-After gives the number of seconds until midnight UTC, when the counter starts again from zero.

JSON

{
  "error": {
    "code": "daily_quota_exceeded",
    "message": "Daily API quota of the `pro` plan reached (10000 calls per day). It resets at 00:00 UTC.",
    "details": { "limit": 10000, "used": 10000, "plan": "pro", "resets_in_seconds": 5240 }
  }
}

On the Business plan (unlimited), these headers are absent. The per-second rate still applies: see Rate limits.

API keys and plan#

On a plan without the API, the API keys page of the client area stays readable but creating a key is refused (plan_required). After moving to Pro or Business, create your key from that page. Existing keys remain after moving to a plan without the API, but their calls answer 403 plan_required. Questions about plans: support@aicscan.io.