Jobs

The Jobs API allows you to export large sets of analysis data asynchronously and download the results any time within 24 hours of the initial request. This is useful for protection from long-running requests that may be impacted by unreliable networks.


Base Route	/v1/jobs
Endpoints	GET /v1/jobs /v1/jobs/:id /v1/jobs/:id/download POST /v1/jobs DELETE /v1/jobs/:id
Produces	JSON
Pagination	No
Application Permissions Required	"API Access: Create, edit, and delete" and access to view the portfolio data requested.
OAuth Scopes	`PORTFOLIO`

Resource Overview

The Jobs API returns a resource object described by the below attributes, including the status, errors, and any Portfolio API parameters used in the job. Asynchronous job requests can be made for both the Portfolio Query and View APIs.

All attributes will be returned in successful GET & POST responses.

Attribute	Description	Example
`job_type`	Type of job. String. Required.	`"portfolio_view_results"`
`started_at`	The start time of the job in UTC. String. ISO 8601 date format.	`"2020-04-15T21:30:16Z"`
`completed_at`	The completed time of the job in UTC. String. ISO 8601 date format.	`"2020-04-15T21:30:17Z"`
`percent_complete`	Percentage complete. Number.	`1.0`
`status`	The current status of the job. String.	See "Status" below.
`errors`	Errors that occurred running the job. Object.	See "Errors" below.
`parameters`	The parameters required to create the type of job specified. Array of Objects.	See "Parameters" below.

Status

Status	Description
`Queued`	Job has not yet been processed by Addepar servers.
`In Progress - Waiting For Capacity`	Job has been placed back in queue because there is no available capacity.
`In Progress`	Job is currently being processed by Addepar servers.
`Picked Up By Job Runner`	Job has been picked up by the server and is waiting to run.
`Completed`	Job has finished processing. Results can be retrieved from the URL in the Location header.
`Canceled`	Job was canceled by the user.
`Timed Out`	Job results have expired and results have been deleted. Results are deleted 24 hours after a job is created.
`Failed`	Job processing failed due to a server issue. Error details are unavailable.
`Rejected`	Job exceeds the maximum quota of the queue.
`Error Cancelled`	Job canceled due to an error. Details are provided within the error field of the response.
`Cancel Requested`	Job in progress and has received a request to cancel.
`User Cancelled`	Job canceled.

Errors

Parameter	Description	Example
`status`	HTTP status code.	`"400"`
`title`	HTTP status title.	`"Bad Request"`
`detail`	Error details.	`"Invalid portfolio: ENTITY 10"`

Relationships

Relationship	Description
`creator`	The user who created the job.

"relationships":{
  "creator":{
    "links":{
      "self":"/v1/jobs/2/relationships/creator",
      "related":"/v1/jobs/2/creator"
    },
    "data":{
      "type":"users",
      "id":"22"
    }
  }
}

Parameters

Required parameters are specified for portfolio view and query jobs within each description.

Parameter	Description	Example
`portfolio_type`	Required for portfolio view and portfolio query jobs. Supported types: -`ENTITY` -`GROUP` -`FIRM` Also supported for portfolio view jobs: -`FIRM_ACCOUNTS` -`FIRM_UNVERIFIED_ACCOUNTS` The type of portfolio.	`entity`
`portfolio_id`	Required for portfolio view and portfolio query jobs. Portfolio IDs can be configured in Addepar. IDs can represent one entity or a group of entities (query jobs only). If the `portfolio_type` is `FIRM`, the `portfolio_id` must be `1.`	`1`
`view_id`	Required for portfolio view jobs. ID of the portfolio view.	`12`
`output_type`	Required for portfolio view jobs. The output format of the exported result. Supported types: -`CSV` -`TSV` -`XLSX`	`csv`
`start_date`	Required for portfolio view and portfolio query jobs. The start date of the time period of portfolio data. "YYYY-MM-DD."	`2016-01-01`
`end_date`	Required for portfolio view and portfolio query jobs. The end date of the time period of portfolio data. "YYYY-MM-DD."	`2016-02-02`
`columns`	Required for portfolio query jobs. See Attributes to discover supported attributes. See Arguments to discover supported attribute arguments.	`[{"key": "time_weighted_return"}]`
`groupings`	Required for portfolio query jobs. List of grouping attribute keys with optional arguments. Array of Objects. Omitted arguments will use default values. See Attributes to discover supported attributes. See Arguments to discover supported attribute arguments.	`[{"key": "asset_class"}]`
`filters`	Optional for portfolio query jobs. Filters rows from the result. Array of Objects. To learn more, reference the Filter Object within Portfolio Query Jobs.	`[{"attribute": "asset_class", "type": "discrete", "operator": "include", "values": ["Equity", "Fixed Income"]}`
`hide_previous_holdings`	Optional for portfolio query jobs. Set to true to exclude holdings not held at end of current period. Boolean. (default: false)	`false`

Create a Portfolio View Job

Creates an asynchronous job to extract portfolio data for a saved view in Addepar.

📘
Note
Each job has a timeout limit of 4 hours.

POST /v1/jobs

Example:

POST https://examplefirm.com/api/v1/jobs

{
  "data":{
    "type":"jobs",
    "attributes":{
      "job_type":"portfolio_view_results",
      "parameters":{
        "view_id":"2",
        "portfolio_type":"entity",
        "portfolio_id":"22",
        "output_type":"json",
        "start_date":"2011-12-31",
        "end_date":"2013-01-15"
      }
    }
  }
}

HTTP/1.1 202 Accepted

{
  "data":{
    "id":"13",
    "type":"jobs",
    "attributes":{
      "job_type":"portfolio_view_results",
      "parameters":{
        "view_id":2,
        "portfolio_type":"entity",
        "portfolio_id":"22",
        "output_type":"json",
        "start_date":"2011-12-31",
        "end_date":"2013-01-15"
      },
      "status":"Queued"
    },
    "relationships":{
      "creator":{
        "links":{
          "self":"/v1/jobs/13/relationships/creator",
          "related":"/v1/jobs/13/creator"
        },
        "data":{
          "type":"users",
          "id":"44"
        }
      }
    },
    "links":{
      "self":"/v1/jobs/13"
    }
  }
}

Response Codes:

202 Accepted: Success. Returns JSON with created job information.
400 Bad Request: Bad JSON: API format, missing parameters or badly formatted parameters
403 Forbidden: User lacks API permission or has not granted the appropriate scope

Create a Portfolio Query Job

Creates an asynchronous job to extract portfolio data with a query.

POST /v1/jobs

Example:

POST https://examplefirm.com/api/v1/jobs

{
  "data":{
    "type":"job",
    "attributes":{
      "job_type":"PORTFOLIO_QUERY",
      "parameters":{
        "columns":[
          {
            "key":"value"
          },
          {
            "key":"value",
            "arguments":{
              "time_point":"2018-12-31"
            }
          },
          {
            "key":"time_weighted_return",
            "arguments":{
              "period":"2019-12-31 to 2020-03-31"
            }
          }
        ],
        "groupings":[
          {
            "key":"asset_class"
          }
        ],
        "filters":[
          {
            "attribute":"asset_class",
            "type":"discrete",
            "operator":"include",
            "values":[
              "Equity",
              "Fixed Income"
            ]
          }
        ],
        "portfolio_type":"entity",
        "portfolio_id":[
          22
        ],
        "start_date":"2020-02-18",
        "end_date":"2020-03-18"
      }
    }
  }
}

HTTP/1.1 202 Accepted

{
  "data": {
    "id": "7",
    "type": "jobs",
    "attributes": {
      "job_type": "PORTFOLIO_QUERY",
      "parameters": {
        "columns": [{
            "key": "value",
            "arguments": {}
          },
          {
            "key": "value",
            "arguments": {
              "time_point": "2018-12-31"
            }
          },
          {
            "key": "time_weighted_return",
            "arguments": {
              "period": "2019-12-31 to 2020-03-31"
            }
          }
        ],
        "groupings": [{
          "key": "asset_class",
          "arguments": {}
        }],
        "filters": [{
          "attribute": {
            "key": "asset_class",
            "arguments": {}
          },
          "type": "discrete",
          "operator": "include",
          "values": [
            "Equity",
            "Fixed Income"
          ]
        }],
        "portfolio_type": "entity",
        "portfolio_id": [
          22
        ],
        "start_date": "2020-02-18",
        "end_date": "2020-03-18",
        "hide_previous_holdings": false
      },
      "percent_complete": 0.0,
      "status": "Queued"
    },
    "relationships": {
      "creator": {
        "links": {
          "self": "/v1/jobs/7/relationships/creator",
          "related": "/v1/jobs/7/creator"
        },
        "data": {
          "type": "users",
          "id": "22"
        }
      }
    },
    "links": {
      "self": "/v1/jobs/7"
    }
  },
  "included": []
}

Response Codes:

202 Accepted: Success. Returns JSON with created job information.
400 Bad Request: Bad JSON: API format, missing or badly formatted parameters
403 Forbidden: User lacks API permission or has not granted the appropriate scope

Check the Status of a Job

Retrieves the status and parameters for a specific job.

GET /v1/jobs/:id

Example:

GET https://examplefirm.com/api/v1/jobs/13

HTTP/1.1 200

{
  "data":{
    "id":"13",
    "type":"jobs",
    "attributes":{
      "job_type":"portfolio_view_results",
      "completed_at":"2020-04-03T15:15:28Z",
      "started_at":"2020-04-03T15:15:28Z",
      "parameters":{
        "view_id":"2",
        "portfolio_type":"entity",
        "portfolio_id":"22",
        "output_type":"json",
        "start_date":"2011-12-31",
        "end_date":"2013-01-15"
      },
      "status":"Completed"
    },
    "relationships":{
      "creator":{
        "links":{
          "self":"/v1/jobs/13/relationships/creator",
          "related":"/v1/jobs/13/creator"
        },
        "data":{
          "type":"users",
          "id":"44"
        }
      }
    },
    "links":{
      "self":"/v1/jobs/13"
    }
  }
}

Response Codes:

200 OK: Success
404 Not Found: Unable to locate the job with the given id, or user does not have permission to view the given job
403 Forbidden: User lacks API permission or has not granted the appropriate scope

Download the Results of a Job

Returns the results of the given job.

📘
Note
Job results are deleted 24 hours after a job is created.

GET /v1/jobs/:id/download

Example:

GET https://examplefirm.com/api/v1/jobs/13/download

HTTP/1.1 200

Content-Disposition: attachment; file name="portfolio_data.json"
Content-Type: application/vnd.api+json

<DOWNLOAD_CONTENT>

Response Codes:

200 OK: Success. Returns a JSON, CSV, TSV or XLSX as requested.
303 See Other: Completed asynchronous job. Follow the link in the "Location" header to retrieve the results.
404 Not Found: Job has not completed or does not return any results
410 Gone: Results have expired.

Check the Status of All Jobs

Retrieves the status and parameters of all jobs.

GET /v1/jobs

Example:

GET https://examplefirm.com/api/v1/jobs

HTTP/1.1 200

{
  "data":[
    {
      "id":"13",
      "type":"jobs",
      "attributes":{
        "job_type":"portfolio_view_results",
        "completed_at":"2020-04-02T21:49:16Z",
        "started_at":"2020-04-02T21:4915Z",
        "parameters":{
          "view_id":"2",
          "portfolio_type":"entity",
          "portfolio_id":"22",
          "output_type":"json",
          "start_date":"2011-12-31",
          "end_date":"2013-01-15"
        },
        "status":"Completed"
      },
      "links":{
        "self":"/v1/jobs/13"
      }
    },
    {
      "id":"14",
      "type":"jobs",
      "attributes":{
        "job_type":"portfolio_view_results",
        "completed_at":"2020-04-03T15:15:28Z",
        "started_at":"2020-04-03T15:15:28Z",
        "parameters":{
          "view_id":"3",
          "portfolio_type":"entity",
          "portfolio_id":"10",
          "output_type":"csv",
          "start_date":"2016-01-01",
          "end_date":"2016-01-02"
        },
        "errors":[
          {
            "status":"400",
            "title":"Bad Request",
            "detail":"Invalid portfolio: ENTITY 10"
          }
        ],
        "status":"Error"
      },
      "links":{
        "self":"/v1/jobs/14"
      }
    }
  ],
  "links":{
    "next":null
  }
}

Response Codes:

200 OK: Success
403 Forbidden: User lacks API permission or has not granted the appropriate scope

Cancel a job

Cancel a job that is has yet to start, is running, or already completed.

DELETE /v1/jobs/:id

When canceling a job with the status:

waiting_for_capacity the job will not run. Status change: user_canceled.
in_progress a request to cancel is submitted. Status change:cancel_requested, then user_canceled.
completed the results are archived. Status change: user_canceled.

Example

DELETE https://examplefirm.com/api/v1/jobs/:1234

204 No Content

Response Codes:

204 No Content: Success. Cancel request submitted.
404 Not Found: Cannot locate the job with the given ID, or you don't have permission to view the job.

Jobs

Resource Overview

Relationships

Parameters

Create a Portfolio View Job

📘
Note

Create a Portfolio Query Job

Check the Status of a Job

Download the Results of a Job

📘
Note

Check the Status of All Jobs

Cancel a job

Resource Overview

Relationships

Parameters

Create a Portfolio View Job

📘Note

Create a Portfolio Query Job

Check the Status of a Job

Download the Results of a Job

📘Note

Check the Status of All Jobs

Cancel a job

📘
Note

📘
Note