Docs

Batched Jobs (Beta)

Suggest Edits

Configure portfolio view or query requests to batch them 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

📘

You can also check the status of a job and delete a job. See the Jobs API for more information.

Guidelines

To get the most out of batched jobs, 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:

  • Filter by groupings or rank (You can filter by range and position)
  • Summary data applied to a table row
  • Advanced tables or pivot tables

Supported Attributes

Support for attributes is within batched mode is determined by whether or not there is support for aggregating specific performance metrics, or if additional data loading stages are required to generate a per-row output.

There are 3 tiers of support for attributes:

  1. Not Supported - cannot be used in any batched request
  2. Fully Supported
  3. Partially Supported - supported for filters/groupings, cannot be used as a column for a row exceeding a certain size (not supported for Total Row)

Unsupported Attributes:

These attributes can neither be used as a Grouping, Filter, or a Column.

# All Addepar Billing Attributes
Benchmark
Benchmark Return %
Calendar Period Grouping
* Group
* Group Type Key
* Percent of Portfolio
Performance Contribution
Target Allocation
Target Allocation %
Target Allocation Range
Time Period Grouping
  • Group and Group Type Key are only not supported if over 500k groups are currently enabled
  • Percent of Portfolio is not supported within a custom attribute, a time series, with a dynamic time period (performance dates or since inception), or if using the settings Percent of Total Portfolio, Percent of Visible Portfolio, Percent of Current Grouping.

Fully Supported Attributes:

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  
Problem Count  
Reference Currency  
Rollup  
Total Return  
Underlying Dype  
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 comprised of the attributes below, the total row setting can be enabled and will properly aggregate any values. Otherwise, the request will be rejected.

All attributes not specifically stated in the above sections are otherwise partially supported, including custom attributes, IRR, and TWR.

Additionally, if any individual rows in a batched job exceed a certain size threshold of positions within the row, the result returned will beCoordinator 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 = truewithin the job payload.

Updated 1 day ago