Rate Limiting

To keep the platform fast and fair, the API limits how many requests each account can make in a short window. If you exceed the limit, further requests are temporarily rejected with HTTP 429 (Too Many Requests) until the window resets. Rate limits protect you too — they stop a runaway script from exhausting your account's capacity.

How the limits work

• Per account. Limits apply to your Sheetgo user account, across all of your API keys combined. Creating extra API keys does not add capacity — the budget is shared by the account.
• Two separate budgets:
  • Reads — GET and HEAD requests (higher allowance).
  • Writes — POST, PUT, PATCH, DELETE requests (lower allowance).
• Per-minute window. Each budget refills on a rolling one-minute basis.

Current default limits (per account, per minute): 120 read, 30 write. Do not hard-code these numbers — some accounts have higher allowances and limits may change. Read the limit from the response headers instead.

Response headers (on every response)

When X-RateLimit-Remaining approaches 0, slow down before you get blocked — the most effective way to avoid 429s.

When you are throttled

A 429 response includes a Retry-After header and a JSON body:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 120 read requests per minute. Retry after 37 seconds.",
  "retry_after": 37,
  "limit": 120,
  "remaining": 0,
  "reset": 37,
  "scope": "read"
}

Consuming the API reliably

1. Honor Retry-After on a 429 — wait at least that many seconds before retrying.
2. Use exponential backoff with jitter for other transient errors.
3. Self-throttle using X-RateLimit-Remaining — slow down proactively.
4. Spread work out with small delays rather than bursting.
5. Cache and avoid redundant calls — reads count even when data is unchanged.
6. Treat 429 as normal — catch it, wait, and retry transparently.

Reference retry loop:

for attempt in range(max_retries):
    resp = call_api(...)
    if resp.status_code != 429:
        return resp
    wait = int(resp.headers.get("Retry-After", 2 ** attempt))
    sleep(wait + random_jitter())

Automated agents and LLM tools

The response body carries everything needed to recover (retry_after, scope, and a plain-language message) — parse the body, not just the status code. Honor retry_after rather than retrying in a tight loop. Most HTTP client libraries already back off automatically on 429 + Retry-After; keep that on.

Need higher limits?

If your legitimate workload consistently approaches the limits, contact Sheetgo support to raise your account's capacity. A change takes effect automatically — and because you read the limit from X-RateLimit-Limit, your integration needs no code change.

API Key Scopes

Sheetgo API keys let apps, scripts, and AI agents act on your Sheetgo account. By default a key can do everything you can — read, edit, run, and delete any workflow, automation, form, and more.

Scopes let you narrow that down. You can limit a key to certain actions (view only, or edit, or delete) and to certain items (all of your workflows, or only a specific few). This is useful when you hand a key to an AI agent or script that should only read data, an integration that should touch only one or two workflows, or a partner who should have limited access.

Scopes only limit the key — not you. Restricting a key never changes what you can do when you log in to Sheetgo yourself; it only limits requests made with that key.

The two things a scope controls

A scope combines what actions are allowed with which items they apply to.

Actions

Running a workflow counts as "Edit", not "View." A View-only key cannot start runs — give it Edit if it needs to.

Items

For each action you can choose all items of that type (all workflows, all automations, …) or only specific items you pick. You can also apply a scope to everything at once (all resource types) — for example, "View everything."

Item types you can scope: workflows, automations, forms, triggers (schedules), webhooks, Outlook, and API destinations.

Setting scopes in your Account

1. Go to Account → Services and account → Sheetgo API.
2. Create a new key, or open an existing key to edit it.
3. Choose the access level:
   • Full access (default) — the key can do everything.
   • All items, limited actions — e.g. View only across everything.
   • Custom — pick actions per item type, and optionally restrict each to specific items.
4. Save. When creating a key, copy it immediately — it is shown only once. When editing, changes take effect right away; you don't need to regenerate the key — the same key keeps working with its new limits.

Examples

• Read-only monitoring key — View → All items. Lists and reads everything; cannot edit, run, or delete.
• Run/edit only two workflows — Workflows → Edit → "Monthly Report", "Sales Sync". Can run and edit those two, nothing else.
• Read everything, edit one — View → All items plus Workflows → Edit → "Client Import". A common "safe agent" setup.
• Partner access to one workflow — Workflows → Full → "Partner Feed". View, edit, run, and delete that one workflow only.
• No restriction (default) — Full access.

Good to know

• Restricting to specific items means the key can't create new ones. Limiting Edit to a specific list lets the key change those items but not create brand-new ones. Give Edit → All items to allow creation.
• Forms and schedules follow their workflow. A form or trigger is reachable only if the key can also view its workflow.
• Lists respect the scope. A key limited to specific workflows sees only those when it lists workflows.
• Keep keys secret. A key is shown only once; if it leaks, delete it and create a new one. Scopes reduce the damage a leaked key can do but don't replace keeping it safe.
• Changing a scope doesn't rotate the key — editing limits keeps the same key string working.

Smart Tags

A smart tag is a {{placeholder}} that Sheetgo replaces with a value from your data while an automation runs. They are used by the document destination — both inside the Google Docs template and in the destination's file_name.

How a tag resolves

A tag matches a column header in the data reaching the destination, and is replaced with that row's value. One document is generated per row.

Header names are matched as they appear in your data, spaces included. There is no mapping to configure: name the tag after the column.

Where tags can be used

• In the template document (document destination) — anywhere in the body, including headers, footers and tables.
• In file_name (document) — so each generated document gets a distinct name, e.g. "Invoice {{Invoice No}} - {{Customer}}".
• In subject and body (share, mail_merge) — the email is rendered per row, so each recipient sees their own values.
• As a recipient (share, mail_merge) — to, cc, bcc and reply_to accept a "{{Header}}" string instead of addresses, which reads the address from that column. The reference must be the whole value: "{{Email}}" works, ["{{Email}}"] and "cc: {{Email}}" do not.

When a tag has no matching column

unused_fields decides:

• error (default) — the run fails, so a template/data mismatch is visible.
• ignore — the tag is replaced with an empty string and the run continues.

Reserved tags

PDF settings

The pdf destination has no smart tags — generated PDFs take their name from the file they were converted from. Its paper_size, page_orientation, scale and merge_files fields control the export. Note that paper_size values for ISO sizes are uppercase: A3, A4, A5, B4, B5.

Cell References

A cell reference is a {{Tab!Ref}} placeholder you put inside an api source's request. When the automation runs, Sheetgo reads that cell from the automation's Google Sheets destination and substitutes the value before the request goes out — so the request changes as your sheet changes, with no API call needed.

GET https://api.example.com/events?since={{Log!A:last|date|fmt:iso_dt}}

Which {{ }} am I looking at?

Three unrelated syntaxes share the double-brace shape. They are not interchangeable.

A cell reference always contains a !. A smart tag is a bare column name. The body template uses the reserved names DATA and ROWS and the block tags {{for}}, {{if}} and {{except-last}}.

Grammar

{{ <tab>!<ref> [|<filter>]* }}

• <tab> — a tab in the destination spreadsheet. Quote it with single quotes if it contains a space, a special character, or starts with a digit: {{'My Sheet'!A1}}, {{'2026 Sales'!A1}}. Double an apostrophe inside a quoted name: {{'O''Brien'!C3}}. When in doubt, quote it — the quoted form always works.
• <ref> — a single cell (A1, B7, AB42) or A:last, the last non-empty cell in column A. Case-insensitive. Ranges (A1:B5), whole columns (A:A), whole rows, named ranges and formulas are not supported.
• |<filter> — optional, chainable, applied left to right.

Filters

Render mode — must be the first filter if used. Default is F.

F and U after another filter are invalid, and the placeholder is left as literal text.

String — trim (strip whitespace), upper, lower.

Numeric — int, float. Both fail the run on a non-numeric value.

Date input — promote the value to a date, always doing work:

Accepts strings, Sheets serial numbers, and existing dates. On its own a date filter renders ISO datetime; chain a fmt:* to change that.

Date output — fmt:*, a no-op unless a date input filter came first:

fmt:day, fmt:month, fmt:year, fmt:timestamp (Unix seconds), fmt:timestamp_ms (Unix milliseconds), fmt:serial (Sheets serial), fmt:iso_dt, fmt:iso_d, fmt:us_dt, fmt:us_d, fmt:eu_dt, fmt:eu_d. _dt includes the time, _d is date only.

Where they go

When something goes wrong

⚠️ Requires a Google Sheets destination

Substitution reads from the automation's destination, so it only happens when that destination is a Google Sheets file. With any other destination the placeholders are sent to your API as literal text, with no warning.

⚠️ Never resolves alongside a webhook destination

A webhook destination must be an automation's only destination, so such an automation has no Sheets destination to read from. Cell references in it will always be sent literally. Pair cell references with a file destination instead.