# Get Co-Sell Dashboard / Insights

`GET https://api.suger.cloud/org/{orgId}/cosell/metric`

Retrieve co-sell analytics for the organization. The response shape depends on the `page` query param:
- (page omitted): legacy 12-month overview (Overview + CntMonthly only; a different schema from the page-specific responses below)
- performance: aggregate KPIs over the period (pipeline, win rate, etc.) — pass `page=performance` explicitly
- actions: outstanding referrals needing user action
- logs: time-ordered execution log (returns ListOperationsResponse, not CosellDashboardData)

Time window controlled by `period` (7d, 30d default, quarter, year, or `custom_<YYYY-MM-DD>_<YYYY-MM-DD>` for an explicit range). On the logs page, further narrow with `partner` (AWS / AZURE / GCP), `action`, `status` (Temporal workflow status: Running/Completed/Failed/Canceled/Terminated/ContinuedAsNew/TimedOut — NOT the Fours referral status enum), and `search` (free text or UUID).

Use this when: user asks for co-sell KPIs, pipeline summary, or recent activity.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `contactId` | query | string | no | Optional contact ID to filter referrals (legacy mode) |
| `page` | query | string | no | Dashboard page: performance (default), actions, logs |
| `period` | query | string | no | Time period: 7d, 30d (default), quarter, year |
| `nocache` | query | boolean | no | Bypass cache and force fresh data |
| `action` | query | string | no | Filter by cosell action type (logs page only, e.g. AutoCreate) |
| `partner` | query | string | no | Filter by cloud partner (logs page only, e.g. AWS) |
| `status` | query | string | no | Filter by Temporal execution status (logs page only). One of: Running, Completed, Failed, Canceled, Terminated, ContinuedAsNew, TimedOut. |
| `search` | query | string | no | Search referrals by name, external ID, or UUID (logs page only) |
| `offsetToken` | query | string | no | Pagination cursor for the logs page; echo the token from the previous response to fetch the next page |
| `pageSize` | query | integer | no | Page size (logs page only). 1–100, default 50. |

## Responses

### 200 — OK

Content-Type: `application/json` · Schema: `CosellDashboardData`

**`CosellDashboardData`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | CosellActionsData | no |  |
| `closedWon` | CosellClosedWonSummary | no |  |
| `cntMonthly` | array<CosellMonthlyTrend> | no |  |
| `overview` | CosellOverview | no |  |
| `providerMetrics` | array<CosellProviderMetric> | no |  |
| `tcvMonthly` | array<CosellMonthlyTCV> | no |  |
| `topContacts` | array<CosellTopContact> | no |  |
| `trends` | array<CosellTrendBucket> | no |  |

**`CosellActionsData`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actionRequired` | array<CosellActionReferral> | no |  |
| `duplicates` | CosellDuplicateSummary | no |  |
| `failureReasons` | array<CosellFailureReason> | no |  |
| `pendingAcceptance` | array<CosellActionReferral> | no |  |

**`CosellClosedWonSummary`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mainCurrencyRevenue` | CosellRevenueMetric | no |  |
| `otherCurrencyRevenue` | array<CosellRevenueMetric> | no |  |
| `providerCounts` | array<CosellProviderCount> | no |  |
| `totalCount` | integer | no |  |
| `trendDelta` | integer | no |  |

**`CosellMonthlyTrend`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inboundCount` | integer | no |  |
| `month` | string | no |  |
| `outboundCount` | integer | no |  |
| `total` | integer | no |  |

**`CosellOverview`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activeCount` | integer | no |  |
| `avgPerDay` | string | no |  |
| `closedLostCount` | integer | no |  |
| `closedWonCount` | integer | no |  |
| `inboundWinRate` | string | no |  |
| `outboundWinRate` | string | no |  |
| `tcv` | array<CosellTCVByCurrency> | no |  |
| `totalCount` | integer | no |  |
| `winRate` | string | no |  |
| `winRateTrend` | string | no |  |
| `yoyGrowthRate` | string | no |  |

**`CosellProviderMetric`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lostCount` | integer | no |  |
| `partner` | string | no |  |
| `totalCount` | integer | no |  |
| `winRate` | string | no |  |
| `winRateTrend` | string | no |  |
| `wonCount` | integer | no |  |

**`CosellMonthlyTCV`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no |  |
| `tcv` | array<CosellTCVByMonth> | no |  |

**`CosellTopContact`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactId` | string | no |  |
| `name` | string | no |  |
| `partner` | string | no |  |
| `referrals` | integer | no |  |
| `winRate` | string | no |  |
| `wonCount` | integer | no |  |

**`CosellTrendBucket`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no |  |
| `lostCount` | integer | no |  |
| `referralCount` | integer | no |  |
| `wonCount` | integer | no |  |

**`CosellActionReferral`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string | no |  |
| `direction` | string | no |  |
| `externalId` | string | no |  |
| `id` | string | no |  |
| `name` | string | no |  |
| `partner` | string | no |  |
| `stage` | string | no |  |
| `status` | string | no |  |

**`CosellDuplicateSummary`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | array<CosellDuplicateGroup> | no |  |
| `totalDuplicates` | integer | no |  |

**`CosellFailureReason`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentId` | string | no | AgentID is unused and always empty. It referenced the legacy AI agent registry, which was deleted in PR 7849; nothing writes or reads this field. Retained only to avoid a breaking shape change to the published SDK. |
| `count` | integer | no |  |
| `errorMessage` | string | no |  |
| `referrals` | array<CosellFailureRef> | no |  |

### 500 — Internal server error

Content-Type: `application/json` · Schema: `ErrorResponse`

**`ErrorResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | ErrorCode | no |  |
| `info` | object | no |  |
| `message` | string | no |  |

## Example

_Generated from this operation's schema. Values are placeholders — substitute your own ids, and set `SUGER_TOKEN` to a bearer token from the [OAuth client-credentials exchange](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X GET 'https://api.suger.cloud/org/{orgId}/cosell/metric' \
  -H "Authorization: Bearer $SUGER_TOKEN"
```

### Response — 200

```json
{
  "actions": {
    "actionRequired": [
      {
        "account": "string",
        "direction": "string",
        "externalId": "01H0000000000000000000",
        "id": "01H0000000000000000000",
        "name": "Acme Corp",
        "partner": "string",
        "stage": "string",
        "status": "string"
      }
    ],
    "duplicates": {
      "groups": [
        {
          "crmId": "01H0000000000000000000",
          "crmType": "string",
          "duplicates": [],
          "primary": {},
          "reason": "string"
        }
      ],
      "totalDuplicates": 1
    },
    "failureReasons": [
      {
        "agentId": "01H0000000000000000000",
        "count": 1,
        "errorMessage": "string",
        "referrals": [
          {}
        ]
      }
    ],
    "pendingAcceptance": [
      {
        "account": "string",
        "direction": "string",
        "externalId": "01H0000000000000000000",
        "id": "01H0000000000000000000",
        "name": "Acme Corp",
        "partner": "string",
        "stage": "string",
        "status": "string"
      }
    ]
  },
  "closedWon": {
    "mainCurrencyRevenue": {
      "avgDealSize": 100,
      "currency": "USD",
      "totalAmount": 100
    },
    "otherCurrencyRevenue": [
      {
        "avgDealSize": 100,
        "currency": "USD",
        "totalAmount": 100
      }
    ],
    "providerCounts": [
      {
        "count": 1,
        "partner": "string"
      }
    ],
    "totalCount": 1,
    "trendDelta": 1
  },
  "cntMonthly": [
    {
      "inboundCount": 1,
      "month": "string",
      "outboundCount": 1,
      "total": 1
    }
  ],
  "overview": {
    "activeCount": 1,
    "avgPerDay": "string",
    "closedLostCount": 1,
    "closedWonCount": 1,
    "inboundWinRate": "string",
    "outboundWinRate": "string",
    "tcv": [
      {
        "activeAmount": 100,
        "currency": "USD",
        "totalAmount": 100
      }
    ],
    "totalCount": 1,
    "winRate": "string",
    "winRateTrend": "string",
    "yoyGrowthRate": "string"
  },
  "providerMetrics": [
    {
      "lostCount": 1,
      "partner": "string",
      "totalCount": 1,
      "winRate": "string",
      "winRateTrend": "string",
      "wonCount": 1
    }
  ],
  "tcvMonthly": [
    {
      "month": "string",
      "tcv": [
        {
          "currency": "USD",
          "totalAmount": 100
        }
      ]
    }
  ],
  "topContacts": [
    {
      "contactId": "01H0000000000000000000",
      "name": "Acme Corp",
      "partner": "string",
      "referrals": 1,
      "winRate": "string",
      "wonCount": 1
    }
  ],
  "trends": [
    {
      "date": "2026-01-31T12:00:00Z",
      "lostCount": 1,
      "referralCount": 1,
      "wonCount": 1
    }
  ]
}
```

### Error — 500

```json
{
  "code": "InternalServerError",
  "message": "string"
}
```

---

API reference: https://doc.fours.com/api/