Observe Tags API

openapi: 3.2.0
info:
  title: Observeinc Tags API
  version: 1.0.230307
  x-assembled-from:
  - https://docs.observeinc.com/reference/createapitoken.md
  - https://docs.observeinc.com/reference/createdashboard.md
  - https://docs.observeinc.com/reference/createdatasetqueryfilter.md
  - https://docs.observeinc.com/reference/createingestfilter.md
  - https://docs.observeinc.com/reference/createingestroute.md
  - https://docs.observeinc.com/reference/createingesttoken.md
  - https://docs.observeinc.com/reference/createmonitor.md
  - https://docs.observeinc.com/reference/createmonitormute.md
  - https://docs.observeinc.com/reference/createmonitormuterule.md
  - https://docs.observeinc.com/reference/createreferencetable.md
  - https://docs.observeinc.com/reference/createserviceaccount.md
  - https://docs.observeinc.com/reference/createskill.md
  - https://docs.observeinc.com/reference/deleteapitoken.md
  - https://docs.observeinc.com/reference/deletedashboard.md
  - https://docs.observeinc.com/reference/deletedatasetqueryfilter.md
  - https://docs.observeinc.com/reference/deleteingestfilter.md
  - https://docs.observeinc.com/reference/deleteingestroute.md
  - https://docs.observeinc.com/reference/deleteingesttoken.md
  - https://docs.observeinc.com/reference/deletemonitor.md
  - https://docs.observeinc.com/reference/deletemonitormute.md
  - https://docs.observeinc.com/reference/deletemonitormuterule.md
  - https://docs.observeinc.com/reference/deletereferencetable.md
  - https://docs.observeinc.com/reference/deleteserviceaccount.md
  - https://docs.observeinc.com/reference/deleteskill.md
  - https://docs.observeinc.com/reference/exportquery.md
  - https://docs.observeinc.com/reference/exportquerypage.md
  - https://docs.observeinc.com/reference/exportworksheet.md
  - https://docs.observeinc.com/reference/generateapitoken.md
  - https://docs.observeinc.com/reference/getalert.md
  - https://docs.observeinc.com/reference/getapitoken.md
  - https://docs.observeinc.com/reference/getapminvocationgraph.md
  - https://docs.observeinc.com/reference/getdashboard.md
  - https://docs.observeinc.com/reference/getdataset.md
  - https://docs.observeinc.com/reference/getdatasetbyid.md
  - https://docs.observeinc.com/reference/getdatasetgraph.md
  - https://docs.observeinc.com/reference/getdatasetqueryfilterbyid.md
  - https://docs.observeinc.com/reference/getdatasetstats.md
  - https://docs.observeinc.com/reference/getingestfilter.md
  - https://docs.observeinc.com/reference/getingestroute.md
  - https://docs.observeinc.com/reference/getingesttoken.md
  - https://docs.observeinc.com/reference/getmonitor-1.md
  - https://docs.observeinc.com/reference/getmonitormute.md
  - https://docs.observeinc.com/reference/getmonitormuterule.md
  - https://docs.observeinc.com/reference/getmonitorstats.md
  - https://docs.observeinc.com/reference/getreferencetable.md
  - https://docs.observeinc.com/reference/getserviceaccount.md
  - https://docs.observeinc.com/reference/getskill.md
  - https://docs.observeinc.com/reference/listalerts.md
  - https://docs.observeinc.com/reference/listapitokens.md
  - https://docs.observeinc.com/reference/listapmenvironments.md
  - https://docs.observeinc.com/reference/listapmservices.md
  - https://docs.observeinc.com/reference/listdashboards.md
  - https://docs.observeinc.com/reference/listdatasetgraph.md
  - https://docs.observeinc.com/reference/listdatasetqueryfilters.md
  - https://docs.observeinc.com/reference/listdatasets-1.md
  - https://docs.observeinc.com/reference/listdatasets.md
  - https://docs.observeinc.com/reference/listdatasettags.md
  - https://docs.observeinc.com/reference/listfilterabledatasets.md
  - https://docs.observeinc.com/reference/listingestfilters.md
  - https://docs.observeinc.com/reference/listingestroutes.md
  - https://docs.observeinc.com/reference/listingesttokens.md
  - https://docs.observeinc.com/reference/listmetrics.md
  - https://docs.observeinc.com/reference/listmonitormuterules.md
  - https://docs.observeinc.com/reference/listmonitormutes.md
  - https://docs.observeinc.com/reference/listmonitors-1.md
  - https://docs.observeinc.com/reference/listserviceaccounts.md
  - https://docs.observeinc.com/reference/listskills.md
  - https://docs.observeinc.com/reference/polldelegatedlogin.md
  - https://docs.observeinc.com/reference/queryreferencetables.md
  - https://docs.observeinc.com/reference/searchdocumentation.md
  - https://docs.observeinc.com/reference/searchobjecttagkeys.md
  - https://docs.observeinc.com/reference/searchobjecttagvalues.md
  - https://docs.observeinc.com/reference/searchtagvalues.md
  - https://docs.observeinc.com/reference/startdelegatedlogin.md
  - https://docs.observeinc.com/reference/updateapitoken.md
  - https://docs.observeinc.com/reference/updatedashboard.md
  - https://docs.observeinc.com/reference/updatedatasetqueryfilter.md
  - https://docs.observeinc.com/reference/updateingestfilter.md
  - https://docs.observeinc.com/reference/updateingestroute.md
  - https://docs.observeinc.com/reference/updateingestroutepriorities.md
  - https://docs.observeinc.com/reference/updateingesttoken.md
  - https://docs.observeinc.com/reference/updatemonitor.md
  - https://docs.observeinc.com/reference/updatemonitormute.md
  - https://docs.observeinc.com/reference/updatereferencetable.md
  - https://docs.observeinc.com/reference/updatereferencetablemetadata.md
  - https://docs.observeinc.com/reference/updateserviceaccount.md
  - https://docs.observeinc.com/reference/updateskill.md
  - https://docs.observeinc.com/reference/validateingestfilterexpression.md
  x-retrieved: '2026-10-13'
  x-source: Assembled verbatim from the OpenAPI 3.1 definitions ReadMe embeds in each of 88 operation pages under https://docs.observeinc.com/reference/ (no single downloadable spec is published); paths and components merged, nothing authored.
  description: 'Operations tagged Tags across 2 of this provider''s published API definitions: observeinc-openapi-assembled.json, observeinc-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{customerid}.observeinc.com
  description: US west server
  variables:
    customerid:
      default: OBSERVE_CUSTOMERID
      description: The customer ID for your instance.
- url: https://{customerid}.{cluster}.observeinc.com
  description: Specific regional cluster (prod)
  variables:
    customerid:
      default: OBSERVE_CUSTOMERID
      description: The customer ID for your instance.
    cluster:
      enum:
      - eu-1
      - ap-1
      default: eu-1
      description: For regional clusters, choose one.
- url: https://{customerid}.{domain}.com
  description: Specific Observe server
  variables:
    customerid:
      default: OBSERVE_CUSTOMERID
      description: The customer ID for your instance.
    domain:
      default: OBSERVE_DOMAIN
      description: The Observe domain for your instance.
security:
- bearerAuth: []
tags:
- name: Tags
paths:
  /v1/tags:
    get:
      summary: List tags
      description: 'Returns a paginated list of tags (both correlation and metric kinds)

        defined across the tenant''s datasets. Each entry groups all per-dataset

        definitions of a single `(name, kind)` pair.


        Use `GET /v1/tags/values` to search tag *values*.


        ## Filtering and ordering with CEL


        The `filter` and `orderBy` query parameters are evaluated as

        Common Expression Language (CEL) expressions over

        each tag in the response.


        ### Available CEL fields


        - `name` (string) — tag name; supports `.matches("regex")`

        - `kind` (string) — `"Correlation"` or `"Metric"`

        - `datasetCount` (int) — number of distinct datasets defining the tag

        - `mappings` (list) — per-dataset definitions; supports `.exists(m, ...)`

        quantifier. Each `m` exposes:

        - `m.dataset.id` (int) — dataset id

        - `m.dataset.label` (string) — dataset label (available without

        `expand`); matches the `dataset.record.label` returned in the body

        - `m.path.field` (string)

        - `m.path.path` (string)

        - `m.origin.id` (int, null for Metric) — dataset where the mapping

        was originally declared. Equals `m.dataset.id` when declared

        directly on that dataset; differs when inherited from upstream.

        - `m.origin.label` (string, null for Metric) — label of the origin

        dataset; guard with `m.origin != null` before accessing.

        - `m.createdBy.id` (int, null for Metric)


        ### Available CEL functions


        The tag CEL environment registers the CEL standard

        definitions

        (operators, `in`, `?:`, `size()`, `string.contains`, `string.startsWith`,

        `string.endsWith`, `matches`, etc.) plus the following extension

        libraries from

        cel-go v0.28.0:


        - `ext.Strings` — `charAt`, `indexOf`, `join`, `lowerAscii`, `replace`, `split`, `substring`, `trim`, `upperAscii`, `format`

        - `ext.Lists` — `lists.flatten`, `lists.range`, `lists.slice`

        - `ext.Math` — `math.greatest`, `math.least`

        - `ext.Sets` — `sets.contains`, `sets.equivalent`, `sets.intersects`

        - `ext.Regex` — `re.capture`, `re.extract`

        - `ext.Encoders` — `base64.encode`, `base64.decode`

        - `ext.Bindings` — `cel.bind` for let-binding sub-expressions

        - `ext.Protos` — protobuf helpers

        - `cel.OptionalTypes` — `optional.of`, `optional.ofNonZero`, `optional.none`


        ### Defaults


        - Default page size: 50; maximum: 100.

        - Default order: `kind` ascending, then `name` ascending.


        Set `expand=true` to inline the `dataset.record` brief (label,

        description, iconUrl, contentType) on every dataset reference.


        Set `sampleValues=true` to attach a bounded sample of each tag''s

        values (see the `sampleValues` parameter).'
      operationId: ListDatasetTags
      tags:
      - Tags
      parameters:
      - name: filter
        in: query
        required: false
        description: 'CEL expression that response tags must match. Must evaluate to

          `bool`. Must be URL-encoded. See the operation description for

          available fields.

          '
        schema:
          type: string
        examples:
          byNameRegex:
            summary: Tags whose name matches a regex
            value: name.matches("^env.*")
          byExactName:
            summary: Tags with an exact name
            value: name == "service"
          correlationOnDataset:
            summary: Correlation tags defined on dataset 41000123
            value: kind == "Correlation" && mappings.exists(m, m.dataset.id == 41000123)
          anyTagOnDataset:
            summary: Any tag (either kind) defined on a particular dataset
            value: mappings.exists(m, m.dataset.id == 41000123)
          byDatasetNameSubstring:
            summary: Tags whose dataset name contains a substring (case-insensitive)
            value: mappings.exists(m, m.dataset.label.lowerAscii().contains("orders"))
          byDatasetNameRegex:
            summary: Tags on datasets whose name matches a regex
            value: mappings.exists(m, m.dataset.label.matches("(?i)^orders"))
          declaredDirectly:
            summary: Correlation tags declared directly on a dataset (not inherited)
            value: kind == "Correlation" && mappings.exists(m, m.origin != null && m.origin.id == m.dataset.id)
          inheritedFromUpstream:
            summary: Correlation tags inherited from a different upstream dataset
            value: kind == "Correlation" && mappings.exists(m, m.origin != null && m.origin.id != m.dataset.id)
          inheritedFromSpecificDataset:
            summary: Correlation tags inherited specifically from dataset 41000999
            value: mappings.exists(m, m.origin != null && m.origin.id == 41000999 && m.dataset.id != 41000999)
      - name: orderBy
        in: query
        required: false
        description: 'CSV CEL expressions; default `kind,name`. Prefix an item with `-`

          for descending. Supported expressions evaluate to comparable values

          (e.g. `name`, `kind`, `datasetCount`).

          '
        schema:
          type: string
        example: kind,name
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ExpandParam'
      - name: sampleValues
        in: query
        required: false
        description: 'When `true`, each returned tag includes up to 20 sample values in

          `sampleValues`. This is a bounded, non-paginated sample, NOT the

          full value set. Sampling is best-effort: `sampleValues` may be

          empty or absent for a tag whose values could not be retrieved.

          Use `GET /v1/tags/values` to search across tag values.

          '
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Tags retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag-ListResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse-400'
        '401':
          $ref: '#/components/responses/ErrorResponse-401'
        '403':
          $ref: '#/components/responses/ErrorResponse-403'
        '429':
          $ref: '#/components/responses/ErrorResponse-429'
        5XX:
          $ref: '#/components/responses/ErrorResponse-5XX'
    servers:
    - url: https://{customerid}.observeinc.com
      description: US west server
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
    - url: https://{customerid}.{cluster}.observeinc.com
      description: Specific regional cluster (prod)
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
        cluster:
          enum:
          - eu-1
          - ap-1
          default: eu-1
          description: For regional clusters, choose one.
    - url: https://{customerid}.{domain}.com
      description: Specific Observe server
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
        domain:
          default: OBSERVE_DOMAIN
          description: The Observe domain for your instance.
components:
  parameters:
    ExpandParam:
      name: expand
      in: query
      description: Whether to expand resources referenced in the response to include additional fields
      schema:
        type: boolean
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip before starting to collect the result set
      schema:
        type: integer
        format: int64
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return in the response
      schema:
        type: integer
        format: int64
  schemas:
    DatasetRef:
      title: DatasetRef
      type: object
      description: 'A reference to a dataset. Always carries the id; the optional `record` field carries the brief metadata, populated when expand=true. Mirrors ObjectRef (see ObjectRef / ObjectBrief in this file).

        '
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        record:
          $ref: '#/components/schemas/DatasetBrief'
    DatasetBrief:
      title: DatasetBrief
      type: object
      description: 'Brief record fields for a DatasetRef (label, description, iconUrl, contentType). Field naming mirrors ObjectBrief in this same file (iconUrl, not icon) for consistency across reference-brief pairs.

        '
      required:
      - label
      - description
      - iconUrl
      - contentType
      properties:
        label:
          type: string
        description:
          type: string
        iconUrl:
          type: string
        contentType:
          $ref: '#/components/schemas/DatasetContentType'
          description: 'The type of data the referenced dataset contains — Resource, Log,

            Metric, OTelSpan, OTelTrace, or Unknown. Derived from the dataset''s

            kind and interface bindings.

            '
    Meta:
      description: List Response Metadata
      type: object
      required:
      - totalCount
      properties:
        totalCount:
          description: 'The total number of resources available, independent of pagination.

            The API may return -1 if the total count is unknown or cannot be computed

            in reasonable time.

            '
          type: integer
          format: int64
    Tag-Resource:
      title: TagObject
      type: object
      description: 'A tag (correlation or metric) along with every dataset that defines

        it. Tags are identified by `(name, kind)`; there is no ObjectId for

        a tag — `name` is the natural identifier within a kind.

        '
      required:
      - name
      - kind
      - datasetCount
      - mappings
      properties:
        name:
          type: string
          description: Tag name. Natural identifier within `kind`.
        kind:
          $ref: '#/components/schemas/TagKind'
        datasetCount:
          type: integer
          format: int64
          description: Number of distinct datasets in which this tag is defined.
        mappings:
          type: array
          description: 'Per-dataset definitions of the tag. Always populated; use the

            `mappings.exists(m, m.dataset.id == ...)` CEL quantifier to

            filter tags scoped to a specific dataset.


            Limited to 20 entries.

            '
          items:
            $ref: '#/components/schemas/Tag-Mapping'
        sampleValues:
          type: array
          description: 'Up to 20 sample values observed for this tag, scoped to the

            datasets the caller can view. Present only when the request sets

            `sampleValues=true`. This is a bounded, non-paginated sample, NOT

            the full value set; it may be empty or absent when values could

            not be retrieved. Use `GET /v1/tags/values` to search values.

            '
          items:
            type: string
    Tag-ListResponse:
      title: TagListResponse
      type: object
      required:
      - tags
      - meta
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag-Resource'
        meta:
          $ref: '#/components/schemas/Meta'
    Dataset-FieldPath:
      title: FieldPath
      type: object
      required:
      - field
      - path
      properties:
        field:
          type: string
        path:
          type: string
    ObjectId:
      type: string
      format: ObjectId
    User:
      title: User
      type: object
      required:
      - id
      properties:
        id:
          title: User Identifier
          $ref: '#/components/schemas/ObjectId'
        label:
          title: User Label
          type: string
        timezone:
          type: string
        locale:
          type: string
    TagKind:
      title: TagKind
      type: string
      enum:
      - Metric
      - Correlation
      description: Kind of tag.
    DatasetContentType:
      title: DatasetContentType
      type: string
      description: 'The type of data a dataset contains. For Resource datasets, this is

        determined by the dataset kind. For other kinds, it is derived from the

        dataset''s interface bindings. Returns Unknown if no recognized interface

        is found.

        '
      enum:
      - Unknown
      - Resource
      - Log
      - Metric
      - OTelSpan
      - OTelTrace
    ErrorMessage:
      type: object
      properties:
        type:
          type: string
          description: A stable, machine-readable identifier for the kind of error.
        message:
          type: string
          description: Error message
      required:
      - type
      - message
    Tag-Mapping:
      title: TagMapping
      type: object
      description: 'A single per-dataset definition of a tag.

        '
      required:
      - dataset
      - path
      - origin
      - discoveryRuleAlias
      - createdBy
      properties:
        dataset:
          $ref: '#/components/schemas/DatasetRef'
        path:
          $ref: '#/components/schemas/Dataset-FieldPath'
        origin:
          anyOf:
          - $ref: '#/components/schemas/DatasetRef'
          - type: 'null'
          description: 'The dataset in which this mapping was originally declared. When

            the tag was declared directly on `dataset`, `origin.id` equals

            `dataset.id`. When the tag was inherited from an upstream

            dataset, `origin` points to that upstream dataset. Only

            meaningful for `kind=Correlation`; always `null` for

            `kind=Metric`. Mirrors the GraphQL `TagSourceInfo.origin`

            convention.

            '
        discoveryRuleAlias:
          type:
          - string
          - 'null'
          description: 'The discovery rule alias that created this mapping, or `null` when

            the mapping was not created by a discovery rule. Only meaningful

            for `kind=Correlation`; always `null` for `kind=Metric`. If the tag

            is inherited from an upstream dataset, this field points to the

            discovery rule alias that created the mapping on the origin

            dataset.

            '
        createdBy:
          anyOf:
          - $ref: '#/components/schemas/User'
          - type: 'null'
          description: 'User who declared this mapping on `origin`. Only meaningful for

            `kind=Correlation`; always `null` for `kind=Metric`.

            '
  responses:
    ErrorResponse-400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-5XX:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-429:
      description: Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: 'Authorization: Bearer <customerid> <apitoken>

        '
x-refined-from:
- observeinc-openapi-assembled.json
- observeinc-openapi.yml