Addepar Developer Portal

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

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"

Job is currently being processed by Addepar servers.

"Completed"

Job has finished processing. Results can be retrieved from the URL in the Location header.

"Timed Out"

Job results have expired and results have been deleted. Results are deleted 24 hours after a job is created.

"Error"

Job processing failed due to an error. Details are provided within the error field of the response.

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

For portfolio_view_results jobs, all Portfolio View API parameters are supported. Reference the Portfolio View API documentation.

Example

"parameters":{
  "view_id":2,
  "portfolio_type":"entity",
  "portfolio_id":22,
  "output_type":"csv",
  "start_date":"2016-01-01",
  "end_date":"2016-02-02"
}

For portfolio_query jobs, all Portfolio Query API parameters are supported. Reference the Portfolio Query API documentation.

Example

"parameters":{
  "columns":[
    {
      "key":"value"
    },
    {
      "key":"time_weighted_return"
    }
  ],
  "groupings":[
    {
      "key":"asset_class"
    }
  ],
  "portfolio_type":"FIRM",
  "portfolio_id":1,
  "start_date":"2018-06-30",
  "end_date":"2020-07-01"
}

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 201 Created

{
  "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:

  • 201 OK: Success. Returns JSON with 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 201 Created

{
  "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:

  • 201 OK: Success
  • 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

Updated 5 months ago

What's Next

Time to try it out for yourself:

API Explorer: Jobs

Jobs

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.