Docs

Batched Jobs (Beta)

Suggest Edits

Configure portfolio view or query requests in batch mode for faster results.

  1. Set up a view or query similarly to usage of the standard Jobs API
  2. Add the header --header 'Addepar-Compute-Type': “BATCH” to the request
  3. Run the request.
  4. Download the results.

How it works
A single job request is split into many requests that run in parallel. When the results are ready they are computed back into a single source.

📘

Beta Feature

Batched jobs and all features described herein are in the Addepar Beta Program. All beta features described herein are provided “as is” and “as available” with no warranty or guarantee of functionality and may be modified or removed at any time by Addepar.

Step 1: Setting up a view or query payload

Set up a view following the batching guidelines below and get the view ID from the URL. You can also set up a portfolio query job following the same guidelines.

Example: Get the View ID from the URL in Addepar

3606

You can see that the view was grouped by legal entity for faster results.

Example: Get the View ID via API

GET  https://examplefirm.addepar.com/api/v1/portfolio/views

200 OK: Success

{
  "data": [
    {
      "id": "19",
      "type": "portfolio_views",
      "attributes": {
        "share_type": "PERSONAL",
        "display_name": "AdvancedTable"
      },
      "links": {
        "self": "/v1/portfolio_views/19"
      }
    },
    {
      "id": "74894",
      "type": "portfolio_views",
      "attributes": {
        "share_type": "FIRM",
        "display_name": "owner1"
      },
      "links": {
        "self": "/v1/portfolio_views/2"
      }
    },
    {
      "id": "4",
      "type": "portfolio_views",
      "attributes": {
        "share_type": "PORTAL",
        "display_name": "TOTAL RETURN VIEW"
      },
      "links": {
        "self": "/v1/portfolio_views/4"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

Step 2: Prepare the request for the Jobs API

Add the header Addepar-Compute-Type : BATCH to your request.

--header 'Addepar-Firm: 1' 
--header 'Authorization: Basic YmZiYWFlZjUtZmYwMC11MWZkLWE0Y2YtYjg4MjcxNmQzZGVjOjlPdU40d3RRbz'
--header 'accept: application/vnd.api+json' \
--header 'Addepar-Compute-Type': “BATCH”

Step 3: Run the request

Run your request using the Jobs API.

POST /v1/jobs

Example:

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

{
  "data":{
    "type":"jobs",
    "attributes":{
      "job_type":"portfolio_view_results",
      "parameters":{
        "view_id":"74894",
        "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":"7",
    "type":"jobs",
    "attributes":{
      "job_type":"portfolio_view_results",
      "parameters":{
        "view_id":74894,
        "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/7"
    }
  }
}

Response codes:

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

Step 4: Download the results

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/7/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

📘

Note

If the view contains unsupported attributes for Batch, the status of the job will become "Error". The status response will also contain the reasons why it is unsupported.

See the Jobs API for how to check the status of a job.

Guidelines

To make batched jobs run as fast as possible, minimize the number of positions in a single row within your view. For example, if you group by Asset Class or Country, there will be many positions in a single row. Instead, group by position, holding account, or top level owner.

A view or query cannot include the following settings:

  • Summary data applied to a table row
  • Advanced tables or pivot tables

Supported Attributes

There are 3 tiers of support for attributes:

  1. Not Supported - cannot be used in any batched request
  2. Fully Supported
  3. Partially Supported - when used as a column, its value will not be computed for the total row, and for any other row that is too large.

Unsupported Attributes:

The following attributes are currently not supported. Note: this list is not exhaustive.

Benchmark
Calendar Period Grouping
* Group
* Group Type Key
Performance Contribution
Target Allocation
Target Allocation %
Target Allocation Range
Time Period Grouping
# Transaction Based Attributes
  • Group and Group Type Key are only not supported if over 500k groups are currently enabled

Fully Supported Attributes:

The following attributes are currently fully supported. Note: this list is not exhaustive.

Accrued Income  
Archived  
Change In Accrued Income  
Creation Date  
Date Format  
Digital Asset Symbol  
Disable Lookthrough  
Display Name  
Entity ID  
External ID  
Group ID  
Income/Expenses  
Model Type  
Net Cash Flow  
Net Gain/Loss  
Original Name 
Percent of Portfolio 
Problem Count  
Reference Currency  
Rollup  
Total Return  
Underlying Type  
Value  
Wrapper status

Partially Supported Attributes

These attributes can generally be used as a Grouping or a Filter, but are not supported as a Column IF they are used on a large grouping row like a Total Row or a top level 'True/False' row.

Only certain attributes are compatible with the Total Row display setting. If a view is composed of the attributes below, the total row setting can be enabled and will properly aggregate any values. Otherwise, the request will be rejected.

Additionally, if any individual rows in a batched job exceed a certain size threshold of positions within the row, the result returned will be Coordinator Disabled, indicating the aggregation was too expensive to generate and cannot be partitioned.

A chart is similar to a grouping row, in that a chart with no groupings is equivalent to a Total Row, and individual bars/lines/pie sections of a chart are represented as groupings. These same rules apply to both charts and tables.

If you need to disable the Total Row display setting, this can be done in the original view by unchecking this option in View Settings > General Settings > Show total row, or set disable_total_row = true within the job payload.

The following attributes are currently partially supported. Note: this list is not exhaustive.

IRR
TWR

Updated 4 days ago