Analytics API Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Describe

Resource URL

Retrieves report, report type, and related metadata for a tabular, summary, or matrix report.

  • Report type metadata tells you about all the fields available in the report type, those you can filter, and by what filter criteria.

  • Report extended metadata tells you about the fields that are summaries, groupings, and contain record details in the report. A property that displays null indicates that its value is not available.

  • Report metadata gives information about the report as a whole. Tells you such things as, the report type, format, the fields that are summaries, row or column groupings, filters saved to the report, and so on.

1/services/data/<latest API version>/analytics/reports/<report ID>/describe

Formats

JSON

HTTP methods

GET

Response body

Property Type Description
reportTypeMetadata Report type metadata Fields in each section of a report type plus filter information for those fields.
reportExtendedMetadata Report extended metadata Additional information about summaries and groupings.
reportMetadata Report metadata Unique identifiers for groupings and summaries.
Report type metadata
Property Type Description
categories Categories[] All fields in the report type organized by section.
dataTypeFilterOperatorMap Filter operator reference Lists all the possible field data types that can be used to filter the report. Each data type, such as phone, percent, currency, or picklist has two properties:

name: Of type string, this is a unique API name for each field type’s filter criteria. Use this API name in the metadata to define filter criteria for a report.

label: Of type string, this is the display name for each filter criteria available to fields of a particular data type. For example, multipicklist fields can have for filter criteria, “equals,” “not equal to,” “includes,” and “excludes.” Bucket fields are considered to be of string data type.
Categories
Property Type Description
label String Display name of a section in the report type under which fields are organized. For example, in an Accounts with Contacts custom report type, Account General is the display name of the section that has fields on general account information.
columns Column map Information for all fields in the report type organized under a particular section’s unique API name.
Column map
Property Type Description
label String Display name of a field.
filterValues String array All filter values for a field, if the field data type is of picklist, multi-select picklist, boolean, or checkbox. For example, checkbox fields always have a value of True or False. For fields of other data types, the filter value is an empty array because their values can’t be determined. Filter values have two properties:

name: Unique API name for a filter value. Of type string.

label: Display name of a filter value. Of type string.
dataType String Data type of the field.
filterable Boolean False means that the field is of a type that can’t be filtered. For example, fields of the type Encrypted Text can’t be filtered.
Report extended metadata
Property Type Description
groupingColumnInfo Grouping column information Map of each row or column grouping to its metadata. Contains values for each grouping identified in the groupingsDown and groupingsAcross list.
detailColumnInfo Detail column information Two properties for each field that has detailed data identified by its unique API name. The detailed data fields are also listed in the report metadata.
aggregateColumnInfo Aggregate column information Includes all report summaries such as, Record Count, Sum, Average, Max, Min, and custom summary formulas. Contains values for each summary listed in the report metadata aggregates.
Detail column information
Property Type Description
label String The localized display name of a standard field, the ID of a custom field, or the API name of a bucket field that has detailed data.
dataType String The data type of the field that has detailed data.
Aggregate column information
Property Type Description
label String Display name for record count, or the summarized or custom summary formula field.
dataType String Data type of the summarized or custom summary formula field.
acrossGroupingContext String Column grouping in the report where the custom summary formula is displayed. As this example shows in the JSON response and in the custom summary formula editor of the matrix report, the custom summary formula is set at the grand summary level for the columns.
1{ 
2   "reportExtendedMetadata" : {
3      "aggregateColumnInfo" : {
4         "FORMULA1" : {
5            "label" : "Stalled Oppty Avg",
6            "dataType" : "Percent",
7            "acrossGroupingContext" : "GRAND_SUMMARY",
8            "downGroupingContext" : "GRAND_SUMMARY"
9         },
10      }
11   }
12}
Grouping level where the custom summary formula is displayed for a matrix report
downGroupingContext String Row grouping in the report where the custom summary formula is displayed. In this example, the custom summary formula for a summary report is displayed at the first grouping level This example is shown in both the JSON response and in the custom summary formula editor of the summary report.
1{
2   "reportExtendedMetadata" : {
3      "aggregateColumnInfo" : {
4...},
5         "FORMULA1" : { 
6            "label" : "Average Won",
7            "dataType" : "Number",
8            "acrossGroupingContext" : null,
9            "downGroupingContext" : "TYPE"
10         },
11      }
12   }
13}
Grouping level where the custom summary formula is displayed in a summary report
Grouping column information
Property Type Description
label String Display name of the field or bucket field used for grouping.
dataType String Data type of the field used for grouping.
groupingLevel Integer

Level of the grouping. Value can be:

  • 0, 1, or 2. Indicates first, second, or third row level grouping in summary reports.
  • 0 or 1. Indicates first or second row or column level grouping in a matrix report.
Report metadata
Property Type Description
name String Report name.
id String Unique report ID.
currency String Report currency, such as USD, EUR, GBP, for an organization that has Multi-Currency enabled. Value is null if the organization does not have Multi-Currency enabled.
reportFormat String Format of the report. Value can be:
  • TABULAR
  • SUMMARY
  • MATRIX
developerName String Report API name.
reportType Report type Unique API name and display name for the report type.

type: Of type string, this is the unique identifier of the report type.

label: Of type string, this is the display name of the report type.
aggregates Array of strings Unique identities for summary or custom summary formula fields in the report. For example:
  • a!Amount represents the average for the Amount column.
  • s!Amount represents the sum of the Amount column.
  • m!Amount represents the minimum value of the Amount column.
  • x!Amount represents the maximum value of the Amount column.
  • s!<customfieldID> represents the sum of a custom field column. For custom fields and custom report types, the identity is a combination of the summary type and the field ID.
groupingsDown Groupings down[] Unique identities for each row grouping in a report. The identity is:
  • BucketField_(ID) for bucket fields.
  • ID of a custom field when the custom field is used for grouping.
groupingsAcross Groupings across[] Unique identities for each column grouping in a report. The identity is:
  • An empty array for reports in summary format as it can’t have column groupings.
  • BucketField_(ID) for bucket fields.
  • ID of a custom field when the custom field is used for a column grouping.
reportBooleanFilter String Logic to parse custom field filters. Value is null when filter logic is not specified.

This is an example of a report filtered to show opportunities for accounts that are either of customer or partner type OR their annual revenue exceeds 100K AND they are medium or large sized businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”

1{
2...
3        "reportBooleanFilter": "(1 OR 2) AND 3",
4        "reportFilters": [
5            {
6                "value": "Analyst,Integrator,Press,Other",
7                "column": "TYPE",
8                "operator": "notEqual"
9            },
10            {
11                "value": "100,000",
12                "column": "SALES",
13                "operator": "greaterThan"
14            },
15            {
16                "value": "Small",
17                "column": "Size",
18                "operator": "notEqual"
19            }
20        ]
21    }
22}
reportFilters Filter details[] List of each custom filter in the report along with the field name, filter operator, and filter value.
detailColumns Array of strings Unique API names for the fields that have detailed data.
historicalSnapshotDates Array of strings List of historical snapshot dates.
Groupings down
Property Type Description
name String API name of the field used as a row grouping.
sortOrder String Order in which data is sorted within a row grouping. Value can be:
  • Asc for ascending order.
  • Desc for descending order.
dateGranularity String Interval set on a date field that’s used as a row grouping. Value can be:
  • Day
  • Calendar Week
  • Calendar Month
  • Calendar Quarter
  • Calendar Year
  • Fiscal Quarter
  • Fiscal Year
  • Calendar Month in Year
  • Calendar Day in Month
sortAggregate String Summary field that’s used to sort data within a grouping in a report that’s in summary format. Applies if you have the Aggregate Sort feature enabled as part of its pilot program. The value is null when data within a grouping is not sorted by a summary field. In this example, data grouped by Account Owner is sorted by the sum of Annual Revenue.
1{
2    "aggregates": ["s!SALES","RowCount"],
3    "groupingsDown": [
4        {
5            "name": "USERS.NAME",
6            "sortOrder": "Desc",
7            "dateGranularity": "None",
8            "sortAggregate": "s!SALES"
9        }
10    ]
11}
Groupings across
Property Type Description
name String API name of the field used as a column grouping.
sortOrder String Order in which data is sorted within a column grouping. Value can be:
  • Asc for ascending order.
  • Desc for descending order.
dateGranularity String Interval set on a date field used as a column grouping. Value can be:
  • Day
  • Calendar Week
  • Calendar Month
  • Calendar Quarter
  • Calendar Year
  • Fiscal Quarter
  • Fiscal Year
  • Calendar Month in Year
  • Calendar Day in Month
Filter details
Property Type Description
value String Value by which a field is filtered. For example, the field Age can be filtered by a numeric value.
column String Unique API name for the field that’s being filtered.
operator String Unique API name for the condition used to filter a field such as “greater than” or “not equal to.” Filter conditions depend on the data type of the field.

Example

See this sample of a GET request for report metadata.