Salesforce Analytics API

{
  "openapi": "3.1.0",
  "info": {
    "title": "Salesforce Analytics (CRM Analytics) REST API",
    "description": "REST API for accessing and managing CRM Analytics (formerly Tableau CRM / Einstein Analytics) resources including datasets, lenses, dashboards, and dataflows. Enables programmatic access to analytics metadata, query execution, and dashboard management. Uses the Wave API resource at /services/data/vXX.0/wave.",
    "version": "63.0",
    "contact": {
      "name": "Salesforce Developer Support",
      "url": "https://developer.salesforce.com/support",
      "email": "[email protected]"
    },
    "license": {
      "name": "Salesforce API Terms of Use",
      "url": "https://www.salesforce.com/company/legal/agreements/"
    }
  },
  "servers": [
    {
      "url": "https://{instance}.salesforce.com/services/data/v63.0/wave",
      "description": "Salesforce production or developer instance",
      "variables": {
        "instance": {
          "default": "yourInstance",
          "description": "Your Salesforce instance identifier"
        }
      }
    }
  ],
  "security": [
    {
      "oauth2": []
    },
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/datasets": {
      "get": {
        "operationId": "getDatasets",
        "summary": "List datasets",
        "description": "Returns a paginated list of CRM Analytics datasets accessible to the current user. Supports filtering by folder, search term, and sort order.",
        "tags": ["Datasets"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search term to filter datasets by name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folderId",
            "in": "query",
            "description": "Filter datasets by analytics app (folder) ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 200
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["Name", "CreatedDate", "LastModifiedDate", "Mru"]
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["Ascending", "Descending"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of datasets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetList"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{datasetIdOrApiName}": {
      "get": {
        "operationId": "getDataset",
        "summary": "Get a dataset",
        "description": "Returns metadata for a specific CRM Analytics dataset.",
        "tags": ["Datasets"],
        "parameters": [
          {
            "name": "datasetIdOrApiName",
            "in": "path",
            "required": true,
            "description": "The dataset ID or developer name",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                }
              }
            }
          }
        }
      }
    },
    "/query": {
      "post": {
        "operationId": "executeQuery",
        "summary": "Execute a SAQL query",
        "description": "Executes a SAQL (Salesforce Analytics Query Language) query against CRM Analytics datasets. SAQL provides a SQL-like syntax for querying, aggregating, and transforming analytics data.",
        "tags": ["Query"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "The SAQL query string"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "The timezone for date operations (e.g., America/Los_Angeles)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResult"
                }
              }
            }
          }
        }
      }
    },
    "/dashboards": {
      "get": {
        "operationId": "getDashboards",
        "summary": "List dashboards",
        "description": "Returns a paginated list of CRM Analytics dashboards accessible to the current user.",
        "tags": ["Dashboards"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search term to filter dashboards",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folderId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of dashboards",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DashboardList"
                }
              }
            }
          }
        }
      }
    },
    "/dashboards/{dashboardId}": {
      "get": {
        "operationId": "getDashboard",
        "summary": "Get a dashboard",
        "description": "Returns metadata and configuration for a specific CRM Analytics dashboard, including its widgets, steps, and layout.",
        "tags": ["Dashboards"],
        "parameters": [
          {
            "name": "dashboardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dashboard"
                }
              }
            }
          }
        }
      }
    },
    "/lenses": {
      "get": {
        "operationId": "getLenses",
        "summary": "List lenses (explorations)",
        "description": "Returns a paginated list of CRM Analytics lenses (saved explorations).",
        "tags": ["Lenses"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folderId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of lenses",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LensList"
                }
              }
            }
          }
        }
      }
    },
    "/dataflows": {
      "get": {
        "operationId": "getDataflows",
        "summary": "List dataflows",
        "description": "Returns a list of CRM Analytics dataflows (recipes). Dataflows define the ETL process for loading data into analytics datasets.",
        "tags": ["Dataflows"],
        "responses": {
          "200": {
            "description": "List of dataflows",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataflowList"
                }
              }
            }
          }
        }
      }
    },
    "/dataflows/{dataflowId}": {
      "get": {
        "operationId": "getDataflow",
        "summary": "Get a dataflow",
        "description": "Returns the definition and metadata for a specific CRM Analytics dataflow.",
        "tags": ["Dataflows"],
        "parameters": [
          {
            "name": "dataflowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataflow metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataflow"
                }
              }
            }
          }
        }
      }
    },
    "/folders": {
      "get": {
        "operationId": "getFolders",
        "summary": "List analytics apps (folders)",
        "description": "Returns a list of CRM Analytics applications (folders) that organize dashboards, lenses, and datasets.",
        "tags": ["Folders"],
        "responses": {
          "200": {
            "description": "List of folders",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "folders": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Folder"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://login.salesforce.com/services/oauth2/authorize",
            "tokenUrl": "https://login.salesforce.com/services/oauth2/token",
            "scopes": {
              "api": "Access and manage your Salesforce data",
              "wave_api": "Access CRM Analytics REST API resources"
            }
          }
        }
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Dataset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "The developer name"
          },
          "label": {
            "type": "string",
            "description": "The display label"
          },
          "description": {
            "type": ["string", "null"]
          },
          "createdDate": {
            "type": "string",
            "format": "date-time"
          },
          "lastModifiedDate": {
            "type": "string",
            "format": "date-time"
          },
          "datasetType": {
            "type": "string",
            "description": "The type of dataset (default, live, trended)"
          },
          "currentVersionId": {
            "type": "string"
          },
          "folder": {
            "$ref": "#/components/schemas/FolderRef"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "DatasetList": {
        "type": "object",
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dataset"
            }
          },
          "nextPageUrl": {
            "type": ["string", "null"]
          },
          "totalSize": {
            "type": "integer"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Dashboard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "createdDate": {
            "type": "string",
            "format": "date-time"
          },
          "lastModifiedDate": {
            "type": "string",
            "format": "date-time"
          },
          "folder": {
            "$ref": "#/components/schemas/FolderRef"
          },
          "state": {
            "type": "object",
            "additionalProperties": true,
            "description": "The dashboard JSON state definition"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "DashboardList": {
        "type": "object",
        "properties": {
          "dashboards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dashboard"
            }
          },
          "nextPageUrl": {
            "type": ["string", "null"]
          },
          "totalSize": {
            "type": "integer"
          }
        }
      },
      "LensList": {
        "type": "object",
        "properties": {
          "lenses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "createdDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "lastModifiedDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "folder": {
                  "$ref": "#/components/schemas/FolderRef"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "nextPageUrl": {
            "type": ["string", "null"]
          },
          "totalSize": {
            "type": "integer"
          }
        }
      },
      "Dataflow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "createdDate": {
            "type": "string",
            "format": "date-time"
          },
          "lastModifiedDate": {
            "type": "string",
            "format": "date-time"
          },
          "definition": {
            "type": "object",
            "additionalProperties": true,
            "description": "The dataflow definition JSON containing nodes and transformations"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "DataflowList": {
        "type": "object",
        "properties": {
          "dataflows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dataflow"
            }
          }
        }
      },
      "Folder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "createdDate": {
            "type": "string",
            "format": "date-time"
          },
          "lastModifiedDate": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "FolderRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "QueryResult": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string"
          },
          "responseId": {
            "type": "string"
          },
          "results": {
            "type": "object",
            "properties": {
              "metadata": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "records": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "query": {
            "type": "string"
          },
          "responseTime": {
            "type": "number"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Datasets",
      "description": "CRM Analytics datasets"
    },
    {
      "name": "Query",
      "description": "SAQL query execution"
    },
    {
      "name": "Dashboards",
      "description": "CRM Analytics dashboards"
    },
    {
      "name": "Lenses",
      "description": "CRM Analytics lenses (explorations)"
    },
    {
      "name": "Dataflows",
      "description": "CRM Analytics dataflows (recipes)"
    },
    {
      "name": "Folders",
      "description": "Analytics applications (folders)"
    }
  ]
}