Generated Reports
The Generated Reports API provides access to generated report objects representing the metadata associated with a single completed run of a report generation job.
A report generation job is initiated from the Addepar web application or the Report Generation API and generates report PDFs for the portfolios associated with a given report.
Base route | /v1/generated_reports |
Endpoints | GET /v1/generated_reports/:id /v1/generated_reports/:id/creator /v1/generated_reports/:id/zipped_file /v1/generated_reports/:id/zipped_file/download |
Produces | JSON |
Pagination | Yes |
OAuth Scopes | FILES for all except /v1/generated_reports/:id/creator, which requires FILES and USERS |
Application Permissions Required | "Access to all tools and portfolios." |
Resource Overview
All attributes will be returned in successful GET responses.
Attribute | Type | Example |
---|---|---|
report_id | The unique id of the report for which the report generation job was run. | 46 |
report_name | The name of the report for which the report generation job was run. | "Quarterly Performance Report" |
status | The status of the completed job. Either, FINISHED , ERROR , or CANCELED .ERROR is due to system failure. CANCELED is an action taken by a user. Both these statuses might still result in one or more successful portfolios. | "ERROR" |
started_at | String representing the time instant in UTC at which this report generation job was started. | "2021-02-14T10:15:30.00Z" |
completed_at | String representing the time instant in UTC at which this report generation job finished. | "2021-02-14T14:25:45.00Z" |
generated_portfolios | An array of objects providing information of successfully generated portfolios. Includes portfolio type, portfolio id, portfolio name, and file id. | "generated_portfolios" |
portfolio_type | One of entity or group. | "entity" |
portfolio_id | Unique id of the portfolio. | 21 |
portfolio_name | Name of the portfolio. | "Tony Stark" |
file_id | Unique id of the generated file. It can be used to download the actual binary file from GET /v1/files/:id/download . | 101 |
failed_portfolios | An array of objects providing information of failed portfolios during report generation. Includes portfolio type, portfolio ID, and portfolio name. | "failed_portfolios" |
portfolio_type | One of entity or group. | "entity" |
Relationships | |
---|---|
creator | The user who created the report generation job that generated the associated files. |
Optional Parameters
Parameter | Description | Example |
---|---|---|
filter[completed_after]=YYYY-MM-DDTHH:MM:SSZ | Returns jobs run after this date. The timestamp is in UTC. | [completed_after]=2021-05-14T12:03:39Z |
filter[completed_before]=YYYY-MM-DDTHH:MM:SSZ | Returns jobs run before this date. The timestamp is in UTC. | [completed_before]=2021-05-14T12:03:39Z |
filter[status]=[FINISHED, ERROR, CANCELED] | Returns jobs by status. Filter by one or more of the following:FINISHED - done runningERROR - report ended in an error with one or more jobs failingCANCELED - A user stopped the job while it was in progress | [status]=FINISHED,ERROR |
Get all generated reports
Retrieves all generated reports that a user is authenticated to view, sorted in reverse chronological order of completion time.
GET /v1/generated_reports/
GET https://examplefirm.addepar.com/api/v1/generated_reports
200 OK: Success
{
"data": [
{
"type": "generated_reports",
"id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
"attributes": {
"report_id": 42,
"report_name": "Quarterly Performance Report",
"status": "ERROR",
"started_at": "2021-02-14T10:15:30.00Z",
"completed_at": "2021-02-14T14:25:45.00Z",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 101
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102
}
],
"failed_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 22,
"portfolio_name": "Thanos"
},
{
"portfolio_type": "group",
"portfolio_id": 32,
"portfolio_name": "Chitauri"
}
]
},
"relationships": {
"creator": {
"links": {
"self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
"related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
},
"data": [
{
"type": "users",
"id": "84"
}
]
}
}
},
{
"type": "generated_reports",
"id": "ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN",
"attributes": {
"report_id": 43,
"report_name": "Market Benchmark Report",
"status": "FINISHED",
"started_at": "2021-02-14T11:15:30.00Z",
"completed_at": "2021-02-14T13:25:45.00Z",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 103
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 104
}
],
"failed_portfolios": []
},
"relationships": {
"creator": {
"links": {
"self": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
"related": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
},
"data": [
{
"type": "users",
"id": "84"
}
]
}
}
}
],
"included": []
}
Example with parameters
GET /v1/generated_reports/?page[size]=50&page[number]=0&filter[status]=FINISHED,ERROR&filter[completed_before]=2021-05-14T12:03:39Z
200 OK: Success
{
"data": [
{
"type": "generated_reports",
"id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
"attributes": {
"report_id": 42,
"report_name": "Quarterly Performance Report",
"status": "ERROR",
"started_at": "2021-02-14T10:15:30.00Z",
"completed_at": "2021-02-14T14:25:45.00Z",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 101
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102
}
],
"failed_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 22,
"portfolio_name": "Thanos"
},
{
"portfolio_type": "group",
"portfolio_id": 32,
"portfolio_name": "Chitauri"
}
]
},
"relationships": {
"creator": {
"data": {
"type": "users",
"id": "84"
},
"links": {
"self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
"related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
}
},
"zipped_file": {
"data": {
"type": "archive/files",
"id": "61"
},
"links": {
"self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/zipped_file",
"related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/zipped_file"
}
}
}
},
{
"type": "generated_reports",
"id": "ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN",
"attributes": {
"report_id": 43,
"report_name": "Market Benchmark Report",
"status": "FINISHED",
"started_at": "2021-02-14T11:15:30.00Z",
"completed_at": "2021-02-14T13:25:45.00Z",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 103
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 104
}
],
"failed_portfolios": []
},
"relationships": {
"creator": {
"data": {
"type": "users",
"id": "84"
},
"links": {
"self": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
"related": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
}
},
"zipped_file": {
"data": {
"type": "archive/files",
"id": "62"
},
"links": {
"self": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/zipped_file",
"related": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/zipped_file"
}
}
}
}
],
"included": [],
"links": {
"next": "/v1/generated_reports?page[number]=1&page[size]=50"
}
}
Responses
200 OK
: Success400 Bad Request
:include
query parameter not allowed403 Forbidden
: Lacking admin permission
Get generated report by job ID
Retrieves a generated report by job ID within the authenticated user's firm.
GET /v1/generated_reports/:id
GET https://examplefirm.addepar.com/v1/generated_reports/42
200 OK: Success
{
"data": {
"type": "generated_reports",
"id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
"attributes": {
"report_id": 42,
"report_name": "Quarterly Performance Report",
"status": "ERROR",
"started_at": "2021-02-14T10:15:30.00Z",
"completed_at": "2021-02-14T14:25:45.00Z",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 101
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102
}
],
"failed_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 22,
"portfolio_name": "Thanos"
},
{
"portfolio_type": "group",
"portfolio_id": 32,
"portfolio_name": "Chitauri"
}
]
},
"relationships": {
"creator": {
"links": {
"self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
"related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
},
"data": [
{
"type": "users",
"id": "84"
}
]
}
}
},
"included": []
}
Responses
200 OK
: Success400 Bad Request
:include
query parameter not allowed403 Forbidden
: Lacking admin permission404 Not Found
: Nonexistent/non-permissioned generated report ID
Get report creator by ID
Retrieves all information related to the user who generated the reports for the job id.
GET /v1/generated_reports/:id/creator
GET https://examplefirm.addepar.com/v1/generated_reports/42/creator
200 OK: Success
{
"data": {
"id": "84",
"type": "users",
"attributes": {
"first_name": "Nick",
"last_name": "Fury",
"two_factor_auth_enabled": false,
"admin_access": true,
"all_data_access": true,
"login_method": "email_password",
"email": "[email protected]"
},
"relationships": {
"permissioned_entities": {
"links": {
"self": "/v1/users/84/relationships/permissioned_entities",
"related": "/v1/users/84/permissioned_entities"
},
"data": []
},
"assigned_role": {
"data": null
},
"permissioned_groups": {
"links": {
"self": "/v1/users/84/relationships/permissioned_groups",
"related": "/v1/users/84/permissioned_groups"
},
"data": []
}
},
"links": {
"self": "/v1/users/84"
}
},
"included": []
}
Responses
200 OK
: Success400 Bad Request
: Invalid relationship queried403 Forbidden
: Lacking admin permission404 Not Found
Get reports in a zipped file by ID
Retrieves all information related to the zipped file generated for the job ID.
GET /v1/generated_reports/:id/zipped_file
GET https://examplefirm.addepar.com/v1/generated_reports/61/zipped_file
200 OK: Success
{
"data": {
"id": "61",
"type": "files",
"attributes": {
"content_type": "application/zip",
"bytes": 36599,
"name": "Quarterly Performance Report at 05-15-2021.zip",
"created_at": "2021-05-17T12:34:38Z"
},
"relationships": {
"associated_groups": {
"links": {
"self": "/v1/files/61/relationships/associated_groups",
"related": "/v1/files/61/associated_groups"
},
"data": []
},
"associated_entities": {
"links": {
"self": "/v1/files/61/relationships/associated_entities",
"related": "/v1/files/61/associated_entities"
},
"data": []
}
},
"links": {
"self": "/v1/files/61"
}
},
"included": []
}
Responses
200 OK
: Success400 Bad Request
: Invalid relationship queried403 Forbidden
: Lacking admin permission404 Not Found
Download reports in a zipped file by ID
Returns a binary zipped file.
GET /v1/generated_reports/:id/zipped_file/download
GET https://examplefirm.addepar.com/v1/generated_reports/61/zipped_file
HTTP/1.1 200
Content-DispositionL attachment; filename="Quarterly Performance Report at 05-15-2021.zip"
Content-Type: application/binary
<RAW_FILE_DATA>
Responses
200 OK
: Success403 Forbidden
: Lacking admin permission404 Not Found
See more types of file downloads
Updated 5 days ago