Events

An event is an object representing a change to a resource that was observed by an event subscription.

In general, requesting events on a resource is faster and subject to higher rate limits than requesting the resource itself. Additionally, change events bubble up - listening to events on a project would include when stories are added to tasks in the project, even on subtasks.

Establish an initial sync token by making a request with no sync token. The response will be a 412 error - the same as if the sync token had expired.

Subsequent requests should always provide the sync token from the immediately preceding call.

Sync tokens may not be valid if you attempt to go ‘backward’ in the history by requesting previous tokens, though re-requesting the current sync token is generally safe, and will always return the same results.

When you receive a 412 Precondition Failed error, it means that the sync token is either invalid or expired. If you are attempting to keep a set of data in sync, this signals you may need to re-crawl the data.

Sync tokens always expire after 24 hours, but may expire sooner, depending on load on the service.

Events have the following fields:

Field Description
user { id: 12345, name: 'Tim Bizarro' } null Read-only. The user who triggered the event.

Note: The event may be triggered by a different user than the subscriber. For example, if user A subscribes to a task and user B modified it, the event’s user will be user B. Note: Some events are generated by the system, and will have null as the user. API consumers should make sure to handle this case.
resource { id: 1234, name: 'Bug task' } Read-only. The resource the event occurred on.

Note: The resource that triggered the event may be different from the one that the events were requested for. For example, a subscription to a project will contain events for tasks contained within the project.
type 'task' Read-only. The type of the resource that generated the event.

Note: Currently, only tasks, projects and stories generate events.
action 'changed' Read-only. The type of action taken that triggered the event.
parent { id: 1234, name: 'Bugs' } Read-only. For added/removed events, the parent that resource was added to or removed from. null for other event types.
created_at '2012-02-22T02:06:58.147Z' Read-only. The timestamp when the event occurred.

GET EVENTS ON RESOURCE

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/project/3214312/events?sync=de4774f6915eae04714ca93bb2f5ee81:3

# Response
HTTP/1.1 412 Precondition Failed
{
  "message": "Sync token invalid or too old. If you are attempting to keep resources in sync, you must re-fetch the full dataset for this query now.",
  "sync": "edfc0896b370b7a479886d316131bf5c:0"
}
GET    /events

Returns the full record for all events that have occurred since the sync token was created.

A GET request to the endpoint /[path_to_resource]/events can be made in lieu of including the resource ID in the data for the request.

Parameter Description
resource 12345 Required: A resource ID to subscribe to. The resource can be a task or project.
sync 'de4774f6915eae04714ca93bb2f5ee81' A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated.

Note: On your first request, omit the sync token. The response will be the same as for an expired sync token, and will include a new valid sync token.If the sync token is too old (which may happen from time to time) the API will return a 412 Precondition Failed error, and include a fresh sync token in the response.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/events?resource=14321&sync=de4774f6915eae04714ca93bb2f5ee81:3

# Response
HTTP/1.1 200
{
  "data": [
    {
      "resource": {
        "id": 1337,
        "name": "My Task"
      },
      "parent": null,
      "created_at": "2013-08-21T18:20:37.972Z",
      "user": {
        "id": 1123,
        "name": "Tom Bizarro"
      },
      "action": "changed",
      "type": "task"
    },
    {
      "resource": {
        "id": 1338,
        "name": "My Other Task"
      },
      "parent": null,
      "created_at": "2013-08-21T18:22:45.421Z",
      "user": {
        "id": 1428,
        "name": "Greg Sanchez"
      },
      "action": "changed",
      "type": "task"
    }
  ],
  "sync": "edfc0896b370b7a479886d316131bf5c:0"
}