AppAnalyticsQueryRequest | Object Reference for Salesforce and Lightning Platform

AppExchange App Analytics is available for packages that passed security review and are registered to a License Management App (LMA). Usage data is provided as package usage logs, as month-based package usage summaries, or as point-in-time subscriber snapshots. Usage logs, monthly usage summaries, and subscriber snapshots are downloadable comma-separated value (.csv) files. For information on how to optimize your use of App Analytics, see AppExchange App Analytics Best Practices.

Usage data from Government Cloud and Government Cloud Plus orgs isn’t available in App Analytics.

Note

Supported Calls

create(), delete(), describeSObjects(), getDeleted(), getUpdated(), query(), retrieve(), undelete(), update(), upsert()

Special Access Rules

See Request AppExchange App Analytics in the ISVforce Guide.

Fields

Field Name	Details
AvailableSince	Type dateTime Properties Create, Filter, Nillable, Sort Description An optional value used to limit the requested results file to data newly arrived in the data lake after the specified date and time. This field is always transferred in the Coordinated Universal Time (UTC) time zone. Use the `AvailableSince` field as part of your catch-up query strategy. `AvailableSince` must be later than `StartTime` and `EndTime`, if specified. `AvailableSince` must be earlier than now. A query must include `StartTime`,`AvailableSince`, or both. For example, to schedule a catch-up query on `2021-04-03T18:00:00Z` for this date range: `StartTime=2021-03-29T00:00:00Z` `EndTime=2021-03-30T00:00:00Z` Valid `AvailableSince` values range from `2021-03-30T00:00:00Z to 2021-04-03T18:00:00Z`. For more information on `AvailableSince` and catch-up queries, see AppExchange App Analytics Best Practices.
DataType	Type picklist Properties Create, Filter, Group, Restricted picklist, Sort Description The type of usage data being requested. Valid values include: `PackageUsageLog` `PackageUsageSummary` `SubscriberSnapshot` In Summer ’20, we changed the enum names from `CustomObjectUsageSummary` and `CustomObjectUsageLog` to `PackageUsageSummary` and `PackageUsageLog`. If you have integrations that use `CustomObjectUsageSummary` or `CustomObjectUsageLog`, they work only with v47 and earlier. After you upgrade to v48, you must update the `DataType` to `PackageUsageSummary` and `PackageUsageLog`. Note
DownloadExpirationTime	Type dateTime Properties Filter, Nillable, Sort Description The time when the download URL is no longer valid. The expiration time is 60 minutes after the query is completed.
DownloadSize	Type long Properties Filter, Group, Nillable, Sort Description The size of the AppExchange App Analytics results file available for download, in bytes.
DownloadUrl	Type textarea Properties Nillable Description URL that the user can download data from. Populated after the request is completed. This URL expires and is removed when the expiration time is reached.
EndTime	Type dateTime Properties Create, Filter, Nillable, Sort Description Enter the end time in format yyyy-MM-ddTHH:mm:ss. Example: 2019-04-15T12:00:00
ErrorMessage	Type string Properties Filter, Group, Nillable, Sort Description Stores error message text that results from this query.
FileCompression	Type picklist Properties Create, Filter, Group, Nillable, Restricted picklist, Sort Description The file compression format of your requested results file. `FileCompression` and `FileType` must align. If `FileType` is `csv`, `FileCompression` defaults to `none` and can be `none` or `gzip`. If `FileType` is `parquet`, `FileCompression` is `snappy` by default and can be `snappy`, `gzip`, or `none`. Valid values include: `gzip` `snappy` `none`
FileType	Type picklist Properties Create, Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort Description The data format of your requested results file. The default is `csv`. `FileCompression` and `FileType` must align. If `FileType` is `csv`, `FileCompression` defaults to `none` and can be `none` or `gzip`. If `FileType` is `parquet`, `FileCompression` is `snappy` by default and can be `snappy`, `gzip`, or `none`. Valid values include: `csv` `parquet`
LastReferencedDate	Type dateTime Properties Filter, Nillable, Sort Description The timestamp for when the current user last viewed a record related to this record.
LastViewedDate	Type dateTime Properties Filter, Nillable, Sort Description The timestamp for when the current user last viewed this record. If this value is null, it’s possible that this record was referenced (LastReferencedDate) and not viewed.
Name	Type string Properties Autonumber, Defaulted on create, Filter, idLookup, Sort Description The auto-generated name of the App Analytics query request.
OrganizationIds	Type string Properties Create, Filter, Group, Nillable, Sort Description Optional. Enter up to 16 comma-separated org IDs without spaces between IDs. Or enter up to 15 comma-separated org IDs with spaces between the IDs. To request data for all the orgs that the package is installed in, leave this field blank.
PackageIds	Type string Properties Create, Filter, Group, Nillable, Sort Description Optional. Enter up to 16 comma-separated package IDs without spaces between IDs. Or enter up to 15 comma-separated package IDs with spaces between the IDs. Use the subscriber package ID that begins with `033`. To retrieve a list of your second-generation managed package IDs, run `sfdx force:package:list --verbose` in Salesforce CLI. To request data on all packages registered to this License Management App, leave this field blank.
QuerySubmittedTime	Type dateTime Properties Filter, Nillable, Sort Description The date and time that the App Analytics query request was received for processing, in Coordinated Universal Time (UTC). `QuerySubmittedTime` is read only.
RequestState	Type picklist Properties Defaulted on create, Filter, Group, Nillable, Restricted picklist, Sort Description Status of the query request. Valid values are: `New` `Pending` `Complete` `Expired` `Failed` `NoData`
StartTime	Type dateTime Properties Create, Filter, Nillable, Sort Description Enter the start time in format yyyy-MM-ddTHH:mm:ss. All App Analytics query requests must include `StartTime` or `AvailableSince` or both. Example: 2019-04-14T12:00:00

Usage

To request usage data, log in to the License Management Org (LMO) that your package is registered to, and initiate the API request from the LMO. In a 24-hour period, you can download a maximum 20 GB of AppExchange App Analytics data.

See Download Package Usage Logs, Package Usage Summaries, and Subscriber Snapshots in the ISVforce Guide.

If requests to view package usage log or subscriber snapshot data are inactive for 90 days, we reserve the right to stop collecting this data. To resume data collection, log a support case in the Salesforce Partner Community. For product, specify Partner Programs & Benefits. For topic, specify ISV Technology Request.