Skip to main content
Creates many records of one Salesforce object in a single call and returns a result for every record you sent: its new ID, or the error for that row. Display name “Salesforce Bulk Create”. Off by default. Use it instead of calling salesforce_create_record once per record whenever there is more than one to write. One call writes them all, and the per-record results mean a partial write cannot be mistaken for a complete one.

​
Authentication and enablement

Needs an active Salesforce integration in the workspace. The access token and the org’s instance_url are injected from that integration. The connected user needs create permission on the object. Off by default. Enable it per agent.

​
Inputs

  • object — required. Salesforce object API name, e.g. VI_Line_Item__c.
  • records — required. A JSON array string. Each element is an object of field API names to values, exactly like the fields argument of Salesforce Create Record. Send every record you need written in one call. Example: [{"Name__c":"Line 1","Amount__c":100},{"Name__c":"Line 2","Amount__c":250}]. At most 2000 records per call; every record needs at least one field.
  • all_or_none — optional, default false. When false, records that pass are created and the ones that fail are reported individually. When true, a failure rolls back the other records in the same batch of 200.
records is a JSON string rather than an array of objects for the same reason the other Salesforce write tools take fields as a string: the element would have to be a property-less object, which Gemini function-calling rejects.

​
Output

Structured result: requested_count, created_count, failed_count, all_or_none, record_ids[], warnings[], completed_at, and results[] with one entry per requested record — index (its position in records), record_id, success, error. When every record lands, the summary reads Created N of N …. When any did not, the summary starts with PARTIAL:, gives the shortfall, and names the first few row errors. A partial run is still a success result, not an error: the records that were created really exist, and an error result would invite a retry that duplicates them. Read created_count against requested_count before treating the export as complete.

​
Limits and side effects

  • Creates records only; never updates or deletes.
  • Salesforce caps its sObject Collections endpoint at 200 records per request, so a larger call is sent as several requests of 200. Record order and index are preserved across them.
  • With all_or_none: true and more than 200 records, the rollback covers each batch separately, not the whole call. The tool adds a warning saying so rather than implying a guarantee it cannot give.
  • The bulk insert is never retried automatically. A create is not idempotent, and the shared HTTP client retries on timeouts and 5xx, which on this endpoint would re-send up to 200 records that Salesforce may already have committed. One failed call you can investigate beats 200 silent duplicates.
  • If one request fails outright (network, 5xx, an expired session), the tool stops. results still holds exactly one row per record you requested, in one of three states:
    • created — success: true with a record_id.
    • rejected — Salesforce answered and refused the row. Nothing was written; fix it and send it again.
    • unknown — the request carrying this row failed in flight, so Salesforce may have committed it. unknown_count counts these. Check in Salesforce before re-sending; a blind retry can duplicate them.
    • not attempted — the run stopped before the row was sent. Safe to send again as-is.
  • If nothing was created at all — whether the request failed in flight or Salesforce accepted it and rejected every row — the result is an error carrying status: "limitation", so the step records a failure rather than a completed run that wrote nothing. It is a limitation, not an ordinary error, so the platform hands it back to the agent instead of retrying: an in-flight batch may already be committed, and an all-rows-rejected batch would be rejected identically.

​
Expected errors

  • no Salesforce access token was provided… / no Salesforce instance_url was provided… — no active integration, or it needs reconnecting.
  • records is required and must be a JSON array string…, records must contain at least one record, record N is empty…, records has N entries; at most 2000… — validation; nothing was written.
  • salesforce returned N results for M records; cannot match ids to records — a malformed reply. That batch is reported as unknown, not as failed: the request reached Salesforce and may have been committed.
  • Per-row failures are not call errors. They appear in results[].error with Salesforce’s own code and fields, e.g. FIELD_CUSTOM_VALIDATION_EXCEPTION: Amount is required (fields: Amount__c).
  • salesforce session expired or invalid…, salesforce API request limit exceeded… — operational.