---
schema_version: "1"
id: 4bfa5863d2c38d043f2873d51963518bb066c3ae98cae1dcbd31cfff7f61f9e1
title: InvokeRetrieve()
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/ampscript/references/api/mc-ampscript-reference-api-invoke-retrieve.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-api/mc-ampscript-reference-api-invoke-retrieve.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 7b7fbbaee44b22b1ea2f365706bea8d934cdde3cac01de8eef391fa91507aab4
products:
  - AMPscript for Marketing Cloud
  - Marketing Cloud
---
# InvokeRetrieve()

Invokes the Retrieve method on a Marketing Cloud Engagement API Object and returns the API status message and request ID.

## Availability

<table>
  <tr>
    <td>Marketing Cloud Engagement</td>
    <td>✅ Yes</td>
  </tr>
  <tr>
    <td>Marketing Cloud Next</td>
    <td>❌ No</td>
  </tr>
</table>

## Syntax

```
InvokeRetrieve(apiObject,
               statusMessage,
               requestId)
```

The `InvokeRetrieve()` function has three parameters:

- `apiObject` (API Object): Required. The API Object to invoke the Retrieve method on.
- `statusMessage` (AMPscript variable): An AMPscript variable that stores the API status message.
- `requestId` (AMPscript variable): An AMPscript variable that stores the request ID.

## Usage

This example creates a RetrieveRequest Object, sets a property, and adds an array item. It then creates a simple filter that finds matching email addresses. Finally, the function calls the `InvokeRetrieve()` function, outputting the status message and the request ID.

```
%%[
  Var @rr_1, @sfp, @statusMessage, @requestId, @emailAddress
  Set @emailAddress = "john.rosales@example.com"
  Set @rr_1=CreateObject("RetrieveRequest")

  SetObjectProperty(@rr_1,"ObjectType","Subscriber")
  AddObjectArrayItem(@rr_1,"Properties","EmailAddress")

  Set @sfp=CreateObject("SimpleFilterPart")

  SetObjectProperty(@sfp,"Property","EmailAddress")
  SetObjectProperty(@sfp,"SimpleOperator","equals")
  AddObjectArrayItem(@sfp,"Value",@emailAddress)
  SetObjectProperty(@rr_1,"Filter",@sfp)

  Set @sub=InvokeRetrieve(@rr_1, @statusMessage, @requestId)
]%%
<p>Status message: %%=v(@statusMessage)=%%</p>
<p>Request ID: %%=v(@requestId)=%%</p>
```