# Query agent metric

URL: https://docs.dixa.io/openapi/dixa-api/beta/intelligence/postintelligenceagentsmetricsmetricid

Get the value of an agent metric for a period. All aggregates of the metric are returned. If nothing matches, `count` is 0 and the other aggregates are null, except presence durations, which are 0. Deactivated agents are included.

## POST /beta/intelligence/agents/metrics/{metricId}

- Server: https://dev.dixa.io
- Auth: `Authorization: <API token>` header

### Request example

agentPresenceDuration · Interval · Whole organization:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/metrics/agentPresenceDuration' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primaryFilter": {
    "period": {
      "interval": {
        "from": "2026-06-01T00:00:00Z",
        "to": "2026-07-01T00:00:00Z"
      }
    }
  },
  "timezone": "Europe/Copenhagen"
}'
```

agentPresenceDuration · Preset · One agent, no presence:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/metrics/agentPresenceDuration' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primaryFilter": {
    "period": {
      "preset": "PreviousWeek"
    }
  },
  "filters": [
    {
      "attribute": "agent",
      "values": [
        "a4f1c0b2-6d38-4e91-8f27-1b5d9c3e7a04"
      ],
      "operator": "IsOne"
    }
  ],
  "timezone": "Europe/Copenhagen"
}'
```

agentAssignmentReasons · Interval · One queue and team, with a breakdown:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/metrics/agentAssignmentReasons' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primaryFilter": {
    "period": {
      "interval": {
        "from": "2026-06-01T00:00:00Z",
        "to": "2026-07-01T00:00:00Z"
      }
    }
  },
  "filters": [
    {
      "attribute": "queue",
      "values": [
        "2f9b6d51-38c4-4a72-9e15-7c8b3f6a2d90"
      ],
      "operator": "IsOne"
    },
    {
      "attribute": "team",
      "values": [
        "9d2f7b31-4c68-4e13-b590-8a3f1d7c6e29"
      ],
      "operator": "IsOne"
    }
  ],
  "timezone": "Europe/Copenhagen"
}'
```

agentOffersTimedOut · Interval · One agent, phone only:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/metrics/agentOffersTimedOut' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primaryFilter": {
    "period": {
      "interval": {
        "from": "2026-06-01T00:00:00Z",
        "to": "2026-07-01T00:00:00Z"
      }
    }
  },
  "filters": [
    {
      "attribute": "agent",
      "values": [
        "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415"
      ],
      "operator": "IsOne"
    },
    {
      "attribute": "channel",
      "values": [
        "PstnPhone"
      ],
      "operator": "IsOne"
    }
  ],
  "timezone": "Europe/Copenhagen"
}'
```

agentClaims · Interval · Conversations from an id onward:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/metrics/agentClaims' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primaryFilter": {
    "period": {
      "interval": {
        "from": "2026-06-01T00:00:00Z",
        "to": "2026-07-01T00:00:00Z"
      }
    }
  },
  "filters": [
    {
      "attribute": "conversation",
      "values": [
        "8123000"
      ],
      "operator": "GreaterThanOrEqual"
    }
  ],
  "timezone": "Europe/Copenhagen"
}'
```

### Response examples

#### 200 The metric values, keyed by aggregate name

agentPresenceDuration · Interval · Whole organization:

```json
{
  "data": {
    "working": {
      "durationMs": 18420000,
      "availability": {
        "email": 18420000,
        "chat": 18420000,
        "message": 12300000,
        "speak": 0
      }
    },
    "away": {
      "durationMs": 5400000,
      "byStatus": [
        {
          "customAwayStatus": {
            "id": "3c6f2a18-8d47-4b93-a05e-2f7c9b1d6a38",
            "label": "Lunch"
          },
          "durationMs": 1800000
        },
        {
          "durationMs": 3600000
        }
      ]
    }
  }
}
```

agentPresenceDuration · Preset · One agent, no presence:

```json
{
  "data": {
    "working": {
      "durationMs": 0,
      "availability": {
        "email": 0,
        "chat": 0,
        "message": 0,
        "speak": 0
      }
    },
    "away": {
      "durationMs": 0,
      "byStatus": []
    }
  }
}
```

agentAssignmentReasons · Interval · One queue and team, with a breakdown:

```json
{
  "data": {
    "transferOffers": 9,
    "claims": 17,
    "count": 120,
    "queueOffers": 84,
    "bulkActions": 4,
    "outboundConversations": 6
  }
}
```

agentOffersTimedOut · Interval · One agent, phone only:

```json
{
  "data": {
    "count": 23
  }
}
```

agentClaims · Interval · Conversations from an id onward:

```json
{
  "data": {
    "count": 31
  }
}
```

#### 400

```json
{
  "message": "Decoding failure in request"
}
```

#### 404 An entity in this request could not be found

```json
{
  "message": "The requested resource could not be found"
}
```

#### 500 Internal failure during request processing

```json
{
  "message": "There was an internal server error while processing the request"
}
```

## OpenAPI definition

The operation and the schemas used, from the full spec at https://docs.dixa.io/openapi-specs/dixa-beta.yaml. Request and response examples are above.

```yaml
openapi: 3.0.3
info:
  title: Dixa API
  version: beta
servers:
  - url: https://dev.dixa.io
security:
  - ApiKeyAuth: []
paths:
  /beta/intelligence/agents/metrics/{metricId}:
    post:
      tags:
        - Intelligence
      summary: Query agent metric
      description: Get the value of an agent metric for a period. All aggregates of
        the metric are returned. If nothing matches, `count` is 0 and the other
        aggregates are null, except presence durations, which are 0. Deactivated
        agents are included.
      operationId: postIntelligenceAgentsMetricsMetricid
      parameters:
        - name: metricId
          in: path
          description: The id of an agent metric
          required: true
          schema:
            type: string
          examples:
            agentPresenceDuration · Interval · Whole organization:
              value: agentPresenceDuration
            agentPresenceDuration · Preset · One agent, no presence:
              value: agentPresenceDuration
            agentAssignmentReasons · Interval · One queue and team, with a breakdown:
              value: agentAssignmentReasons
            agentOffersTimedOut · Interval · One agent, phone only:
              value: agentOffersTimedOut
            agentClaims · Interval · Conversations from an id onward:
              value: agentClaims
      requestBody:
        description: The query
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AgentMetricDataRequest"
        required: true
      responses:
        "200":
          description: The metric values, keyed by aggregate name
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntelligenceMetricValues"
        "400":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
        "404":
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFound"
        "500":
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    AgentMetricDataRequest:
      title: AgentMetricDataRequest
      description: An agent metric query
      type: object
      required:
        - primaryFilter
        - timezone
      properties:
        primaryFilter:
          $ref: "#/components/schemas/AgentPrimaryFilter"
        filters:
          description: The filters to apply. All filters must match
          type: array
          items:
            $ref: "#/components/schemas/SecondaryFilter"
        timezone:
          description: The timezone presets and days are evaluated in, such as
            `Europe/Copenhagen`
          type: string
    AgentPrimaryFilter:
      title: AgentPrimaryFilter
      description: The period to query
      type: object
      required:
        - period
      properties:
        period:
          $ref: "#/components/schemas/Period"
    Period:
      title: Period
      description: 'A period, given as either a preset, `{"preset": "Last7Days"}`, or
        an interval, `{"interval": {"from": "2026-06-01T00:00:00Z", "to":
        "2026-06-30T23:59:59.999Z"}}`'
      oneOf:
        - $ref: "#/components/schemas/IntervalPeriod"
        - $ref: "#/components/schemas/PresetPeriod"
    IntervalPeriod:
      title: IntervalPeriod
      description: A period between two points in time
      type: object
      required:
        - interval
      properties:
        interval:
          $ref: "#/components/schemas/IntelligenceInterval"
    IntelligenceInterval:
      title: IntelligenceInterval
      description: A time range. Both ends are ISO 8601 timestamps that must end in
        `Z` or a UTC offset, such as `2026-06-01T00:00:00Z` or
        `2026-06-01T00:00:00+02:00`
      type: object
      required:
        - from
        - to
      properties:
        from:
          description: The start of the range, inclusive. Must be before `to`
          type: string
          format: date-time
        to:
          description: The end of the range, inclusive
          type: string
          format: date-time
    PresetPeriod:
      title: PresetPeriod
      description: A preset period, evaluated in the timezone of the query
      type: object
      required:
        - preset
      properties:
        preset:
          description: >-
            The preset. The available presets are:


            - `Today` and `Yesterday`

            - `Last{Unit}` or `Previous{Unit}`: the previous full unit, e.g.
            `PreviousWeek`

            - `Last{N}{Unit}s`: for N of 2 or more, the last N units, including
            the current one, e.g. `Last7Days`. With N of 1 it is the same as
            `Previous{Unit}`

            - `This{Unit}`: the current unit so far, for `Week`, `Month`,
            `Quarter` or `Year`, e.g. `ThisMonth`


            The units are `Hour`, `Day`, `Week`, `Month`, `Quarter` and `Year`
          type: string
    SecondaryFilter:
      title: SecondaryFilter
      description: A filter on an attribute
      type: object
      required:
        - attribute
      properties:
        attribute:
          description: The attribute to filter on, from the `filters` of the metric or
            record. Any other attribute is rejected
          type: string
        values:
          description: The values to filter on, as returned by List filter values. Send an
            empty list for `IsEmpty` and `IsNotEmpty`
          type: array
          items:
            type: string
        operator:
          description: The operator. Defaults to the `defaultOperator` of the attribute.
            An operator the attribute does not support is rejected
          type: string
          enum:
            - IsEmpty
            - IsNotEmpty
            - IsOne
            - IsNotOne
            - IsAll
            - GreaterThan
            - GreaterThanOrEqual
            - LessThan
            - LessThanOrEqual
    IntelligenceMetricValues:
      title: IntelligenceMetricValues
      type: object
      required:
        - data
      properties:
        data:
          description: The metric values, keyed by the `name` of each of the metric's
            `aggregates`. All aggregates are included. If nothing matches,
            `count` is 0, `min`, `max`, `sum`, `average`, `stdDev` and
            `percentage` are null, and an object value is filled with zeros
          type: object
          additionalProperties: {}
    BadRequest:
      title: BadRequest
      type: object
      required:
        - message
      properties:
        message:
          type: string
    NotFound:
      title: NotFound
      type: object
      required:
        - message
      properties:
        message:
          type: string
    ServerError:
      title: ServerError
      type: object
      required:
        - message
      properties:
        message:
          type: string
```