Rate Limits - OneShot

Overview

Paid endpoints allow 60 requests a minute, expensive operations 10, and free reads 120. Over the limit, the API returns 429 Too Many Requests and the SDK retries with backoff. Limits keep usage fair and the system stable. Depending on the endpoint type, they apply per agent (by wallet address) or per IP address.

Rate Limits by Endpoint Type

Endpoint Type	Limit	Window	Key
Paid endpoints	60 requests	1 minute	Agent wallet
Expensive operations	10 requests	1 minute	Agent wallet
Free read endpoints	120 requests	1 minute	Agent wallet

Endpoint Categories

Paid Endpoints (60/min)

POST /v1/tools/email/quote
POST /v1/tools/email/send
POST /v1/tools/enrich/email
POST /v1/tools/enrich/profile
POST /v1/tools/verify/email
POST /v1/tools/commerce/search
POST /v1/tools/commerce/buy
POST /v1/tools/sms/send

Expensive Operations (10/min)

Resource-intensive operations get the strictest limit:

POST /v1/tools/voice/call: voice calls
POST /v1/tools/research: deep web research
POST /v1/tools/research/people: people discovery

Free Read Endpoints (120/min)

Read-only endpoints that need no payment:

GET /v1/tools/inbox/list: email inbox list
GET /v1/tools/inbox/:id: email details
GET /v1/tools/sms/inbox: SMS inbox list
GET /v1/tools/sms/inbox/:id: SMS details
GET /v1/requests/:id: job status polling

Rate Limit Response

Exceeding a limit returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests, please try again later.",
  "retry_after": 60
}

Response Headers

Header	Description
`RateLimit-Limit`	Maximum requests allowed in window
`RateLimit-Remaining`	Requests remaining in current window
`RateLimit-Reset`	Seconds until the window resets

Best Practices

Implement exponential backoff

On a 429, wait for the retry_after period before retrying. If it repeats, increase the wait exponentially.

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Batch operations when possible

Where available, send to many recipients in one request:

SMS: up to 10 recipients per request
Email: multiple recipients per send

Cache inbox results

Free read endpoints such as inbox list and status polling have generous limits. Caching results client-side still saves calls.

Let the SDK wait for results

Both SDKs subscribe to a WebSocket push for the job and also poll GET /v1/requests/:id on a short backoff (300ms → 2s, relaxing to 5s once the push channel is confirmed). Most results arrive within a few seconds of dispatch. If you poll by hand, make the first check sub-second and back off. There is no webhook for job completion.

SDK Handling

The SDK retries rate-limited calls itself:

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY
});

// SDK automatically retries on 429 with exponential backoff
const result = await agent.research({
  query: "Latest AI developments"
});

Need Higher Limits?

For higher limits or enterprise options, email [email protected].

​Overview

​Rate Limits by Endpoint Type

​Endpoint Categories

​Paid Endpoints (60/min)

​Expensive Operations (10/min)

​Free Read Endpoints (120/min)

​Rate Limit Response

​Response Headers

​Best Practices

​SDK Handling

​Need Higher Limits?