home / skills / abdullahbeam / nexus-design-abdullah / hubspot-list-deals

hubspot-list-deals skill

safe

/00-system/skills/hubspot/hubspot-list-deals

This skill lists HubSpot deals and returns paginated results to streamline monitoring and reporting of your pipeline.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-list-deals

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.3 KB

---
name: hubspot-list-deals
description: "List deals from HubSpot CRM. Load when user says 'list deals', 'show deals', 'show pipeline', 'get deals', 'hubspot deals'. Returns paginated deal list."
---

# List HubSpot Deals

**Specialized skill** for listing deals from HubSpot CRM.

## Pre-Flight Check

Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.

---

## Usage

### Basic List (default 10 deals)
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_deals.py --json
```

### With Limit
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_deals.py --limit 25 --json
```

### With Pagination
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_deals.py --after "cursor_value" --json
```

---

## Output Format

```json
{
  "results": [
    {
      "id": "5840795376",
      "properties": {
        "dealname": "Enterprise Deal",
        "amount": "50000",
        "dealstage": "qualifiedtobuy",
        "pipeline": "default",
        "closedate": "2025-03-15T00:00:00Z"
      },
      "url": "https://app.hubspot.com/contacts/.../record/0-3/5840795376"
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}
```

---

## Display Format

```
Found {count} deals:

1. Enterprise Deal
   Amount: $50,000
   Stage: Qualified to Buy
   Close Date: 2025-03-15
   ID: 5840795376

2. Startup Package
   Amount: $5,000
   Stage: Proposal Sent
   ...
```

---

## Common Deal Stages

| Stage ID | Name |
|----------|------|
| appointmentscheduled | Appointment Scheduled |
| qualifiedtobuy | Qualified to Buy |
| presentationscheduled | Presentation Scheduled |
| decisionmakerboughtin | Decision Maker Bought In |
| contractsent | Contract Sent |
| closedwon | Closed Won |
| closedlost | Closed Lost |

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.deals.read` scope |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-create-deal` - Create new deal
- `hubspot-search-deals` - Search by name/amount
- `hubspot-update-deal` - Update deal stage
- `hubspot-get-associations` - Get deal contacts

Overview

This skill lists deals from a HubSpot CRM instance and returns a paginated, machine-friendly list or a concise human display. It supports limit and cursor-based pagination and outputs core deal properties like name, amount, stage, pipeline, close date, and record URL. Use it to quickly inspect pipeline status and recent opportunities.

How this skill works

The skill calls HubSpot's Deals API to retrieve deal records using configured credentials and required scopes. It accepts parameters for limit and an "after" cursor to fetch subsequent pages, then formats results into a JSON payload with results and paging.next.after. It also provides a readable summary listing key fields for each deal.

When to use it

Quickly view current deals in a pipeline or overall CRM.
Paginate through many deals using cursor-based navigation.
Check deal stages and close dates for forecasting or follow-up.
Verify recent deal creation or large-value opportunities.
Integrate into workflows that need a short list of deals for review.

Best practices

Run the pre-flight config check to confirm credentials and scopes before use.
Request only the fields you need to reduce payload size and rate usage.
Use sensible limits (e.g., 10–50) and paginate for large datasets.
Handle 401/403/429 errors gracefully: refresh credentials, add missing scopes, or back off on retries.
Map stage IDs to readable names for display to non-technical users.

Example use cases

Show the next 10 deals in the default pipeline for a quick sales meeting snapshot.
Fetch 25 deals to export a short report of amounts and close dates.
Continue fetching pages using the returned 'after' cursor to build a full dataset.
Validate that a recent high-value deal appears in HubSpot and capture its record URL.
Audit deal stages to find opportunities stuck in a particular stage.

FAQ

What permissions are required?

The integration needs crm.objects.deals.read scope and valid HubSpot API credentials.

How do I get the next page of results?

Pass the paging.next.after value as the --after parameter to retrieve the next page.