TwentyDEV icon

TwentyDEV

Consume the Twenty API
Join our community

Actions252

Overview

This node operation "Find Many Opportunities" allows users to query and retrieve multiple opportunity records from an external service via its API. It supports filtering, sorting, pagination, and controlling the depth of related nested objects included in the response.

Common scenarios where this node is beneficial include:

  • Fetching a list of sales or business opportunities based on specific criteria.
  • Retrieving paginated results for display in dashboards or reports.
  • Extracting opportunities with related data (e.g., associated contacts or accounts) up to a specified nesting level.
  • Sorting opportunities by fields such as creation date or status.

Practical example: A sales manager wants to get all open opportunities sorted by expected close date, limited to 50 records per request, including related account information but no further nested relations.

Properties

Name Meaning
Order By Specifies how to sort the returned opportunities. Format: field_name_1,field_name_2[DIRECTION_2],.... Directions can be AscNullsFirst, AscNullsLast, DescNullsFirst, DescNullsLast. Default direction is AscNullsFirst. Example: createdAt,priorityDescNullsLast sorts first by creation date ascending, then priority descending with nulls last. Default is id.
Filter Filters the opportunities returned. Format: field[COMPARATOR]:value pairs separated by commas. Supports comparators like eq, neq, in, containsAny, is, gt, gte, lt, lte, startsWith, like, ilike. Logical conjunctions or, and, not can be used for complex filters. Examples: status[eq]:open, amount[gte]:10000. Default excludes opportunities with id 0000....
Limit Limits the number of opportunities returned in one request. Default is 60.
Depth Controls how many levels of related nested objects are included in the response:
- 0: Only primary opportunity data.
- 1: Primary opportunity plus directly related objects.
- 2: Primary, directly related, and their related objects.
Default is 1.
Starting After Cursor-based pagination: returns opportunities starting after the specified cursor value. Cursors are found in startCursor and endCursor fields in the response's pageInfo.
Ending Before Cursor-based pagination: returns opportunities ending before the specified cursor value. Cursors are found in startCursor and endCursor fields in the response's pageInfo.

Output

The node outputs JSON data containing an array of opportunity objects matching the query parameters. Each opportunity object includes fields as defined by the API schema, potentially including nested related objects depending on the Depth parameter.

The output JSON typically contains:

  • An array of opportunity records under a main data field.
  • Pagination info such as cursors (startCursor, endCursor) inside a pageInfo object to support cursor-based pagination.
  • Opportunity fields vary but generally include identifiers, names, statuses, dates, amounts, and any related entities included per the depth setting.

No binary data output is indicated for this operation.

Dependencies

  • Requires an API key credential for authenticating requests to the external Twenty API service.
  • The base URL for the API is configured dynamically from credentials.
  • The node uses standard HTTP headers for JSON content type and accepts JSON responses.
  • No additional environment variables are explicitly required beyond the API authentication setup.

Troubleshooting

  • Empty results: Check that the filter syntax is correct and matches existing data. Also verify pagination cursors if using starting_after or ending_before.
  • Invalid filter or order_by format: The API expects specific formats for these strings; ensure comparators and directions are valid and properly formatted.
  • Authentication errors: Confirm that the API key credential is correctly configured and has necessary permissions.
  • Pagination issues: Using invalid or expired cursors for starting_after or ending_before may cause errors or empty responses.
  • Depth too high: Requesting very deep nested objects (depth=2) might increase response size and latency; consider lowering depth if performance issues occur.

Links and References

Discussion