# Query agent records

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

Get the rows of an agent record for a period. To get the next page, send the same query with `meta.next` as `pagination.pageKey`. Without filters, all agents are included, also deactivated ones.

## POST /beta/intelligence/agents/records/{recordId}

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

### Request example

agentPresenceDuration · Interval · Two agents:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/records/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"
      }
    }
  },
  "filters": [
    {
      "attribute": "agent",
      "values": [
        "a4f1c0b2-6d38-4e91-8f27-1b5d9c3e7a04",
        "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415"
      ],
      "operator": "IsOne"
    }
  ],
  "timezone": "Europe/Copenhagen",
  "pagination": {
    "pageLimit": 50
  },
  "includeLabels": true
}'
```

agentPresenceDuration · Preset · Every agent, no labels:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/records/agentPresenceDuration' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primaryFilter": {
    "period": {
      "preset": "PreviousWeek"
    }
  },
  "timezone": "Europe/Copenhagen",
  "includeLabels": false
}'
```

agentPresenceDuration · Interval · A deactivated agent, nothing in the period:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/records/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"
      }
    }
  },
  "filters": [
    {
      "attribute": "agent",
      "values": [
        "e6b2a704-3f19-4d82-9c5b-4a8e1f2d7c36"
      ],
      "operator": "IsOne"
    }
  ],
  "timezone": "Europe/Copenhagen"
}'
```

agentOffers · Interval · Two agents, conversations up to an id:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/records/agentOffers' \
  -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": [
        "a4f1c0b2-6d38-4e91-8f27-1b5d9c3e7a04",
        "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415"
      ],
      "operator": "IsOne"
    },
    {
      "attribute": "conversation",
      "values": [
        "8123500"
      ],
      "operator": "LessThanOrEqual"
    }
  ],
  "timezone": "Europe/Copenhagen",
  "pagination": {
    "pageLimit": 2
  }
}'
```

agentAssignmentReasons · Interval · One agent in one queue:

```bash
curl -X POST 'https://dev.dixa.io/beta/intelligence/agents/records/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": "agent",
      "values": [
        "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415"
      ],
      "operator": "IsOne"
    },
    {
      "attribute": "queue",
      "values": [
        "2f9b6d51-38c4-4a72-9e15-7c8b3f6a2d90"
      ],
      "operator": "IsOne"
    }
  ],
  "timezone": "Europe/Copenhagen"
}'
```

### Response examples

#### 200 One page of rows, and the keys of the previous and next pages

agentPresenceDuration · Interval · Two agents:

```json
{
  "data": [
    {
      "working": true,
      "availableOnSpeak": false,
      "endedAt": "2026-06-18T12:30:00+00:00",
      "availableOnMessage": true,
      "agent": {
        "id": "a4f1c0b2-6d38-4e91-8f27-1b5d9c3e7a04",
        "label": "Joe Bloggs"
      },
      "simultaneousRing": false,
      "availableOnChat": true,
      "availableOnEmail": true,
      "startedAt": "2026-06-18T08:00:00+00:00"
    },
    {
      "working": false,
      "availableOnSpeak": false,
      "availableOnMessage": false,
      "agent": {
        "id": "a4f1c0b2-6d38-4e91-8f27-1b5d9c3e7a04",
        "label": "Joe Bloggs"
      },
      "simultaneousRing": false,
      "availableOnChat": false,
      "customAwayStatus": {
        "id": "3c6f2a18-8d47-4b93-a05e-2f7c9b1d6a38",
        "label": "Lunch"
      },
      "endedAt": "2026-06-18T13:00:00+00:00",
      "availableOnEmail": false,
      "startedAt": "2026-06-18T12:30:00+00:00"
    }
  ],
  "meta": {
    "pageLimit": 50
  }
}
```

agentPresenceDuration · Preset · Every agent, no labels:

```json
{
  "data": [
    {
      "working": true,
      "availableOnSpeak": false,
      "endedAt": "2026-06-16T16:00:00+00:00",
      "availableOnMessage": true,
      "agent": {
        "id": "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415"
      },
      "simultaneousRing": false,
      "availableOnChat": false,
      "availableOnEmail": true,
      "startedAt": "2026-06-16T08:30:00+00:00"
    },
    {
      "working": false,
      "availableOnSpeak": false,
      "availableOnMessage": false,
      "agent": {
        "id": "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415"
      },
      "simultaneousRing": false,
      "availableOnChat": false,
      "customAwayStatus": {
        "id": "3c6f2a18-8d47-4b93-a05e-2f7c9b1d6a38"
      },
      "endedAt": "2026-06-16T16:45:00+00:00",
      "availableOnEmail": false,
      "startedAt": "2026-06-16T16:00:00+00:00"
    }
  ],
  "meta": {
    "pageLimit": 50
  }
}
```

agentPresenceDuration · Interval · A deactivated agent, nothing in the period:

```json
{
  "data": [],
  "meta": {
    "pageLimit": 50
  }
}
```

agentOffers · Interval · Two agents, conversations up to an id:

```json
{
  "data": [
    {
      "channel": {
        "id": "Email",
        "label": "Email"
      },
      "offeredAt": "2026-06-18T09:14:05.2+00:00",
      "queue": {
        "id": "2f9b6d51-38c4-4a72-9e15-7c8b3f6a2d90",
        "label": "Support"
      },
      "tags": [
        {
          "id": "5e7a9c13-2f84-4b60-9d31-6c8a5e2f7b04",
          "label": "vip"
        }
      ],
      "isPreferredAgent": false,
      "offerType": {
        "id": "Standard",
        "label": "Standard"
      },
      "agent": {
        "id": "a4f1c0b2-6d38-4e91-8f27-1b5d9c3e7a04",
        "label": "Joe Bloggs"
      },
      "contactPoint": {
        "id": "support@example.com"
      },
      "isPersonalOffer": false,
      "conversationId": 8123456,
      "initialDirection": {
        "id": "Inbound",
        "label": "Inbound"
      }
    },
    {
      "channel": {
        "id": "PstnPhone",
        "label": "Phone"
      },
      "offeredAt": "2026-06-18T12:05:44.9+00:00",
      "queue": {
        "id": "7ac3e8f4-1b92-4d05-8637-9f2c4a8e1b63",
        "label": "Billing"
      },
      "isPreferredAgent": true,
      "offerType": {
        "id": "PreferredAgent",
        "label": "Preferred Agent"
      },
      "agent": {
        "id": "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415",
        "label": "Amara Okafor"
      },
      "contactPoint": {
        "id": "+18889100777"
      },
      "isPersonalOffer": true,
      "conversationId": 8123490,
      "initialDirection": {
        "id": "Inbound",
        "label": "Inbound"
      }
    }
  ],
  "meta": {
    "next": "eyJ0aW1lc3RhbXAiOiIyMDI2LTA2LTE4VDEyOjA1OjQ0LjkwMFoiLCJzZWNvbmRhcnlLZXkiOiI4MTIzNDkwIiwiYWRkaXRpb25hbEtleXMiOlsiNDUwMiJdLCJsaW1pdCI6MiwiZGlyZWN0aW9uIjoibmV4dCJ9",
    "pageLimit": 2
  }
}
```

agentAssignmentReasons · Interval · One agent in one queue:

```json
{
  "data": [
    {
      "channel": {
        "id": "PstnPhone",
        "label": "Phone"
      },
      "queue": {
        "id": "2f9b6d51-38c4-4a72-9e15-7c8b3f6a2d90",
        "label": "Support"
      },
      "conversationCreatedAt": "2026-06-18T12:05:41.3+00:00",
      "assignedAt": "2026-06-18T12:06:02+00:00",
      "contactPoint": {
        "id": "+18889100777"
      },
      "agent": {
        "id": "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415",
        "label": "Amara Okafor"
      },
      "reason": {
        "id": "OfferAccepted",
        "label": "Queue offers"
      },
      "conversationId": 8123490,
      "initialDirection": {
        "id": "Inbound",
        "label": "Inbound"
      }
    },
    {
      "channel": {
        "id": "Email",
        "label": "Email"
      },
      "queue": {
        "id": "2f9b6d51-38c4-4a72-9e15-7c8b3f6a2d90",
        "label": "Support"
      },
      "assignedAt": "2026-06-19T10:31:17.8+00:00",
      "contactPoint": {
        "id": "support@example.com"
      },
      "conversationCreatedAt": "2026-06-19T10:02:50+00:00",
      "tags": [
        {
          "id": "b3c81f6d-7a95-4e28-8c40-1f6b9d3a5e72",
          "label": "refund"
        }
      ],
      "agent": {
        "id": "c81d4e2a-95b7-4c60-a3f8-2e6a7d09b415",
        "label": "Amara Okafor"
      },
      "reason": {
        "id": "ConversationClaimed",
        "label": "Claims"
      },
      "conversationId": 8123533,
      "initialDirection": {
        "id": "Inbound",
        "label": "Inbound"
      }
    }
  ],
  "meta": {
    "pageLimit": 50
  }
}
```

#### 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/records/{recordId}:
    post:
      tags:
        - Intelligence
      summary: Query agent records
      description: Get the rows of an agent record for a period. To get the next page,
        send the same query with `meta.next` as `pagination.pageKey`. Without
        filters, all agents are included, also deactivated ones.
      operationId: postIntelligenceAgentsRecordsRecordid
      parameters:
        - name: recordId
          in: path
          description: The id of an agent record
          required: true
          schema:
            type: string
          examples:
            agentPresenceDuration · Interval · Two agents:
              value: agentPresenceDuration
            agentPresenceDuration · Preset · Every agent, no labels:
              value: agentPresenceDuration
            agentPresenceDuration · Interval · A deactivated agent, nothing in the period:
              value: agentPresenceDuration
            agentOffers · Interval · Two agents, conversations up to an id:
              value: agentOffers
            agentAssignmentReasons · Interval · One agent in one queue:
              value: agentAssignmentReasons
      requestBody:
        description: The query
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AgentRecordDataRequest"
        required: true
      responses:
        "200":
          description: One page of rows, and the keys of the previous and next pages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntelligenceRecordPage"
        "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:
    AgentRecordDataRequest:
      title: AgentRecordDataRequest
      description: An agent record 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
        pagination:
          $ref: "#/components/schemas/PageRequest"
        includeLabels:
          description: Whether references include a `label`. Defaults to true
          type: boolean
    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
    PageRequest:
      title: PageRequest
      description: The page to fetch. If not provided, the first page is returned
      type: object
      properties:
        pageKey:
          description: The key of the page to fetch, taken from `meta.next` or
            `meta.previous` in a previous response
          type: string
        pageLimit:
          description: The number of rows per page, up to 200
          default: 50
          type: integer
          format: int32
          minimum: 1
          maximum: 200
    IntelligenceRecordPage:
      title: IntelligenceRecordPage
      type: object
      required:
        - meta
      properties:
        data:
          description: The rows of the page. The columns a row can contain are listed
            under `fields` in the record's catalogue entry
          type: array
          items:
            description: A row, keyed by the `name` of each of the record's `fields`.
              Columns without a value are left out, so rows can have different
              keys
            type: object
            additionalProperties: {}
        meta:
          $ref: "#/components/schemas/PageResponse"
    PageResponse:
      title: PageResponse
      description: The keys of the previous and next pages, and the page size
      type: object
      required:
        - pageLimit
      properties:
        previous:
          description: The key of the previous page. Not set on the first page
          type: string
        next:
          description: The key of the next page. Not set on the last page
          type: string
        pageLimit:
          description: The page size used
          type: integer
          format: int32
    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
```