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 /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" |
job_type | Specifies whether the report job was scheduled or ad hoc. | "SCHEDULED" or "AD_HOC" |
generated_portfolios | An array of objects providing information of successfully generated portfolios. Includes portfolio type, portfolio id, portfolio name, file id, and publish to portal status. | "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" |
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 |
filter[xxx][entityId] | Returns the jobs for this entity's portfolio. | [entityId]=12345 |
filter[xxx][groupId] | Returns the jobs for this group's portfolio. | [groupId]=54789 |
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",
"job_type": "AD_HOC",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 101,
"has_been_published": false
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102,
"has_been_published": false
}
],
"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",
"job_type": "AD_HOC",
"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"
}
}
Example with various 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",
"job_type": "AD_HOC",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 101,
"has_been_published": false
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102,
"has_been_published": false
}
],
"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": "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"
}
}
}
}
}
Example with portfolio filter parameter
GET /v1/generated_reports/?page[size]=50&page[number]=0&filter[entityId]=1234
{
"data": [
{
"type": "generated_reports",
"id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
"attributes": {
"report_id": 42,
"report_name": "Quarterly Performance Report",
"status": "FINISHED",
"started_at": "2021-02-14T10:15:30.00Z",
"completed_at": "2021-02-14T14:25:45.00Z",
"job_type": "AD_HOC",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 1234,
"portfolio_name": "Tony Stark",
"file_id": 101,
"has_been_published": false
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102,
"has_been_published": false
}
],
"failed_portfolios": []
},
"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",
"job_type": "AD_HOC",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 1234,
"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&filter[entityId]=1234"
}
}
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",
"job_type": "AD_HOC",
"generated_portfolios": [
{
"portfolio_type": "entity",
"portfolio_id": 21,
"portfolio_name": "Tony Stark",
"file_id": 101,
"has_been_published": false
},
{
"portfolio_type": "group",
"portfolio_id": 31,
"portfolio_name": "Avengers",
"file_id": 102,
"has_been_published": false
}
],
"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": "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"
}
}
}
}
}
Responses
200 OK
: Success400 Bad Request
:include
query parameter not allowed403 Forbidden
: Lacking admin permission404 Not Found
: Nonexistent/non-permissioned generated report ID or the report is currently being generated
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 12 days ago