Octave icon

Octave

Interact with the Octave V2 API

Actions26

Overview

The "Run Prospector" operation of the Agent resource allows users to initiate a prospecting process using a specified prospector agent. This node is designed to find and return contact or company data based on various targeting criteria such as company domain, job titles, personas, and playbooks. It is useful in sales, marketing, or recruitment automation workflows where identifying potential leads or contacts programmatically is needed.

Typical use cases include:

  • Automatically gathering contact information for companies by domain.
  • Targeting specific job titles or personas within organizations.
  • Running predefined playbooks to customize prospecting strategies.
  • Limiting the number of results and controlling the detail level of returned data.

For example, a user might run this node to find marketing decision-makers at a list of companies, specifying fuzzy or exact job titles, and then feed the results into an email outreach sequence.

Properties

Name Meaning
Agent OId Name or ID The unique identifier or name of the prospector agent to run. Must be selected from a loaded list or specified directly (supports expressions).
Company Domain Optional. The domain of the company to prospect (e.g., example.com). Limits the search to contacts related to this domain.
Limit Maximum number of results to return. If set to 0 or omitted, the agent's default limit applies.
Minimal Response Boolean flag indicating whether to return a minimal version of the contact data (true) or full details (false).
Playbook Name or ID Optional. Specifies a playbook to use during prospecting. Can be chosen from a list or specified by ID (supports expressions).
Persona Names or IDs Optional. One or more personas to target during prospecting. Selectable from a list or specified by IDs (supports expressions).
Fuzzy Titles Job titles for fuzzy matching, entered as a comma-separated string (e.g., "VP Marketing, Head of Sales"). Matches approximate titles.
Exact Titles Job titles for exact matching, entered as a comma-separated string. Only contacts with these exact titles are matched.
Exclude Titles Job titles to exclude from search results, entered as a comma-separated string. Contacts with these titles will be filtered out.
Additional Inputs (JSON) Optional JSON object containing any other top-level inputs the agent might accept. This JSON will be merged into the main request body, allowing for extended customization beyond predefined fields.

Output

The node outputs an array of JSON objects representing the prospecting results returned by the agent. Each item typically contains contact or company data according to the query parameters and the minimal/full response setting.

  • The json field includes the structured data about each prospect found.
  • If the minimal response option is enabled, the data will contain only essential fields; otherwise, it may include detailed contact information.
  • There is no indication that binary data is output by this node.

Dependencies

  • Requires an API key credential for authenticating with the Octave V2 API.
  • The node depends on external services provided by the Octave platform to perform prospecting.
  • Load options for agents, playbooks, and personas are dynamically fetched via internal methods, so proper API access and permissions are necessary.
  • No additional environment variables or n8n configurations are explicitly required beyond the API key setup.

Troubleshooting

  • Common issues:

    • Invalid or missing agent ID: Ensure the selected agent exists and the ID is correct.
    • API authentication errors: Verify the API key credential is valid and has sufficient permissions.
    • Malformed JSON in Additional Inputs: The JSON must be well-formed; otherwise, the request may fail.
    • Exceeding rate limits or result limits: Adjust the "Limit" property or check API usage quotas.

  • Error messages:

    • Errors from the API are caught and included in the output if "Continue On Fail" is enabled.
    • Parsing errors on API responses may occur if the response body is not valid JSON.
    • Network or timeout errors should be checked by verifying connectivity and API service status.

Links and References

Discussion