Flows

GET /v1/flows returns directed origin-to-destination flow rows for a region filter. Use it for questions like “where are Williamson County’s in-migrants coming from?” or “where are residents leaving Davidson County going?”

When period is omitted, the API uses the latest period_start available for the supplied filters and reports that date in meta.period.

Request


curl "https://api.creativeforesight.io/v1/flows?destination=47187&measure=agi&limit=3" \
  -H "Authorization: Bearer $CF_API_KEY"

Query parameters

Parameter	Type	Required	Description
`origin`	string	No	Origin region code. At least one of `origin` or `destination` is required.
`destination`	string	No	Destination region code. At least one of `origin` or `destination` is required.
`measure`	string	No	Flow measure, such as `agi`, `returns`, or `individuals`.
`period`	string	No	`period_start` date in `YYYY-MM-DD` format. Defaults to the latest available period for the filters.
`limit`	integer	No	Maximum rows to return. Defaults to `50` and caps at `500`.

Response


{
  "data": [
    {
      "origin": {
        "code": "47037",
        "name": "Davidson County"
      },
      "destination": {
        "code": "47187",
        "name": "Williamson County"
      },
      "measure": "agi",
      "period_start": "2022-01-01",
      "value": 250000
    }
  ],
  "meta": {
    "count": 1,
    "limit": 3,
    "period": "2022-01-01",
    "filters": {
      "destination": "47187",
      "measure": "agi"
    },
    "units": {
      "agi": "USD, thousands",
      "returns": "count",
      "individuals": "count"
    }
  }
}

value is reported exactly as published by the source. For IRS migration flow measures, agi values are thousands of USD; returns and individuals are counts.

Errors

Status	Code	Meaning
`400`	`INVALID_PARAMETER`	Required or optional query parameters are invalid, including missing both `origin` and `destination`.
`401`	`INVALID_API_KEY`	The request did not include a valid API key and was not a settled x402 request.
`404`	`RESOURCE_NOT_FOUND`	The requested origin or destination region was not found.
`429`	`RATE_LIMIT_EXCEEDED`	The API key exceeded its one-minute request limit.
`500`	`INTERNAL_ERROR`	Flow data could not be loaded.