When an object (like a task) is edited, the relevant application creates a "transaction" and applies it. This list of transactions on each object is the basis for essentially all edits and comments. Reviewing the transaction record allows you to see who edited an object, when, and how their edit changed things.

One common reason to call this method is that you're implementing a webhook and just received a notification that an object has changed. See the Webhooks documentation for more detailed discussion of this use case.

One Object Type at a Time

This API method can query transactions for any type of object which supports transactions, but only one type of object can be queried per call. For example: you can retrieve transactions affecting Tasks, or you can retrieve transactions affecting Revisions, but a single call can not retrieve both.

This is a technical limitation arising because (among other reasons) there is no global ordering on transactions.

To find transactions for a specific object (like a particular task), pass the object PHID or an appropriate object identifier (like T123) as an objectIdentifier.

To find all transactions for an object type, pass the object type constant as an objectType. For example, the correct identifier for tasks is TASK. (You can quickly find an unknown type constant by looking at the PHID of an object of that type.)

All supported values for objectType:

Constraints

These constraints are supported:

• phids Optional list<phid>. Find specific transactions by PHID. This is most likely to be useful if you're responding to a webhook notification and want to inspect only the related events.
• authorPHIDs Optional list<phid>. Find transactions with particular authors.

Transaction Format

Each transaction has custom data describing what the transaction did. The format varies from transaction to transaction. The easiest way to figure out exactly what a particular transaction looks like is to make the associated kind of edit to a test object, then query that object.

Not all transactions have data: by default, transactions have a null "type" and no additional data. This API does not expose raw transaction data because some of it is internal, oddly named, misspelled, confusing, not useful, or could create security or policy problems to expose directly.

New transactions are exposed (with correctly spelled, comprehensible types and useful, reasonable fields) as we become aware of use cases for them.