---
title: "Start Mosaic CSV healing"
method: POST
path: "/v1/mosaic/start"
tags: ["Repair Data"]
---

# Start Mosaic CSV healing

`POST /v1/mosaic/start`

Starts an asynchronous Mosaic job that heals and enriches an arbitrary CSV, TXT, XLSX, or public Google Sheet. Pass a public HTTPS URL (Google Drive / Sheets, Dropbox, OneDrive, or a direct file link). The file is securely fetched and stored before processing. Credits are charged inside the background job after the file is parsed (based on row count and selected options). The first Mosaic run for an organization may be a free trial (first 1,000 rows free; overage billed against normal credits). Use the polling endpoint with the returned run ID to retrieve status and download links.

<span>⚡ <strong>Rate limit:</strong> 20 requests per 1 minute</span>

<span>💰 <strong>Cost:</strong> Credits are charged after the file is parsed inside the background job. Cost is based on the number of billable rows plus any optional enrichments (contact details, company details) you enable. The first Mosaic run for an organization may be a free trial (first 1,000 rows free; overage billed against normal credits).&nbsp;<span title="Pricing shown is default pricing. Actual pricing may vary. Final charge depends on parsed row count and the options you select.">ⓘ</span></span>

## Request body

- object
  - `apiKey` string, required — Your Fiber API key
  - `sourceUrl` string, uri, required — HTTPS URL of the input file. Supported formats: CSV, TXT (one LinkedIn profile URL per line), XLSX, or a public Google Sheet. You may also pass a public Google Drive file link, Dropbox share link, or OneDrive / SharePoint share link. The link must be publicly accessible (e.g. Google Sheets / Drive: "Anyone with the link can view"; Dropbox / OneDrive: link allows direct download) or the fetch will fail. Google Sheets export the first tab only. For XLSX workbooks we auto-detect the most likely worksheet and header row; if detection is unavailable we use the sheet with the most rows and treat row 1 as the header. Maximum file size is 50 MiB. The file is securely fetched and stored before processing.
  - `customInstructions` string, nullable — Optional additional instructions for the AI on top of our system prompt — not a replacement for it. Use this to steer enrichment when your file needs extra context. Examples: "I really want personal emails but I don't care about phones"; "These are all doctors — make sure you get office phones, not home phones".
  - `options` object, nullable — Feature toggles that control billing and enrichment (contact info, company details, live fetch, redline, max rows).
    - `contactInfo` object, nullable — Which kinds of contact info to reveal per row — work email, personal email, and/or phone — independently selectable. Omit to skip contact reveal entirely. When enabled, adds the matching contact-reveal operation(s) per billable row.
      - `getWorkEmails` boolean
      - `getPersonalEmails` boolean
      - `getPhoneNumbers` boolean
    - `includeCompanyDetails` boolean — When true, enriches each person's current employer with funding, offices, headcount, and related company fields. Adds the company lookup operation per billable row.
    - `liveFetch` boolean — When true, runs live profile fetch and web-search slug recovery when the enrichment plan calls for it. Bundled into the base Mosaic row charge — no separate operation. When false, the engine skips gated live-fetch steps only.
    - `runRedline` boolean — When true, compares enriched output against your input columns to flag staleness or mismatches. No separate billing operation.
    - `maxRows` integer, nullable — Cap how many input rows are processed and billed for this run (maximum 20,000). Useful for trial runs or cost control.

## Response `200`

Default Response

- object
  - `output` object, required
    - `runId` string, required — Unique Mosaic run ID. Poll /mosaic/poll with this ID to check status and retrieve results.
    - `isFreeTrialRun` boolean, required — True when this run used the organization's one-time free Mosaic trial. The first 1,000 rows are free; rows beyond that are billed against normal credits.
  - `chargeInfo` union, required
    - object — Credits were charged immediately for this operation
      - `method` 'charged-now', required
      - `creditsCharged` number, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits will be charged after the operation completes
      - `method` 'charging-later', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits that were charged for an asynchronous operation
      - `method` 'charged-for-async-process', required
      - `creditsCharged` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — No credits were charged for this operation
      - `method` 'free', required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
    - object — Credits were refunded for this operation
      - `method` 'credits-refunded', required
      - `creditsRefunded` number, required
      - `message` string, required
      - `lowCreditAlert` object, nullable — Contains a link to get more credits, a warning message, and the remaining credit count.
        - `getMoreCreditsUrl` string, uri, required — URL to top up credits or restart billing cycle to get fresh credits.
        - `message` string, required — Human-readable credits warning.
        - `availableCredits` number, required — Number of credits remaining in the current billing period.
  - `warnings` object[], nullable — Warnings about extraneous fields in request
    - `field` string, required — Full path to extraneous field (e.g., 'searchParams.ExtraField')
    - `message` string, required — Warning message
  - `advice` string[], nullable — Tips, recommendations, and suggestions for using this API effectively.

## Other responses

- `400` — Default Response
- `401` — Default Response
- `402` — Default Response
- `403` — Default Response
- `404` — Default Response
- `422` — Default Response
- `429` — Default Response
- `500` — Default Response
- `503` — Default Response

---

[API](https://skmtc.net/fiber/apis/fiber-ai-api.md) · [All operations](https://skmtc.net/fiber/apis/fiber-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiber/fiber-ai-api/revisions/720c63a313eb/schema)