Question: "In algebraic geometry, how often does a line bundle have a flat connection? When it has a flat connection, how many flat connections can it have?"
Comment: Over other fields/rings than the complex number field you get similar results using basic properties of the $\operatorname{Ext}$ and $\operatorname{Hom}$ functors: If $\pi: X \rightarrow S:=Spec(A)$ is any scheme and if $L\in Pic(X)$ is any invertible sheaf, there is the Atiyah-sequence
$$A1.\text{ } 0 \rightarrow \Omega^1_{X/S} \otimes L \rightarrow J^1(L) \rightarrow L \rightarrow 0$$
which is split iff $L$ has a connection. You get an extension class
$$a(L) \in \operatorname{Ext}^1_{\mathcal{O}_X}(L, L\otimes \Omega^1_{X/S}) \cong $$
$$ \operatorname{Ext}^1_{\mathcal{O}_X}(\mathcal{O}_X, L^*\otimes L\otimes \Omega^1_{X/S}) \cong \operatorname{Ext}^1_{\mathcal{O}_X}( \mathcal{O}_X, \Omega^1_{X/S}) \cong $$
$$ \operatorname{H}^1(X, \Omega^1_{X/S}).$$
You may view the image of the class $a(L)=c_1(L)$ under the above isomorphisms as the first Chern class of $L$. Hence $c_1(L)=0$ iff $L$ has a connection. The set of connections on $L$ is parametrized by the set
$$\operatorname{Hom}_{\mathcal{O}_X}(L, L \otimes \Omega^1_{X/S}) \cong $$
$$\operatorname{Hom}_{\mathcal{O}_X}(\mathcal{O}_X,\operatorname{Hom}_{\mathcal{O}_X}(L, L \otimes \Omega^1_{X/S})) \cong $$
$$\operatorname{Hom}_{\mathcal{O}_X}(\mathcal{O}_X, L^*\otimes L \otimes \Omega^1_{X/S}) \cong $$
$$\operatorname{Hom}_{\mathcal{O}_X}(\mathcal{O}_X, \Omega^1_{X/S}) \cong \operatorname{H}^0(X, \Omega^1_{X/S}).$$
More generally if $E$ is any locally trivial finite rank sheaf you get a class
$$a(E) \in \operatorname{H}^1(X, \operatorname{End}_{\mathcal{O}_X}(E) \otimes \Omega^1_{X/S}).$$
with the same properties. The "parameter-space of connections" is the set
$$\operatorname{H}^0(X, \operatorname{End}_{\mathcal{O}_X}(E) \otimes \Omega^1_{X/S}).$$
Remark: You may let $S$ be any base-scheme and the above results still hold.
The following link gives an obstruction sequence for a general $E$ to have a flat connection using non-abelian extensions of (sheaves of) Lie-Rinehart algebras:
When do flat holomorphic connections exist?
When $E$ is a locally trivial finite rank sheaf with a connection $\nabla$, there is an exact sequence
$$0 \rightarrow \operatorname{End}_{\mathcal{O}_X}(E) \rightarrow \Theta_X(E, \nabla) \rightarrow \Theta_X \rightarrow 0$$
which splits iff $E$ has a flat connection. By definition
$$ \Theta_X(E, \nabla):= \operatorname{End}_{\mathcal{O}_X}(E)\oplus \Theta_X$$
with the following Lie-structure:
If $x,y \in \Theta(U)$ and $\phi, \psi \in \operatorname{End}_{\mathcal{O}_X}(E)(U)$, define
$$ [(\phi,x),(\psi,y)]:=([\phi,\psi]+[\nabla(x), \psi]-[\nabla(y), \phi]+R_{\nabla}(x,y), [x,y]),$$
where $R_{\nabla}$ is the curvature of $\nabla$.
Note: When you add a potential $P$ to a flat connection $\nabla$, it does not follow that the new connection $\nabla+P$ is flat.
Example: If $X\subseteq \mathbb{P}^n_{\mathbb{C}}$ is a smooth quasi projective variety with a finite rank locally trivial sheaf $E$ with an algebraic connection $\nabla$, you get an extension class
$$na(E,\nabla) \in \operatorname{Ext}^1(\Theta_X, \operatorname{End}_{\mathcal{O}_X}(E))$$
and there is a canonical map
$$c:\operatorname{Ext}^1(\Theta_X, \operatorname{End}_{\mathcal{O}_X}(E)) \rightarrow \operatorname{H}^1(X, \operatorname{End}_{\mathcal{O}_X}(E) \otimes \Omega^1_X),$$
with $na(E,\nabla)="0"$ iff $E$ has a flat algebraic connection $\nabla':=\nabla+P$. The two classes $c(na(E,\nabla))$ and $a(E)$ live in the same vector space. One may wonder if these two classes are related: If $c(na(E,\nabla))$ is a multiple of $a(E)$, it follows $a(E)=0$ may imply $na(E,\nabla)=0$. The "non-abelian cohomology set"
$$\operatorname{Ext}^1(\Theta_X, \operatorname{End}_{\mathcal{O}_X}(E))$$
does not have the structure of an abelian group in general. I believe it has been conjectured that if $a(E)=0$ it follows $na(E,\nabla)=0$ but do not have a precise reference.
Example: For a line bundle it follows $\operatorname{End}(L) \cong \mathcal{O}_X$ and you get an exact sequence
$$NA.\text{ }0 \rightarrow \mathcal{O}_X \rightarrow \Theta_X(L, \nabla) \rightarrow \Theta_X \rightarrow 0.$$
By the above argument it follows this sequence splits over the complex numbers.
Example: Let for simplicity $L\in \operatorname{Pic}(A)$ be an invertible $A$-module with a connection $\nabla: T \rightarrow \operatorname{End}_k(L)$ with $T:=\operatorname{Der}_k(A)$.
Let $ad\nabla: T \rightarrow \operatorname{End}_k(L^* \otimes_A L) \cong \operatorname{End}_k(A)$.
It follows for any endomorphism $\phi_a \in L^*\otimes L$ we have
$$ad\nabla(x)(\phi_a)=\phi_{x(a)},$$
where $\phi_a(u):=au$ for $u\in L$. It follows $ad\nabla$ is a flat connection. We get an extension
$$NA1.\text{ } 0 \rightarrow L^* \otimes L \rightarrow L^* \otimes L \oplus T \rightarrow^p T \rightarrow 0$$
where the middle term has the following Lie structure:
$$[(a,x),(b,y)]:=(x(b)-y(a) +R_{\nabla}(x,y),[x,y])$$
for $a,b\in L^* \otimes L, x,y \in T$.
Lemma: A section $s: T\rightarrow A\oplus T$
with $s(x):=(\rho(x),x)$ is $A$-linear and a map of $k$-Lie algebras iff the map $\nabla^*:=\nabla+\rho$ is a flat connection.
Hence sequence $A1$ is the obstruction for the existence of a connection and $NA1$ is the obstruction for the existence of a flat connection.
If $(L,\nabla)$ is a flat connection on a line bundle $L$ it follows sections $\rho$ of $NA$ are in 1-1 correspondence with flat connections $\nabla^*:=\nabla+\rho$. Hence you may view the "set of sections" of $NA$ as the "parameter-space of flat connections". There is an algebraic group/a group scheme acting on this parameter space and you may form the "(stack) quotient".
If $X$ is a complex projective manifold it follows $NA$ should have a section for any $L\in Pic(X)$.
Note: Let $X \subseteq \mathbb{P}^n_S$ be projective over $S:=Spec(A)$ with $A$ a finitely generated algebra over a field $k$ and let $E$ be a coherent $\mathcal{O}_X$-module. It follows
$$\operatorname{H}^0(X, \operatorname{End}(E)\otimes \Omega^1_{X/S})$$
is a finitely generated $A$-module. This is Hartshorne, Thm II.5.19. In particular if $A$ equals $k$, it follows the group is a finite dimensional $k$-vector space.
Note: The field $k$ may be arbitrary, hence the results are valid for a real algebraic variety $X$ and a finite rank vector bundle $E$ on $X$. The "Serre-Swan theorem" gives an equivalence of categories between the category of real smooth finite rank vector bundles on a real smooth manifold $M$ and finite rank projective $R:=C^{\infty}(M)$-modules. The ring $R$ is a commutative unital algebra over the field of real numbers, and the sequences $A1,NA1$ exist for any $R$-module $L$.