Skip to main content

Aircover Pipeline

A Python script that pulls a list of meetings from the Aircover API for a date range and runs a coaching agent template against each one.

What this does

  1. Authenticates to the Aircover API.
  2. Calls GET /analytics/ to fetch every meeting in the requested date range (auto-chunked into 3-month windows; results deduplicated).
  3. For each meeting, calls GET /transcript/coaching with a chosen template id and writes the agent's structured output to a JSON file.

Output structure (under --output-dir):

out/
├── meetings.json                  # raw meeting list from /analytics
├── agent-outputs/
│   ├── agent_<meeting_id>.json    # one file per processed meeting
│   └── ...
├── failures.json                  # only if any rows failed; lists meeting ids
└── summary.json                   # totals per run

Requirements

  • Python 3.10 or newer
  • requests (installed via requirements.txt)
  • An Aircover account with API access

Setup

Three equivalent ways to install. Pick whichever fits your workflow.

Pip into a virtualenv (most common):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Pip install (registers an aircover-pipeline command on your PATH):

python3 -m venv .venv
source .venv/bin/activate
pip install .
# Now you can run from anywhere:
aircover-pipeline --list-templates

Makefile shortcuts (for those who prefer make):

make install              # creates .venv and installs deps
make list-templates       # lists templates
make run ARGS='--start 2026-01-01 --end 2026-03-31 \
               --template-id <id> --output-dir ./out'
make dry-run ARGS='--start 2026-01-01 --end 2026-03-31 \
                   --template-id <id> --output-dir ./out'
make clean                # removes venv and output dirs

Authentication

Two ways to authenticate. Pick whichever applies to your Aircover account.

⚠️ Don't pass credentials as CLI flags. --username, --password, --access-token, and --refresh-token work for ad-hoc testing but leak to shell history, process listings, and CI logs. For anything beyond a one-off, put credentials in .env (gitignored) or pass them via environment variables.

Option A — Username + password

Best for accounts that log in directly to Aircover (not via SSO).

cp .env.example .env
# Edit .env and set:
#   AIRCOVER_USERNAME=your-username@your-company.com
#   AIRCOVER_PASSWORD=your-password

The script will read .env automatically.

Option B — Bearer token (SSO-only accounts)

If your Aircover account logs in via SSO (Google, Okta, etc.), /auth/login will reject your password. Paste a bearer token from the web app instead:

  1. Open https://app.aircover.ai and sign in via SSO.

  2. Open browser dev tools (F12 or Cmd+Opt+I).

  3. Go to Application → Local Storage → https://app.aircover.ai.

  4. Find the entry containing authInfo (or access_token / refresh_token directly). It's a JSON blob; copy the values of access_token and refresh_token.

  5. Put them in .env:

    AIRCOVER_ACCESS_TOKEN=eyJhbGciOi...
    AIRCOVER_REFRESH_TOKEN=eyJhbGciOi...
    

    Or pass them on the command line via --access-token / --refresh-token.

The refresh token typically lives ~60 days. The access token lives ~1 hour and is auto-refreshed by the script as long as the refresh token is set.

Security

.env is in .gitignore and will not be committed. The refresh token is long-lived and grants the same permissions as a full login session — treat it like a password.

Usage

1. Find a coaching template id

python aircover_pipeline.py --list-templates

Output:

Available coaching templates (3):
  My QBR Template
    id: WVrzuxuavDAQttxogZaHfZ

  Customer Health Check
    id: a1B2c3D4e5F6g7H8i9J0kL
  ...

2. Run the pipeline

python aircover_pipeline.py \
  --start 2026-01-01 --end 2026-03-31 \
  --template-id WVrzuxuavDAQttxogZaHfZ \
  --output-dir ./out

3. Test on a small batch first

python aircover_pipeline.py \
  --start 2026-01-01 --end 2026-03-31 \
  --template-id WVrzuxuavDAQttxogZaHfZ \
  --output-dir ./out \
  --limit 5

When combined with --resume, --limit N means "process up to N new meetings this run" — already-done rows are skipped first, then the limit is applied to what remains. So --limit 10 --resume always processes up to 10 new meetings, regardless of how many were already finished in prior runs.

4. Resume after a crash

If the run stops partway through (timeout, network blip, etc.), re-run with --resume. It will skip any meetings that already have an output file and only process the remaining ones. Atomic writes mean a half-written file from a crash will not be mistaken for completed work.

python aircover_pipeline.py ... --resume

5. Filter the meeting list

# Drop meetings whose deal_id starts with one of these domains
--exclude-domains example.com,internal.test

# Keep only meetings whose notes_sent_to includes one of these emails
--filter-emails alice@your-company.com,bob@your-company.com

# Keep only meetings whose team_ids includes at least one of these team IDs
--filter-teams 1,3,7

6. Point at a different API environment

By default the script talks to https://api.aircover.ai. Override via --base-url or AIRCOVER_BASE_URL for staging/sandbox environments:

# CLI
python aircover_pipeline.py --base-url https://stageapi.aircover.ai ...

# Or in .env
AIRCOVER_BASE_URL=https://stageapi.aircover.ai

Useful if Aircover provisioned you a staging tenant for testing integrations before going live against production data.

7. Print version

python aircover_pipeline.py --version
# → aircover-pipeline 1.0.3

Same value is recorded in every summary.json as package_version for audit trails.

8. Dry-run preview

Pull the meeting list and apply filters, but skip the coaching calls. Lets you see how many meetings would be processed before committing the time.

python aircover_pipeline.py \
  --start 2026-01-01 --end 2026-03-31 \
  --template-id <id> --output-dir ./out \
  --dry-run

Output: meetings.json and summary.json (with dry_run: true). No agent-outputs/.

Output schema

The output files follow a stable schema. The schema_version field in summary.json will be bumped if the field set or semantics change in a breaking way. As of 1.0:

meetings.json

[
  {
    "id": "meeting_id_here",
    "deal_id": "<prospect-domain>/<id>",
    "team_ids": "12, 34",
    "date": "2026-03-15",
    "notes_sent_to": "alice@example.com, bob@example.com"
  }
]

agent-outputs/agent_<meeting_id>.json

{
  "meeting_id": "...",
  "deal_id": "...",
  "date": "2026-03-15",
  "template_id": "WVrzuxuavDAQttxogZaHfZ",
  "properties": {
    "<property_id>": {
      "title": "Pain Points",
      "result": "Customer mentioned ...",
      "score": 4,
      "max_score": 5
    },
    ...
  }
}

summary.json

{
  "schema_version": "1.0",
  "package_version": "1.0.3",
  "ran_at": "2026-05-31T16:30:00+00:00",
  "start": "2026-01-01",
  "end": "2026-03-31",
  "template_id": "...",
  "base_url": "https://api.aircover.ai",
  "filters": {
    "exclude_domains": null,
    "filter_emails": null,
    "filter_teams": null,
    "limit": null
  },
  "meetings_in_window": 120,
  "processed_this_run": 120,
  "success": 115,
  "failed": 5,
  "skipped_resume": 0
}

When --dry-run is used, summary.json also includes "dry_run": true and omits the success / failed / processed_this_run fields.

Formal JSON Schemas

Machine-readable JSON Schema files for each output type are in schemas/:

File Validates
schemas/meetings-1.0.json meetings.json
schemas/agent-output-1.0.json agent-outputs/agent_<meeting_id>.json
schemas/summary-1.0.json summary.json
schemas/failures-1.0.json failures.json

Use them to validate output programmatically in your downstream pipeline. Example with Python's jsonschema package:

pip install jsonschema
import json
from jsonschema import validate

with open("out/meetings.json") as f:
    meetings = json.load(f)
with open("schemas/meetings-1.0.json") as f:
    schema = json.load(f)

validate(meetings, schema)  # raises ValidationError on schema mismatch

The schema_version field in summary.json indicates which schema family this run conforms to. Breaking changes to the output structure will increment this version and ship new *-2.0.json schemas alongside the old ones, so you can migrate on your own timeline.

failures.json (only when any rows failed)

[
  {"meeting_id": "...", "deal_id": "...", "date": "..."},
  ...
]

Exit codes

Code Meaning
0 All attempted rows succeeded (or no meetings to process)
1 Partial failure — some rows succeeded, some failed; see failures.json
2 Auth/setup error, all /analytics/ chunks failed, OR every attempted row failed
3 Uncaught exception / interrupted (Ctrl+C)

Useful for cron / CI integration: a 0 is clean, a 1 means investigate failures.json, a 2 means look at logs and fix something before re-running, a 3 means the script crashed — file a bug.

Common issues

Symptom Likely cause
401 Unauthorized on every meeting Access token expired and no refresh token. Re-grab tokens from web app or use username/password auth.
Empty meetings.json even with valid date range Your account doesn't have access to any meetings in that window. Check the date range and your account's permissions.
404 Not Found on /analytics/ Your account doesn't have access to that endpoint. Talk to your Aircover contact.
HTTP 500 {"errors":["Unable to read deal"]} for some rows Meeting exists but has no Salesforce deal linked. Expected for internal meetings or pre-SFDC meetings; safe to ignore.
Per-row Coaching call failed log lines Either the meeting has no transcript, or your token can't access that meeting's organization. The row is recorded in failures.json.

Verbose logging

Pass --verbose to enable debug-level logs. Useful for diagnosing per-meeting failures.

Running tests

make test
# or directly:
pip install -e ".[test]"
pytest tests/ -v

71 unit tests cover credential loading (env vars / .env file / kwargs precedence), token refresh + re-login fallback, 401 retry, 5xx/429 retry with Retry-After honoring, malformed-JSON tolerance on every endpoint, atomic write semantics, date-format validation, meeting response parsing, date-range chunking, distinguishing all-chunks-failed from empty window, the three CLI filter helpers, end-to-end --limit/--resume ordering, and summary.json audit metadata. No real HTTP — all networking is mocked.

Support

Questions or issues: support@aircover.ai.

When reporting a problem, include:

  • The exact command you ran (redact tokens / passwords).
  • The relevant output (with --verbose if a particular row failed).
  • The contents of summary.json and failures.json if relevant.

License

MIT. See LICENSE.txt.

Metadata

Release files for aircover-pipeline 1.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aircover-pipeline 1.0.3
File Size Uploaded Provenance Actions
aircover_pipeline-1.0.3.tar.gz 30.3 kB With provenance Details for aircover_pipeline-1.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aircover-pipeline 1.0.3
File Interpreter ABI Platform Actions
aircover_pipeline-1.0.3-py3-none-any.whl Python 3 none any Details for aircover_pipeline-1.0.3-py3-none-any.whl

Total release size: 50.0 kB

Release files / aircover_pipeline-1.0.3.tar.gz

Download URL aircover_pipeline-1.0.3.tar.gz
Size 30.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9b519a2c3b31498bda961ac570204de27c3daf93e38bc68cc7703e49263158cd
BLAKE2b-256 checksum
How to use checksums
0ba7fcc03ec4a45d13a114e673579aae35cdc8e648f8110611588fc366c62486
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.

Transparency log

Release files / aircover_pipeline-1.0.3-py3-none-any.whl

Download URL aircover_pipeline-1.0.3-py3-none-any.whl
Size 19.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e1a4cb6e7736ab4f54dc7b384e241f5ac2287f6a384e72eeec56dd761bde5e9c
BLAKE2b-256 checksum
How to use checksums
7cfa4c40a3f4ee3af073ef283f4d3d2140819f2fcb0c624ada677fc67a513663
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.

Transparency log

Security for aircover-pipeline 1.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aircover_pipeline-1.0.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page