Jobs

The Jobs API exports large analysis datasets asynchronously. Create a job to run a portfolio view or query in the background, poll for completion, and download results as JSON within 24 hours. Use Jobs when your request covers more than 100 entities, spans large date ranges, or would exceed the 30-second synchronous timeout.

Overview


Base Route	`/v1/jobs`
Endpoints	GET `/v1/jobs` `/v1/jobs/:id` `/v1/jobs/:id/download` POST `/v1/jobs` DELETE `/v1/jobs/:id`
Produces	JSON
Pagination	Yes (default: 25 per page)
Application Permissions	"API Access: Create, edit, and delete" and access to view the requested portfolio data
OAuth Scopes	`PORTFOLIO`

Resource attributes

Attribute	Type	Required	Constraints	Description	Example
`job_type`	string	Yes	Enum: `portfolio_view_results`, `portfolio_query_results`	The type of analysis to run	`"portfolio_view_results"`
`status`	string	No (read-only)	Enum: see Status lifecycle below	Current state of the job	`"Completed"`
`percent_complete`	number	No (read-only)	0.0 to 1.0	Progress indicator	`1.0`
`started_at`	string	No (read-only)	ISO 8601 UTC	When processing began	`"2020-04-15T21:30:16Z"`
`completed_at`	string	No (read-only)	ISO 8601 UTC	When processing finished	`"2020-04-15T21:30:17Z"`
`errors`	array	No (read-only)	Array of error objects with `status`, `title`, `detail`	Errors encountered during processing	See error response examples
`parameters`	object	Yes	Structure varies by `job_type`; see Parameters below	The configuration for the analysis run	See endpoint examples

Parameters

Required parameters depend on the job type.

Portfolio view job parameters

Parameter	Type	Required	Constraints	Description	Example
`portfolio_type`	string	Yes	Enum: `ENTITY`, `ENTITY_FUNDS`, `GROUP`, `GROUP_FUNDS`, `FIRM`, `FIRM_ACCOUNTS`, `FIRM_CLIENTS`, `FIRM_HOUSEHOLDS`, `FIRM_UNVERIFIED_ACCOUNTS`	The scope of the portfolio to analyze	`"ENTITY"`
`portfolio_id`	string	Yes	Must be a valid entity or group ID; must be `1` when `portfolio_type` is `FIRM`	The portfolio to analyze	`"22"`
`view_id`	string	Yes	Must reference an existing saved view	The portfolio view to render	`"12"`
`output_type`	string	Yes	Enum: `JSON`, `CSV`, `TSV`, `XLSX`	The format for downloaded results	`"JSON"`
`start_date`	string	Yes	Format: `YYYY-MM-DD`	Start of the analysis period	`"2026-01-01"`
`end_date`	string	Yes	Format: `YYYY-MM-DD`; must be >= `start_date`	End of the analysis period	`"2026-06-30"`

Portfolio query job parameters

Parameter	Type	Required	Constraints	Description	Example
`portfolio_type`	string	Yes	Same enum as view jobs	The scope of the portfolio to analyze	`"ENTITY"`
`portfolio_id`	string	Yes	Same rules as view jobs	The portfolio to analyze	`"22"`
`start_date`	string	Yes	Format: `YYYY-MM-DD`	Start of the analysis period	`"2026-01-01"`
`end_date`	string	Yes	Format: `YYYY-MM-DD`; must be >= `start_date`	End of the analysis period	`"2026-06-30"`
`columns`	array	Yes	Array of objects with `key` (string) and optional `arguments` (object)	The attributes to compute	`[{"key": "value"}]`
`groupings`	array	Yes	Array of objects with `key` (string) and optional `arguments` (object); can be empty	How to group results	`[{"key": "asset_class"}]`
`filters`	array	No	Array of filter objects; see Portfolio Query	Row-level filters	`[{"attribute": "asset_class", "type": "discrete", "operator": "include", "values": ["Equity"]}]`
`hide_previous_holdings`	boolean	No	Default: `false`	Exclude holdings not held at end of period	`false`

Relationships

Relationship	Description	Use when...
`creator`	The user who created the job	You need to identify which user or API client initiated the export

{
  "relationships": {
    "creator": {
      "links": {
        "self": "/v1/jobs/2/relationships/creator",
        "related": "/v1/jobs/2/creator"
      },
      "data": {
        "type": "users",
        "id": "22"
      }
    }
  }
}

Create a portfolio view job

Creates an asynchronous job to export data from a saved portfolio view. Each job has a 4-hour timeout limit.

curl --request POST \
  --url 'https://examplefirm.addepar.com/api/v1/jobs' \
  --header 'Authorization: Basic {base64_encoded_credentials}' \
  --header 'Addepar-Firm: {firm_id}' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Accept: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "jobs",
      "attributes": {
        "job_type": "portfolio_view_results",
        "parameters": {
          "view_id": "2",
          "portfolio_type": "ENTITY",
          "portfolio_id": "22",
          "output_type": "JSON",
          "start_date": "2026-01-01",
          "end_date": "2026-06-30"
        }
      }
    }
  }'

{
  "data": {
    "id": "b6c1b9da-4387-11ef-8636-dd826f8aeed1a",
    "type": "jobs",
    "attributes": {
      "job_type": "portfolio_view_results",
      "parameters": {
        "view_id": 2,
        "portfolio_type": "ENTITY",
        "portfolio_id": "22",
        "output_type": "JSON",
        "start_date": "2026-01-01",
        "end_date": "2026-06-30"
      },
      "status": "Queued",
      "percent_complete": 0.0,
      "started_at": null,
      "completed_at": null,
      "errors": []
    },
    "relationships": {
      "creator": {
        "links": {
          "self": "/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a/relationships/creator",
          "related": "/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a/creator"
        },
        "data": {
          "type": "users",
          "id": "44"
        }
      }
    },
    "links": {
      "self": "/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a"
    }
  }
}

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Missing required parameter: view_id"
    }
  ]
}

Response codes:

202 Accepted -- Job created and queued; use the id from the response to poll status
400 Bad Request -- Missing or invalid parameters; check the detail field for the specific issue
403 Forbidden -- Missing PORTFOLIO OAuth scope or insufficient entity visibility for the requested portfolio

Create a portfolio query job

Creates an asynchronous job to compute custom analytics over portfolio data.

curl --request POST \
  --url 'https://examplefirm.addepar.com/api/v1/jobs' \
  --header 'Authorization: Basic {base64_encoded_credentials}' \
  --header 'Addepar-Firm: {firm_id}' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Accept: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "jobs",
      "attributes": {
        "job_type": "portfolio_query_results",
        "parameters": {
          "portfolio_type": "ENTITY",
          "portfolio_id": "22",
          "start_date": "2026-01-01",
          "end_date": "2026-06-30",
          "columns": [
            {"key": "value"},
            {"key": "time_weighted_return"}
          ],
          "groupings": [
            {"key": "asset_class"}
          ]
        }
      }
    }
  }'

{
  "data": {
    "id": "c7d2e0fb-5498-22fg-9747-ee937g9bffa2b",
    "type": "jobs",
    "attributes": {
      "job_type": "portfolio_query_results",
      "status": "Queued",
      "percent_complete": 0.0
    },
    "links": {
      "self": "/v1/jobs/c7d2e0fb-5498-22fg-9747-ee937g9bffa2b"
    }
  }
}

Response codes:

202 Accepted -- Job created and queued
400 Bad Request -- Invalid columns or groupings structure; check Attributes for valid keys
403 Forbidden -- Missing PORTFOLIO scope or insufficient entity visibility

Get job status

Poll this endpoint to check whether a job has completed. Use the id returned from the create response.

curl --request GET \
  --url 'https://examplefirm.addepar.com/api/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a' \
  --header 'Authorization: Basic {base64_encoded_credentials}' \
  --header 'Addepar-Firm: {firm_id}' \
  --header 'Accept: application/vnd.api+json'

{
  "data": {
    "id": "b6c1b9da-4387-11ef-8636-dd826f8aeed1a",
    "type": "jobs",
    "attributes": {
      "job_type": "portfolio_view_results",
      "status": "Completed",
      "percent_complete": 1.0,
      "started_at": "2026-06-15T14:30:00Z",
      "completed_at": "2026-06-15T14:32:45Z",
      "errors": []
    },
    "links": {
      "self": "/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a"
    }
  }
}

Response codes:

200 OK -- Job details retrieved successfully
403 Forbidden -- Missing permission to view this job
404 Not Found -- Job ID does not exist; verify the ID from the create response

Download results

After a job reaches Completed status, download the results. Results expire 24 hours after job creation.

curl --request GET \
  --url 'https://examplefirm.addepar.com/api/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a/download' \
  --header 'Authorization: Basic {base64_encoded_credentials}' \
  --header 'Addepar-Firm: {firm_id}' \
  --header 'Accept: application/vnd.api+json'

The response body contains the job results in the format specified by output_type (JSON, CSV, TSV, or XLSX).

Response codes:

200 OK -- Results downloaded successfully
404 Not Found -- Results have expired (24-hour window) or job has not completed; re-create the job if expired
403 Forbidden -- Missing permission to download this job's results

List all jobs

Retrieves all jobs for the authenticated user's firm.

curl --request GET \
  --url 'https://examplefirm.addepar.com/api/v1/jobs' \
  --header 'Authorization: Basic {base64_encoded_credentials}' \
  --header 'Addepar-Firm: {firm_id}' \
  --header 'Accept: application/vnd.api+json'

Response codes:

200 OK -- Jobs listed successfully
403 Forbidden -- Missing API access permission

Cancel a job

Cancels a running or queued job. Completed jobs cannot be canceled.

curl --request DELETE \
  --url 'https://examplefirm.addepar.com/api/v1/jobs/b6c1b9da-4387-11ef-8636-dd826f8aeed1a' \
  --header 'Authorization: Basic {base64_encoded_credentials}' \
  --header 'Addepar-Firm: {firm_id}' \
  --header 'Accept: application/vnd.api+json'

Response codes:

202 Accepted -- Cancellation requested; job transitions to Cancel Requested then User Cancelled
403 Forbidden -- Missing permission to cancel this job
404 Not Found -- Job ID does not exist

Status lifecycle

Status	Meaning	Agent action	Typical duration
`Queued`	Waiting for server capacity	Poll after 5s	Seconds to minutes
`Picked Up By Job Runner`	Assigned to a worker	Poll after 5s	Seconds
`In Progress`	Actively computing	Poll after 10s	Minutes to hours
`In Progress - Waiting For Capacity`	Returned to queue due to load	Poll after 30s	Minutes
`Completed`	Results ready for download	Proceed to `/v1/jobs/:id/download`	(terminal)
`Failed`	Server error; no results available	Read `errors` array; re-create the job if transient	(terminal)
`Timed Out`	Results expired after 24 hours	Re-create the job	(terminal)
`Canceled`	User initiated cancellation via API or UI	No action needed	(terminal)
`User Cancelled`	Cancellation confirmed	No action needed	(terminal)
`Cancel Requested`	Cancellation in progress	Wait for transition to `User Cancelled`	Seconds
`Rejected`	Queue quota exceeded	Reduce concurrent jobs or wait for existing jobs to complete, then retry	(terminal)
`Error Cancelled`	System cancelled due to error	Read `errors` array for details	(terminal)

Error recovery

Failure	Symptom	Recovery
Invalid job parameters	`400` with `detail` message on create	Check `job_type` enum value and verify all required parameters for that job type are present
Insufficient permissions	`403` on create	Verify OAuth scope is `PORTFOLIO` and the API user has visibility to the requested portfolio entities
Job stuck in queue	Status unchanged for 15+ minutes	Cancel with DELETE, wait for `User Cancelled`, then re-create
Download returns 404	Job completed but results expired	Results expire 24 hours after creation; re-create the job
Job rejected	Status becomes `Rejected` immediately	You have too many concurrent jobs; wait for existing jobs to complete before creating new ones
Job fails with error	Status becomes `Failed` or `Error Cancelled`	Read the `errors` array in the job response; fix the underlying issue and re-create

Related resources

Batched Jobs -- Run jobs with the Addepar-Compute-Type: BATCH header for large-scale exports (Beta)

Report Generation -- Generate PDF/Excel reports using the Jobs lifecycle

Portfolio View API -- The data source for portfolio_view_results job type

Portfolio Query API -- The data source for portfolio_query_results job type

Attributes -- Discover supported column keys for query jobs

Pagination -- Cursor-based pagination for the list endpoint

Jobs

Overview

Resource attributes

Parameters

Portfolio view job parameters

Portfolio query job parameters

Relationships

Create a portfolio view job

Create a portfolio query job

Get job status

Download results

List all jobs

Cancel a job

Status lifecycle

Error recovery

What’s Next