Request

Response

    Filter Datasets List
    POST

    v3/datasets/list:filter

    Retrieves datasets assigned to the caller, narrowed by supported data type and/or name.

    Resource Information

    Method and URI
    POST
    https://developer.api.autodesk.com/sustainability/v3/datasets/list:filter
    Authentication Context
    User context required
    Required OAuth Scopes
    data:read
    Data Format
    JSON

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is a three-legged access token obtained via an Authorization Code flow or a Secure Service Account (SSA) flow.

    The SSA flow is designed for headless server-to-server operations. While it functions like a two-legged flow (no user interaction), it is classified as three-legged because it preserves user context.

    Content-Type*
    string
    Must be application/json
    * Required

    Request

    Query String Parameters

    limit
    int
    The maximum number of results to return in a single response. This controls the page size for pagination and helps manage response times and memory usage. The actual number of results may be fewer due to filtering, data availability, or server constraints.
    offset
    int
    The number of results to skip from the beginning of the collection before returning results. This allows pagination through large datasets by specifying which result to start from. Default value is 0 (start from the beginning).

    Request

    Body Structure

    Filter criteria to narrow down the datasets list

    Expand all
    filters*
    object
    Map of filter id to filter clause. Keys are filter identifiers; values are { op, value } objects. An empty object applies no filtering. Omit optional known filters rather than sending null as the clause value.
    **
    object
    A well-formed filter clause. Each key under filters in the request body must map to an object with op and value. Sending explicit null as the clause (instead of { op, value }) is invalid. The value field may be null as a primitive when the operator allows it.
    op*
    enum:string
    Filter operator. Must be one of the supported operators. Possible values: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, BETWEEN
    value*
    one of
    Filter value. For scalar operators (EQ, NEQ, LT, LTE, GT, GTE, CONTAINS), supply a single primitive (string, number, boolean, or null). For array operators (IN, NOT_IN), supply an array of primitives. For BETWEEN, supply a 2-element array representing the inclusive range bounds.
    0*
    string
    1*
    number
    2*
    boolean
    3*
    array
    oneOf*
    array:oneOf
    0*
    string
    1*
    number
    2*
    boolean
    * Required

    Response

    HTTP Status Code Summary

    200
    OK
    A filtered list of datasets was successfully retrieved.
    400
    Bad Request
    The request could not be processed due to invalid or malformed data. Check the request parameters, body format, and required fields before retrying.
    401
    Unauthorized
    The supplied authorization header was invalid or the token scope was not acceptable. Verify your authentication credentials and try again.
    403
    Forbidden
    The request was valid but lacked the necessary permissions. Verify your credentials and permissions before sending the request again.

    Response

    Body Structure (200)

    Expand all
    results
    array: object
    Array of datasets matching the filter criteria.
    id
    string
    Unique identifier for the dataset. Use this value as the datasetId URI parameter in API requests to access this dataset’s data.
    name
    string
    The display name of the dataset. This is the human-readable name that should be shown to users when presenting dataset options.
    description
    string
    Detailed description of the dataset. This can include information about the data sources, methodologies, coverage, and the types of sustainability data it contains.
    provider
    object
    The display name of the data provider. This is the human-readable name that should be shown to users when identifying the dataset’s source.
    name
    string
    The display name of the sustainability data provider. This is the human-readable name that should be shown to users when presenting provider options.
    supportedDataTypes
    array: string
    Array of supported data types for this dataset. Must contain at least one data type.

    Valid data types: - baselines - Baseline environmental data - generic-estimates - Generic environmental impact estimates - industry-epds - Industry-wide Environmental Product Declarations - product-epds - Product-specific Environmental Product Declarations - activities - Manufacturing and process-level LCI activities

    pagination
    object
    Contains pagination metadata for navigating through large result sets.
    offset
    int
    The number of results skipped from the beginning of the collection to retrieve the current set of results. This value will be the value supplied in the request.
    limit
    int
    Determines maximum number of objects that may be returned in the current set of results. A request may return fewer objects due to filtering and other reasons. This value will be the value used by the server in the response. This may be different from the request.
    totalResults
    int
    The total number of results that match the request irrespective of the limit. Can be null if the total number of results is not known.
    nextUrl
    string
    Link that will return the next set of results. This value may be null which indicates that the consumer has reached the last set of results and should stop paging.
    appliedFilters
    object
    Present on every successful :filter response; may be an empty object. Maps filter ids the client sent that were used for this action to { requested, applied, warnings? } entries.
    *
    object
    An applied filter entry showing the requested and applied filter values.
    requested
    object
    The filter value as requested by the client.
    op
    enum:string
    The filter operator. Possible values: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, BETWEEN
    value
    one of
    The filter value. Can be a single string, number, boolean, an array of strings, an array of numbers, or null.
    0
    string
    1
    number
    2
    boolean
    3
    array: string
    4
    array: number
    applied
    object
    The filter value as actually applied.
    op
    enum:string
    The filter operator. Possible values: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, BETWEEN
    value
    one of
    The filter value. Can be a single string, number, boolean, an array of strings, an array of numbers, or null.
    0
    string
    1
    number
    2
    boolean
    3
    array: string
    4
    array: number
    warnings
    array: string
    Optional warnings about the applied filter.
    ignoredFilters
    object
    Present on every successful :filter response; may be an empty object. Maps filter ids the client sent that are not supported for this action (per filter discovery for that resource and action) to { reason } entries. Keys must match the client’s filter ids exactly. Every filter entry in the request must be a valid { op, value } clause (see the filter request schema) or the request fails with 400.
    *
    object
    An ignored filter entry with the reason it was ignored.
    reason
    string
    The reason the filter was ignored. For filter ids not supported on this action, the response uses the fixed string Filter is not supported by this connector.
    warnings
    array: string
    Optional top-level warnings when one or more list items from the data provider failed validation and were excluded from results. Omitted when no items were stripped.

    Example

    A filtered list of datasets was successfully retrieved.

    Request

    curl -v 'https://developer.api.autodesk.com/sustainability/v3/datasets/list:filter?limit=100' \
      -X 'POST' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
      -H 'Content-Type: application/json' \
      -d '{
            "filters": {
              "jurisdictions": {
                "op": "IN",
                "value": [
                  "US",
                  "CA"
                ]
              }
            }
          }'
    
    Show More

    Response

    {
      "results": [
        {
          "id": "f47ac123-4569-4372-000a-0e0123a58479",
          "name": "EC3 - Building Transparency",
          "description": "The Embodied Carbon in Construction Calculator (EC3) tool is a free and easy to use tool that allows benchmarking, assessment and reductions in embodied carbon, focused on the upfront supply chain emissions of construction materials.\n",
          "provider": {
            "name": "EC3 - Building Transparency"
          },
          "supportedDataTypes": [
            "baselines",
            "generic-estimates",
            "industry-epds",
            "product-epds"
          ]
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 25,
        "nextUrl": "https://developer.api.autodesk.com/sustainability/v3/datasets/f81d4fae-7dec-11d0-a765-00a0c91e6bf6/epds/categories?offset=25&limit=25",
        "totalResults": 150
      },
      "appliedFilters": {
        "categoryId": {
          "requested": {
            "op": "EQ",
            "value": "cat-masterformat-033000"
          },
          "applied": {
            "op": "EQ",
            "value": "cat-masterformat-033000"
          }
        },
        "jurisdictions": {
          "requested": {
            "op": "IN",
            "value": [
              "US",
              "CA"
            ]
          },
          "applied": {
            "op": "IN",
            "value": [
              "US"
            ]
          },
          "warnings": [
            "Value 'CA' is not supported for jurisdictions and was ignored."
          ]
        }
      },
      "ignoredFilters": {
        "unknown_filter": {
          "reason": "Filter is not supported by this connector."
        }
      },
      "warnings": [
        "The number of results returned differs from pagination.totalResults because 1 record from the data provider failed validation and were omitted. Please contact your data provider for assistance. Example record ID: bad-record-1."
      ]
    }
    
    Show More