What we do
Tools
Industries
Department
How we workLet's talk →
Home/Asana/Asana API
Asana developer reference

The Asana API: Authentication, Rate Limits, Pagination and Webhooks

Asana's REST API reaches tasks, subtasks, projects, sections, custom fields, comments and attachments, with webhooks for changes. Below is what you need while building. Rules are the one big exception, covered near the end. Still deciding what to connect, not how? The Asana hub covers that.

The essentials

Base URL: https://app.asana.com/api/1.0. Responses come wrapped in a data object, and write requests send their body inside data too.

Auth: send Authorization: Bearer {token}. The token is a personal access token for your own scripts, or an OAuth access token when other people sign in to your app.

Fields: list endpoints return compact records (mostly gid and name). Ask for what you need with opt_fields, e.g. ?opt_fields=name,completed,assignee.email,custom_fields.

PAT, OAuth or a service account?

Method Use it for Watch for
Personal access token (PAT) Scripts and internal tools that act as one person. Long-lived, and fine in production for single-user jobs. It sees exactly what that person sees, and it stops working when they leave. Tie important jobs to a dedicated account, not a staff member.
OAuth 2.0 Apps where several people sign in. Authorization code grant, with PKCE required for localhost and native redirect URIs. Access tokens expire after an hour. Store the refresh token and swap it at https://app.asana.com/-/oauth_token with grant_type=refresh_token. Request granular scopes such as tasks:read rather than full permissions where you can.
Service account Org-wide jobs: backups, admin automation, anything that needs all of the domain's data. Required for the audit log, organization exports and SCIM. Enterprise tiers only, and only a super admin can create one.

Asana API rate limits

Per authorization token. Every limiter answers with a 429 and a Retry-After header in seconds.

Limit Value Notes
Standard, free domains 150 requests a minute Low enough that a first full sync of a busy workspace needs pacing.
Standard, paid domains 1,500 requests a minute Requests rejected by this limiter still count, so retrying early pushes recovery further out.
Search API 60 requests a minute Separate from the standard limit.
Concurrent requests 50 GET, 15 writes in flight Reads and writes are limited separately. A parallel uploader hits the write cap long before the per-minute one.
Duplicate, instantiate and export jobs 5 at once per user Jobs someone starts in the web app count too.
Cost limit Not published Expensive requests drain a per-minute budget. Deep opt_fields on large lists are the usual cause.

Paginate every list

  1. 1

    Always send a limit

    Add limit (1 to 100) to every list request. Some older endpoints don't paginate unless you do, and an unpaginated query is cut off at about 1,000 objects, or times out in a large organization.

  2. 2

    Follow next_page

    The response carries next_page with an offset, a relative path and a full uri. Pass that offset on the next request. When next_page is null, you're done.

    Watch for: offsets expire. Don't park a token overnight and expect to resume from it; restart the walk instead.

Asana webhooks, from handshake to first event

Webhooks save you polling, but they're not a guarantee. Plan the catch-up job on day one.

  1. 1

    Create the webhook

    POST /webhooks with a resource (a project or task gid, for example) and your HTTPS target URL. Webhooks on a workspace, team, portfolio or goal must include filters, and they don't receive task, subtask or story events.

  2. 2

    Answer the handshake

    Before your create call returns, Asana sends a request to the target with an X-Hook-Secret header. Reply 200 or 204 with the same value in your own X-Hook-Secret header. Only then does the create call come back 201.

    Watch for: the secret. Store it now, because it's not returned when you fetch the webhook later. And your receiver must already be live when you call create, or the handshake fails.

  3. 3

    Verify every delivery

    Each request carries X-Hook-Signature: an HMAC-SHA256 of the raw request body, keyed with that secret. Compute it over the raw bytes, not a re-serialized body, and reject anything that doesn't match.

  4. 4

    Fetch what changed

    The body has an events array, often several at once. Each event says what changed, not the new state, so fetch the resource with opt_fields to get current values. Use each event's created_at rather than arrival order.

  5. 5

    Reply fast, and keep replying

    Return 200 within 10 seconds and process from a queue. Asana retries failed deliveries with backoff for up to 24 hours, and sends a heartbeat every 8 hours. If nothing succeeds for 24 hours, the webhook is deleted.

    Watch for: delivery is at-most-once and events can't be replayed. A scheduled job that compares Asana with your copy is the only way to be sure nothing was missed.

Where Asana API builds go wrong

Retrying a 429 on a fixed timer

How you'll know: The job spends longer throttled than working.

Fix: Wait exactly the Retry-After seconds. The official client libraries retry for you up to a set maximum; a hand-rolled client needs the same.

A webhook that disappeared

How you'll know: No events for days, and the webhook no longer shows when you list them.

Fix: Your endpoint missed heartbeats for 24 hours, or the resource was deleted. Alert on last_success_at going stale, recreate the webhook, and run the catch-up job for the gap.

Matching custom fields by name

How you'll know: Someone renames a field and the sync writes blanks.

Fix: Store custom field gids, look them up once at start, and fail loudly when an expected field is gone.

Expecting full records in list results

How you'll know: Assignee, due date or custom field values come back empty.

Fix: Compact records are the default. Name every field you need in opt_fields, and keep the list short to stay inside the cost limit.

What the API can and can't do with Rules

There's no endpoint to create a Rule or edit its triggers, conditions and actions. That stays in the Rule builder, as covered on our Asana automation page. What you can do, in beta, is fire one: give a Rule the Web request is received trigger in the builder, and Asana generates the endpoint POST /rule_triggers/{trigger_id}/run. Send it a target task and an action_data object, and the Rule runs with those values.

That makes a practical split. Let people who own the project keep the logic in a Rule they can read, and have outside systems call it. When the logic needs data Asana doesn't hold, or has to write to another system, it moves into code on the API instead.

Questions people ask

Is the Asana API free to use?

Yes. There's no separate fee, and it works on the free tier. The plan changes what you get: free domains are limited to 150 requests a minute against 1,500 on paid ones, and service accounts need an Enterprise tier.

Does Asana have webhooks?

Yes. Subscribe to a project, task or other resource with POST /webhooks, complete the X-Hook-Secret handshake, and Asana sends batched events when it changes. Delivery is at-most-once, so pair it with a scheduled check.

What's the rate limit on Asana's API?

1,500 requests a minute per token on paid domains and 150 on free ones, with separate caps of 60 a minute for search and 50 concurrent reads or 15 concurrent writes. Every limit returns a 429 with a Retry-After header.

Can I create or edit an Asana Rule through the API?

No. Building or editing a Rule's logic happens in Asana's Rule builder. The API can only run a Rule that has the Web request is received trigger, which is in beta.

Does Asana have an official SDK?

Yes. Asana publishes official client libraries, including ones for Node and Python, that handle authentication, pagination and 429 retries. Plain HTTP works just as well if you'd rather not take on a dependency.

How do I verify an Asana webhook signature?

Compute an HMAC-SHA256 of the raw request body using the secret from the handshake, and compare it with the X-Hook-Signature header. Reject the request if they differ.

Who builds Asana API integrations for small teams?

That's regular work for n-frames: webhook receivers, two-way syncs with accounting and CRM systems, and bulk migrations into Asana, with the monitoring that tells you when a run fell short.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.