> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airweave.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server.

# Run Sync

POST https://api.airweave.ai/source-connections/{source_connection_id}/run

Trigger a data synchronization job for a source connection.

Starts an asynchronous sync job that pulls the latest data from the connected
source. The job runs in the background and you can monitor its progress using
the jobs endpoint.

For continuous sync connections, this performs an incremental sync by default.
Use `force_full_sync=true` to perform a complete re-sync of all data.

Reference: https://docs.airweave.ai/api-reference/source-connections/run-source-connections-source-connection-id-run-post

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /source-connections/{source_connection_id}/run:
    post:
      operationId: run-source-connections-source-connection-id-run-post
      summary: Run Sync
      description: >-
        Trigger a data synchronization job for a source connection.


        Starts an asynchronous sync job that pulls the latest data from the
        connected

        source. The job runs in the background and you can monitor its progress
        using

        the jobs endpoint.


        For continuous sync connections, this performs an incremental sync by
        default.

        Use `force_full_sync=true` to perform a complete re-sync of all data.
      tags:
        - source-connections
      parameters:
        - name: source_connection_id
          in: path
          description: Unique identifier of the source connection to sync (UUID)
          required: true
          schema:
            type: string
            format: uuid
        - name: force_full_sync
          in: query
          description: >-
            Force a full sync ignoring cursor data. Only applies to continuous
            sync connections. Non-continuous connections always perform full
            syncs.
          required: false
          schema:
            type: boolean
            default: false
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Created sync job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionJob'
        '404':
          description: Source Connection Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '409':
          description: Sync Already Running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
servers:
  - url: https://api.airweave.ai
    description: Production
  - url: http://localhost:8001
    description: Local
components:
  schemas:
    SyncJobStatus:
      type: string
      enum:
        - created
        - pending
        - running
        - completed
        - failed
        - cancelling
        - cancelled
      description: Sync job status enum.
      title: SyncJobStatus
    SourceConnectionErrorCategory:
      type: string
      enum:
        - oauth_credentials_expired
        - api_key_invalid
        - auth_provider_account_gone
        - auth_provider_credentials_invalid
        - usage_limit_exceeded
        - rate_limited
      description: Error categories for credential/auth failures on source connections.
      title: SourceConnectionErrorCategory
    SourceConnectionJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the sync job
        source_connection_id:
          type: string
          format: uuid
          description: ID of the source connection this job belongs to
        status:
          $ref: '#/components/schemas/SyncJobStatus'
          description: >-
            Current status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, or
            CANCELLING
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the job started execution (ISO 8601)
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the job finished (ISO 8601). Null if still running.
        duration_seconds:
          type:
            - number
            - 'null'
          format: double
          description: Total execution time in seconds. Null if still running.
        entities_inserted:
          type: integer
          default: 0
          description: Number of new entities created during this sync
        entities_updated:
          type: integer
          default: 0
          description: Number of existing entities updated during this sync
        entities_deleted:
          type: integer
          default: 0
          description: Number of entities removed during this sync
        entities_failed:
          type: integer
          default: 0
          description: Number of entities that failed to process
        error:
          type:
            - string
            - 'null'
          description: Error message if the job failed
        error_category:
          oneOf:
            - $ref: '#/components/schemas/SourceConnectionErrorCategory'
            - type: 'null'
          description: >-
            Error category for credential errors (e.g.
            oauth_credentials_expired)
        error_details:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          description: Additional error context for debugging
      required:
        - id
        - source_connection_id
        - status
      description: >-
        A sync job representing a single synchronization run.


        Sync jobs track the execution of data synchronization from a source
        connection.

        Each job includes timing information, entity counts, and error details
        if applicable.
      title: SourceConnectionJob
    NotFoundErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what was not found
      required:
        - detail
      description: Response returned when a resource is not found (HTTP 404).
      title: NotFoundErrorResponse
    ConflictErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing the conflict
      required:
        - detail
      description: >-
        Response returned when a resource conflict occurs (HTTP 409).


        This typically occurs when attempting to create a resource that already
        exists,

        or when an operation cannot be completed due to the current state of a
        resource.
      title: ConflictErrorResponse
    ValidationErrorLocItems:
      oneOf:
        - type: string
        - type: integer
      title: ValidationErrorLocItems
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      title: HTTPValidationError
    RateLimitErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message explaining the rate limit
      required:
        - detail
      description: >-
        Response returned when rate limit is exceeded (HTTP 429).


        The API enforces rate limits to ensure fair usage. When exceeded,

        wait for the duration specified in the Retry-After header before
        retrying.
      title: RateLimitErrorResponse
  securitySchemes:
    default:
      type: apiKey
      in: header
      name: x-api-key

```

## Examples



**Response**

```json
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "source_connection_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "started_at": "2024-03-15T12:00:00Z",
  "completed_at": "2024-03-15T12:05:32Z",
  "duration_seconds": 332.5,
  "entities_inserted": 45,
  "entities_updated": 12,
  "entities_deleted": 3,
  "entities_failed": 0
}
```

**SDK Code**

```python
import requests

url = "https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run"

headers = {"x-api-key": "<apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```typescript
import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({ apiKey: "YOUR_API_KEY" });
await client.sourceConnections.run("550e8400-e29b-41d4-a716-446655440000", {
    force_full_sync: false
});

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.airweave.ai/source-connections/550e8400-e29b-41d4-a716-446655440000/run")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```