Go to Aphex
All Collections
API & Integration
Aphex Data API
Task Events API V3

Task Events API V3

Jason avatar
Written by Jason
Updated over a week ago

Overview

The Task Events API provides Enterprises with access to the raw event stream of all the planning and statusing actions of users from across their projects.

💡 The Task Events API is available on the Aphex Enterprise plan

Structure

The API is designed to be called daily. Calling will provide you a list of task events, ordered chronologically, that you can use to reconstruct the data held in Aphex.

Events are generated by users creating, updating and deleting tasks as well as attaching day level delay and resource allocation.

The events are structured so that Enterprises can choose to store the event feed or use the events to keep an up to date record of all Tasks via an ETL operation.

Calling the API

The Task Events API can be called via a HTTP GET request to our endpoint 

https://api.aphex.co/taskEvents

Authentication

Along with the call you must include a custom header, x-api-key, with your organisation API key which was provided to you as part of your enterprise onboarding.

An example:

curl -X GET -H 'x-api-key: YOUR API KEY HERE' https://api.aphex.co/taskEvents

💡 Make sure you use HTTPS and not HTTP - our API rejects requests made over HTTP, since this sends your API Key over the internet in plain text.

Paginating Queries

To fetch the events since you last called we support the following query parameter:

  • startAfter : The most recent eventId from the events you've received.

    • For subsequent calls, this value can also be found on the nextStartAfter property at the root of the previous response

    • Calls that omit this parameter will return from the Organisation's first event

An example:

curl -X GET -H 'x-api-key: YOUR API KEY HERE' https://api.aphex.co/taskEvents?startAfter=57e4ae861c6b3

Page Limiting

To control the number of events returned you can optionally provide the following parameter:

  • pageSize : A number to represent the max number of events to be returned by the query

    • API calls omitting this parameter will default to a pageSize of 2000.

An example:

curl -X GET -H 'x-api-key: YOUR API KEY HERE' https://api.aphex.co/taskEvents?startAfter=57e4ae861c6b3&pageSize=2000

API Response

The response from the API is a chronological list of events.

There are 3 event types:

  1. TaskCreated : Triggered when a user creates a task. Contains the created task.

  2. TaskUpdated : Triggered when a user updates a task, attaches a delay or updates the resource allocation. Contains the full task.

  3. TaskDeleted : Triggered when a user deletes a task. Contains the id of the deleted task.

Task Created

Any task created will return an event payload with same attributes and order as below.

{"data": [      
{"apiVersion": "v1",
"createdAt": 1614587767389,
"eventId": "FO8097npw2KzZaFoya1O",        
"task": {
"calendar": "Five Day",          
"duration": 1,          
"end": 1614297600000,          
"externalId": "",          
"id": "6LFkmZqBmdA4oByyLP2N",          
"labourResources": {                                  
"Carpenters": 4,                              
},          
"location": "",          
"materialResources": {                                  
"Concrete Panels": 24,
},          
"name": "New Task",          
"ownerEmail": "e.williams@aphex.co",          
"ownerName": "Elliot Williams",          
"packageId": "2349mgeg43ksgmerer",          
"parentId": "",          
"plantResources": {                                  
"100T Excavator": 2,                              
},          
"projectExternalId": "234mfksd433m45ks",          
"projectId": "U2qmd9CVWG0k5EvFxlp9",          
"projectName": "Aphex Fire",          
"shift": "day"          
"start": 1614211200000,          
"statuses": [                        
{                            
date: 1614902400000,                            
type: "onSchedule"                            
name: "On Schedule",                            
value: -2,                            
addedBy: "e.musk@tesla.com",                            
createdAt: 23423423523,                        
},                        
{                               
date: 1614905300000,                            
type: "delay",                            
name: "Insufficient Resources",                            
category: "Resources",                            
value: 2,                            
addedBy: "e.musk@tesla.com",                            
createdAt: 23423423523,                        
}                     
],          
"subcontractor": "",          
"successors": [fasdwr4gen2nbReyLP2N],          
"wbsPath": "",        
},        
"type": "TaskCreated"      
}, // ...    
],    
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",  
}

Task Updated

Any task updated will return an event payload with same attributes and order as below.

{    "data": 
[      
{"apiVersion": "v1",
"createdAt": 1614587767389,
"eventId": "FO8097npw2KzZaFoya1O",        
"task": {
"calendar": "Five Day",          
"duration": 1,          
"end": 1614297600000,          
"externalId": "",          
"id": "6LFkmZqBmdA4oByyLP2N",          
"labourResources": {                                  
"Carpenters": 4,                              
},          
"location": "",          
"materialResources": {                                  
"Concrete Panels": 24,
},          
"name": "New Task",          
"ownerEmail": "e.williams@aphex.co",          
"ownerName": "Elliot Williams",          
"packageId": "2349mgeg43ksgmerer",          
"parentId": "",          
"plantResources": {                                  
"100T Excavator": 2,                              
},          
"projectExternalId": "234mfksd433m45ks",          
"projectId": "U2qmd9CVWG0k5EvFxlp9",          
"projectName": "Aphex Fire",          
"shift": "day"          
"start": 1614211200000,          
"statuses": [                        
{                            
date: 1614902400000,                            
type: "onSchedule"                            
name: "On Schedule",                            
value: -2,                            
addedBy: "e.musk@tesla.com",                            
createdAt: 23423423523,                        
},                        
{                               
date: 1614905300000,                            
type: "delay",                            
name: "Insufficient Resources",                            
category: "Resources",                            
value: 2,                            
addedBy: "e.musk@tesla.com",                            
createdAt: 23423423523,                        
}                     
],          
"subcontractor": "",          
"successors": [fasdwr4gen2nbReyLP2N],          
"wbsPath": "",        
},        
"type": "TaskUpdated"      
}, // ...    
],    
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",  
}

Task Deleted

Any task deleted will return an event payload with same attributes and order as below.

{"data": [   
{      
"apiVersion": "v1",      
"createdAt": 1614587776549,      
"eventId": "HLoT3X3nyCAbGFDdcXdQ",      
"task": { "id": "8xH9q2IptPRYnYDMjc3J" },      
"type": "TaskDeleted"    
},  
],  
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",}

Statuses

In Aphex, status is recorded as a collection of events that are in turn attached to tasks. Status events record the interactions of the team as they update and adjust their committed plans and can reflect positive or negative status events.

Status events are attached to tasks under the statuses tag and have the following attributes;

  1. date : The date that the status event is attached to in Unix Epoch time format

  2. type : The Type of Status Event;

    • delay : A delay has been logged on this task or the task has been extended in duration

    • shortened : The task has reduced in duration

    • completed : The task is completed

    • onSchedule : The task is confirmed as on schedule

    • completedEarly : The task was completed early than planned

  3. name : The display name of the event (either a display format for a positive event such as "On Schedule" or the delay reason for a negative event such as "Awaiting Access" for an event type delay)

  4. value : The value or quantum of the status event. This indicates the impact of the change to the completion date of the task. A positive value indicates a delay and a negative value indicates an improvement.

  5. category : The Delay Category for the Delay Reason contained in the name. If the event is not a delay, this will be blank. The Delay Category will represent the current category assigned to the Delay Reason i.e. if Delay Reason "Awaiting Access" was changed to "Access" Delay Category then future delay events will contain the new category value whilst previous events will not be retriggered (in order to avoid excessive noise in the API). You can chose to look for these changes in order to update your reference tables or simply store them as they are.

  6. addedBy : The User that generated the status event (by email)

  7. createdAt : The date that the status event is created in Unix Epoch time format

API Limits

We place limits on our API to ensure its availability and responsiveness. The limits are;

  • Responses have a size limit of 32Mb

  • Organisations have a daily limit of 20,000 task events per day

We recommend using the default page size of 2000 as a maximum to ensure sufficient head room for the response size limit. If you find this limit restrictive please contact us at hello@aphex.co.

HTTP Response Codes

  • 200 OK - your data will be in the body of the response

  • 204 No Data - your request returned no data

  • 400 Bad Request - double check your query parameters

  • 401 Unauthorized - double check your API key is included in the x-api-key header

  • 403 Forbidden - ensure you are making a GET request

  • 503 Service Unavailable - Likely you've breached the daily organisation limit. Don't worry you can call tomorrow passing the most recent startAfter you've received to date.

Reach out to hello@aphex.co if you need any assistance or have other ways you would like to access your data.

Did this answer your question?