> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/circleci/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Start with Pipelines + Insights metrics</strong></td><td>These two entities give you the most useful CI/CD picture immediately. Use Join to link them on project slug for a combined view of volume and performance.</td></tr><tr><td><strong>Use a dedicated API token</strong></td><td>Create a CircleCI personal API token specifically for Coupler.io rather than reusing a shared or personal token. This makes it easy to revoke access without breaking other integrations.</td></tr><tr><td><strong>Set a realistic start date</strong></td><td>For the initial sync, use a start date 30–90 days back rather than your full history. CircleCI's API pagination means large historical loads are slow, and you can always extend the window later.</td></tr><tr><td><strong>Combine multiple projects with Append</strong></td><td>If you manage several CircleCI projects, add multiple sources to a single data flow and use the Append transformation to unify pipeline or job data across all of them in one destination table.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Schedule based on your pipeline cadence</strong></td><td>If your team pushes code multiple times a day, an hourly or every-few-hours refresh keeps your dashboards current. For slower release cycles, daily is usually enough.</td></tr><tr><td><strong>Run Insights separately from pipeline data</strong></td><td>Insights metrics aggregate data on CircleCI's side and update less frequently than raw pipeline records. You can schedule Insights entities less often (e.g., daily) to avoid unnecessary API calls.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Scope to specific projects and workflows</strong></td><td>Use the Project ID and Workflow ID parameters to narrow your data pull. Fetching org-wide data across all workflows is much slower and returns more noise than you usually need.</td></tr><tr><td><strong>Use Aggregate for duration analysis</strong></td><td>Rather than exporting every raw job record, use Coupler.io's Aggregate transformation to pre-calculate average and p95 job durations grouped by workflow name or branch. This keeps your destination tables lean.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
**Don't confuse Project ID with project slug.** Some entities (like Specific projects) need the UUID-format Project ID from your project settings URL, while others accept the slug (e.g., `gh/myorg/myrepo`). Using the wrong format will return an error or empty data.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Specify a project ID or workflow ID when querying Jobs or Workflow jobs
* Check that your API token belongs to a user with access to the target project
* Use the Workflow jobs entity to auto-populate job numbers before pulling the Jobs entity
  {% endcolumn %}

{% column %}
**Don't**

* Leave the start date blank on large orgs — it will try to pull all history
* Share your personal API token across team members or store it in a shared doc
* Query Contexts data unless your token belongs to an org admin account
  {% endcolumn %}
  {% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/project-management/circleci/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.