> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequentum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get aggregate run counts for an agent

> Returns the total number of Runs for an Agent together with a breakdown by `RunStatus`,
counted across both current Runs and Run history.

Use this instead of counting the response of `GET /api/v1/agent/{agentId}/runs`. That
endpoint returns at most `maxRecords` Runs — 50 by default — so counting it reports the
cap rather than the real total for any Agent that has run more often than the limit.

**Reading the breakdown**

- Each entry carries the numeric `status`, its `statusName`, and the `count`.
- Statuses with no Runs are omitted rather than reported as zero.
- `Failure` and `Failed` are distinct statuses, as are `Completed` and `Success`. Add the
  pairs together if you want a single failed or succeeded figure.



## OpenAPI

````yaml GET /api/v1/agent/{agentId}/runs/summary
openapi: 3.0.4
info:
  title: Sequentum Cloud API
  description: API endpoints for Sequentum Cloud
  version: v1
servers: []
security:
  - ApiKey: []
    Bearer: []
paths:
  /api/v1/agent/{agentId}/runs/summary:
    get:
      tags:
        - ApiAgent
      summary: Get aggregate run counts for an agent
      description: >-
        Returns the total number of Runs for an Agent together with a breakdown
        by `RunStatus`,

        counted across both current Runs and Run history.


        Use this instead of counting the response of `GET
        /api/v1/agent/{agentId}/runs`. That

        endpoint returns at most `maxRecords` Runs — 50 by default — so counting
        it reports the

        cap rather than the real total for any Agent that has run more often
        than the limit.


        **Reading the breakdown**


        - Each entry carries the numeric `status`, its `statusName`, and the
        `count`.

        - Statuses with no Runs are omitted rather than reported as zero.

        - `Failure` and `Failed` are distinct statuses, as are `Completed` and
        `Success`. Add the
          pairs together if you want a single failed or succeeded figure.
      parameters:
        - name: agentId
          in: path
          description: The id of the agent
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Returns the total number of Runs and the per-status breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunSummaryApiModel'
        '400':
          description: If the request is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: If the API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: If the Agent is not found or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl https://dashboard.sequentum.com/api/v1/agent/289/runs/summary \
              -H "Authorization: ApiKey $SEQUENTUM_API_KEY"

            # => {
            #      "totalCount": 395,
            #      "statusCounts": [
            #        { "status": 9, "statusName": "Completed", "count": 272 },
            #        { "status": 7, "statusName": "Failed",    "count": 72  },
            #        { "status": 8, "statusName": "Stopped",   "count": 51  }
            #      ]
            #    }
        - lang: node
          label: Node.js
          source: >-
            const res = await
            fetch("https://dashboard.sequentum.com/api/v1/agent/289/runs/summary",
            {
              headers: {
                "Authorization": `ApiKey ${process.env.SEQUENTUM_API_KEY}`,
              },
            });


            const summary = await res.json();

            console.log(`${summary.totalCount} runs total`);


            for (const s of summary.statusCounts) {
              console.log(`  ${s.statusName}: ${s.count}`);
            }
        - lang: python
          label: Python
          source: |-
            import os
            import requests

            response = requests.get(
                "https://dashboard.sequentum.com/api/v1/agent/289/runs/summary",
                headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
            )
            response.raise_for_status()
            summary = response.json()

            print(f"{summary['totalCount']} runs total")
            for s in summary["statusCounts"]:
                print(f"  {s['statusName']}: {s['count']}")
components:
  schemas:
    AgentRunSummaryApiModel:
      type: object
      properties:
        totalCount:
          type: integer
          description: >-
            Total number of runs for the agent, across current runs and run
            history
          format: int32
        statusCounts:
          type: array
          items:
            $ref: '#/components/schemas/AgentRunStatusCountApiModel'
          description: Run counts broken down by run status
          nullable: true
      additionalProperties: false
      description: Aggregate run counts for an agent
    BadRequestError:
      type: object
      properties:
        statusCode:
          type: integer
          format: int32
        statusDescription:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
          readOnly: true
        severity:
          $ref: '#/components/schemas/ErrorSeverity'
        errorCode:
          type: string
          description: >-
            Optional machine-readable error code. When present, clients should
            switch on this

            value rather than parsing
            Sequentum.Enterprise.Core.ControllerError.Message. The controller
            pipeline serialises

            with System.Text.Json, which ignores the Newtonsoft attribute below,
            so an unset code

            reaches the client as `"errorCode": null` rather than being omitted
            - clients

            must treat null and absent alike.
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    AgentRunStatusCountApiModel:
      type: object
      properties:
        status:
          type: integer
          description: The RunStatus value
          format: int32
        statusName:
          type: string
          description: The RunStatus name, for example Completed, Failed or Stopped
          nullable: true
        count:
          type: integer
          description: Number of runs with this status
          format: int32
      additionalProperties: false
      description: Number of runs that ended in one particular status
    ErrorSeverity:
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
      type: integer
      description: >-
        `0` = `Error`; `1` = `Unexpected`; `2` = `Fatal`; `3` = `Warning`; `4` =
        `Info`
      format: int32
  securitySchemes:
    ApiKey:
      type: apiKey
      description: >-
        API Key authorization header. Example: "Authorization: ApiKey
        {your-api-key}"
      name: Authorization
      in: header
    Bearer:
      type: http
      description: 'OAuth 2.0 Bearer token. Example: "Authorization: Bearer {access-token}"'
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.