Retrieving external account history

How to retrieve the history on a linked external account.



To get external account history, you need to use the v0 APIs.


You can retrieve an account transaction history for external accounts that have been successfully linked to a customer using Plaid Link. Depending on the external financial institute and the duration of time that the account has been open, up to 24 months of transaction data can be retrieved.

You can't retrieve history for an external account that has been linked but which is not verified.

In a single paginated response, you can retrieve up to 500 sequentially ordered transactions.


Using this API for the first time

When this endpoint is called for an account for the first time, a full transaction history query starts processing. This takes a minute or two to complete and only occurs once. When this is complete, any subsequent queries are returned immediately.

Retrieving an external account history

To retrieve an account's history, use GET /accounts/{account_id}/history and provide optional query parameters as shown in the table below.






Retrieve account history starting at this date in ISO 8601 YYYY-MM-DD format, for example 202-01--1. Default is 30 days prior to end_date.



Retrieve account history up until this date in ISO 8601 YYYY-MM-DD format, for example 2021-10-15. Defaults to today's date.



Number of transactions to retrieve, between 1 and 500. Default is 100.



Number of transactions to skip. Default is 0.

An example of a request to retrieve an account history is shown below.

curl --request GET \
     --url '' \
     --header 'Accept: application/json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("")

http =, url.port)
http.use_ssl = true

request =
request["Accept"] = 'application/json'

response = http.request(request)
puts response.read_body
const options = {method: 'GET', headers: {Accept: 'application/json'}};

fetch('', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = ""

querystring = {"start_date":"2020-01-01","end_date":"2021-07-31","count":"50","offset":"0"}

headers = {"Accept": "application/json"}

response = requests.request("GET", url, headers=headers, params=querystring)

var client = new RestClient("");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .addHeader("Accept", "application/json")

Response response = client.newCall(request).execute();

When this API is queried for the first time, you receive a response similar to that shown below.

    "account_id": "b3952794-e073-41fc-80c9-18166039bc43",
    "status": "initiated",
    "message": "Transaction query initiated"



You need to refresh the external account link if you receive the following message:

     "Message":"The login details of this item have changed (credentials, MFA, or required user action) and a user 
      login is required to update this information. Use Link's update mode to restore the item to a good state.",
      "Status": 424,
     "Code": "processor_error",
     "Type": "Processor Error",

Webhooks are sent when the full transaction history is ready, as described below in Account history webhook. When the data set is ready, you can send a query again to retrieve transactions.

An example of a response to a successful request for an external account history is shown below.

  "account_id": "b3952794-e073-41fc-80c9-18166039bc43",
  "type": "external",
  "balances": {
    "available_balance": 110,
    "current_balance": 110,
    "currency": "USD",
  "total_transactions": 125,
  "transactions": [
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "state": "pending",
      "previous_transaction_id": null,
      "transaction_type": "in store",
      "amount": 2307.21,
      "currency": "USD",
      "created_time": "2017-01-27",
      "updated_time": "2017-01-29",
      "details": {
        "statement_descriptor": "Apple Store",
        "mcc_description": "Computers and Electronics",
        "merchant_name": "Apple",
        "merchant_address": "300 Post St",
        "merchant_city": "San Francisco",
        "merchant_state": "CA",
        "merchant_postal_code": "94108",
        "merchant_country": "US",
        "merchant_lat": 40.740352,
        "merchant_long": -74.001761,
        "merchant_store_number": "1235"

total_transactions is the total number of transactions available within the date range you specified. If this is larger than the size of the transactions array (using any value of count), more transactions are available which can be retrieved using the offset parameter.

For a complete specification and interactive examples, see Get accounts history in the Bond API Reference.

Transaction format

The attributes comprising a transaction in the external account transaction history response are described in the table below.




Unique ID of the transaction.


pending or completed.


For completed transactions, this is the ID of the pending transaction where applicable.


One of:

  • `online`—transactions made online
  • `in store`—transactions made at a physical location
  • `other`—transactions related to banks, such as fees or deposits


The signed amount of the settled transaction. Positive values mean money moved out of the account and negative values mean money moved into the account.


The ISO currency code of the transaction.


The date the transaction was authorized in YYYY-MM-DD format using UTC, for example 2021-08-10.


The date the transaction occurred or was completed in YYYY-MM-DD format using UTC, for example 2021-08-31.


The transaction description or merchant name.


The description of the most granular MCC code known.


The merchant name retrieved from the statement_descriptor.


The street address where the transaction occurred.


The city where the transaction occurred.


The state or region where the transaction occurred.


The postal code where the transaction occurred.


The ISO country code for where the transaction occurred.


The geographic latitude where the transaction occurred.


The geographic longitude where the transaction occurred.


The merchant defined store number where the transaction occurred.

Account history webhook

To receive notification when the full account history is available to query, subscribe to the account.history.ready webhook event.

Once you have subscribed to this event and the full transaction history is available, you receive a callback similar to that shown below.

    "event": "account.history.ready",
    "account_id": "b3952794-e073-41fc-80c9-18166039bc43",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00"

For a description of webhooks, see Webhooks and Webhook events and subscriptions. For a complete specification and interactive examples, see Webhooks in the Bond API Reference.

Retrieving balances for a Brand's accounts

For details regarding retrieving account balances, see Retrieving account balances.

Did this page help you?